Docker 部署指南
使用 Docker 快速部署 GEO Wiki Pro 到本地或服务器的完整指南
# Docker 部署指南
> 使用 Docker 一键部署 GEO Wiki Pro，支持本地开发和服务器生产环境
---
## 📋 前置条件
| 条件 | 最低要求 |
|------|----------|
| 操作系统 | Linux / macOS / Windows (WSL2) |
| Docker | 20.10+ |
| Docker Compose | v2.0+ |
| 内存 | 1GB+ |
| 磁盘空间 | 500MB+ |
---
## 🚀 快速部署（3 步完成）
### 第 1 步：克隆项目
```bash
git clone https://github.com/your-org/geo-wiki-pro.git
cd geo-wiki-pro
```
### 第 2 步：配置环境变量
```bash
cp .env.example .env
```
编辑 `.env` 文件，设置必要参数：
```env
# 必填：JWT 密钥（至少 32 个字符）
JWT_SECRET=your-super-secret-key-here
# 可选配置
PORT=3002
CORS_ORIGINS=http://localhost:3000
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=300
```
::: warning
请务必设置一个强随机的 `JWT_SECRET`。生产环境中不要使用默认值。
:::
### 第 3 步：启动服务
```bash
docker compose up -d
```
验证服务状态：
```bash
curl http://localhost:3002/api/v1/health
```
预期输出：
```json
{
"status": "ok",
"version": "2.9.0"
}
```
---
## 🏗️ 架构说明
GEO Wiki Pro 采用前后端分离架构：
```
┌─────────────────┐ ┌─────────────────┐
│ Nginx │────▶│ Express.js │
│ (静态前端) │ │ (API 后端) │
│ 端口: 80/443 │ │ 端口: 3002 │
└─────────────────┘ └─────────────────┘
│
▼
┌─────────────┐
│ 文件系统 │
│ data/ │
│ public/ │
└─────────────┘
```
### 服务组件
| 组件 | 说明 | 端口 |
|------|------|------|
| Nginx | 反向代理 + 静态文件服务 | 80/443 |
| Express.js | API 服务器 | 3002 |
| 文件存储 | Markdown 文档 + 媒体文件 | - |
---
## ⚙️ 高级配置
### 自定义端口
修改 `docker-compose.yml` 中的端口映射：
```yaml
services:
api:
ports:
- "8080:3002" # 外部端口:内部端口
```
### 挂载数据目录
将数据持久化到宿主机：
```yaml
services:
api:
volumes:
- ./data:/app/data
- ./public/media:/app/public/media
```
### 配置 HTTPS
在生产环境中，建议使用反向代理配置 HTTPS：
```nginx
server {
listen 443 ssl;
server_name wiki.example.com;
ssl_certificate /etc/ssl/certs/wiki.example.com.pem;
ssl_certificate_key /etc/ssl/private/wiki.example.com.key;
location / {
proxy_pass http://localhost:3002;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
---
## 🔒 安全配置
### 首次登录
部署完成后，系统会自动创建管理员账号：
1. 访问 `http://your-server:3002/login`
2. 使用默认管理员账号登录
3. **立即修改默认密码**
### 环境变量安全
| 变量 | 说明 | 安全建议 |
|------|------|----------|
| `JWT_SECRET` | JWT 签名密钥 | 使用 `openssl rand -base64 32` 生成 |
| `CORS_ORIGINS` | 允许的跨域来源 | 生产环境限制为实际域名 |
| `RATE_LIMIT_*` | 限流配置 | 根据预期访问量调整 |
::: danger
永远不要将 `.env` 文件提交到版本控制系统（Git）。确保 `.gitignore` 中包含 `.env`。
:::
---
## 🐛 常见问题
### 容器启动失败
```bash
# 查看日志
docker compose logs api
# 常见原因：
# 1. .env 文件未配置 JWT_SECRET
# 2. 端口被占用
# 3. Docker 权限不足
```
### 数据持久化
```bash
# 检查数据目录
ls -la data/
# 备份数据
tar -czf backup-$(date +%Y%m%d).tar.gz data/ public/media/
```
### 更新版本
```bash
# 拉取最新代码
git pull origin main
# 重新构建并启动
docker compose down
docker compose build --no-cache api
docker compose up -d
```
---
## 📊 监控与维护
### 健康检查
```bash
# API 健康状态
curl http://localhost:3002/api/v1/health
# Docker 容器状态
docker compose ps
```
### 日志查看
```bash
# 实时日志
docker compose logs -f api
# 最近 100 行日志
docker compose logs --tail 100 api
```
---
## 📚 下一步
- [创建第一个知识库](/docs/first-knowledge-base) - 从零搭建产品知识库
- [快速入门指南](/docs/quick-start) - 5 分钟快速上手产品开发
- [FAQ](/docs/faq) - 常见问题解答
---
*最后更新: 2026-05-26 | 版本: v2.9.0*