Docker 部署指南
面向已购买 GEO Wiki Pro 商业授权的客户，介绍生产环境的标准 Docker 部署流程
> ⚠️ **付费客户专属文档**
>
> 本文档面向**已购买 GEO Wiki Pro 商业授权**的客户。如果您还未购买，请先联系商务获取授权：
>
> 📧 [[email protected]](mailto:[email protected])
>
> 购买后您将获得：完整源码包、部署文档、技术支持、版本升级、定制开发。
---
## 📋 前置条件
在开始部署前，请确保您的服务器满足以下条件：
| 条件 | 最低要求 | 推荐配置 |
|------|----------|----------|
| 操作系统 | Linux (Ubuntu 22.04+ / CentOS 8+ / Debian 11+) | Ubuntu 22.04 LTS |
| Docker | 20.10+ | 24.0+ |
| Docker Compose | v2.0+ | v2.20+ |
| CPU | 1 核 | 2 核+ |
| 内存 | 1GB | 2GB+ |
| 磁盘空间 | 500MB | 5GB+（含备份空间）|
| 公网带宽 | 1 Mbps | 5 Mbps+（取决于访问量）|
> 💡 商务客户如需服务器选型建议或云厂商折扣，请联系 [[email protected]](mailto:[email protected])。
---
## 🚀 快速部署（4 步完成）
### 第 1 步：上传并解压源码包
将您购买后获取的源码包上传到服务器（使用 SFTP 或 scp），然后解压：
```bash
# 创建项目目录
sudo mkdir -p /opt/geowiki-pro
sudo chown $USER:$USER /opt/geowiki-pro
# 上传源码包到该目录后，解压
cd /opt/geowiki-pro
tar -xzf geowiki-pro-source.tar.gz
# 查看解压结果
ls -la
```
### 第 2 步：配置环境变量
```bash
# 复制环境变量模板
cp .env.example .env
# 编辑 .env 文件（必填项）
nano .env
```
**必填配置**：
```bash
# JWT 密钥（至少 32 个字符，建议用 openssl 生成）
JWT_SECRET=<your-secure-random-secret>
# 服务端口（默认 3002，可按需修改）
PORT=3002
# 数据存储路径（建议用绝对路径）
DATA_DIR=/opt/geowiki-pro/data
```
**生成安全的 JWT 密钥**：
```bash
openssl rand -base64 48
```
### 第 3 步：启动服务
```bash
# 启动所有服务（后台运行）
docker-compose up -d
# 查看启动状态
docker-compose ps
# 查看实时日志
docker-compose logs -f
```
### 第 4 步：验证部署
```bash
# 检查 API 健康状态
curl https://your-domain.com/api/v1/health
# 访问管理后台
# 浏览器打开：https://your-domain.com/admin
# 默认账号：admin（首次登录会强制要求修改密码）
```
> ✅ 如果健康检查返回 `{"success": true}`，说明部署成功！
---
## 🏗️ 架构说明
### 服务组件
| 服务 | 端口 | 说明 |
|------|------|------|
| Web 前端 | 3002 | React SPA，文档展示界面 |
| API 服务 | 3002（同端口）| Node.js 后端，提供 REST API |
| 数据存储 | - | 文件系统存储（`data/docs/`, `data/db.json`）|
整个系统采用单容器部署，简化运维。
---
## ⚙️ 高级配置
### 自定义端口
如需修改默认端口（3002），编辑 `.env`：
```bash
PORT=8080
```
同时修改 `docker-compose.yml` 中的端口映射：
```yaml
ports:
- "8080:3002" # 外部端口:内部端口
```
### 挂载数据目录
为了数据安全和备份便利，建议将数据目录挂载到宿主机：
```yaml
volumes:
- ./data:/app/data
- ./public/media:/app/public/media
- ./logs:/app/logs
```
### 配置 HTTPS（推荐）
生产环境强烈建议使用 HTTPS。两种方案：
**方案 A：使用 Nginx 反向代理 + Let's Encrypt**
```nginx
server {
listen 443 ssl http2;
server_name geowiki.pro;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:3002;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
**方案 B：使用 Cloudflare 反向代理**（零配置 SSL）
将域名 DNS 指向 Cloudflare，开启代理模式即可。
---
## 🔒 安全配置
### 首次登录
1. 使用默认账号 `admin` 登录
2. **系统会强制要求修改密码**（密码至少 8 位）
3. 立即在管理后台修改默认管理员邮箱
### 环境变量安全
```bash
# 设置 .env 文件权限（仅 owner 可读写）
chmod 600 .env
# 永远不要将 .env 提交到 Git
echo ".env" >> .gitignore
```
### 定期更新 JWT 密钥
建议每 90 天轮换一次 JWT 密钥（商务客户可联系技术支持协助）。
---
## 🐛 常见问题
### 容器启动失败
```bash
# 查看详细日志
docker-compose logs api
# 常见原因：
# 1. .env 文件未配置 JWT_SECRET（必须至少 32 字符）
# 2. 端口被占用：lsof -i :3002
# 3. Docker 权限不足：sudo usermod -aG docker $USER
```
### 数据备份
```bash
# 手动备份（建议配合 cron 定时执行）
tar -czf backup-$(date +%Y%m%d).tar.gz data/
# 商务客户可联系技术支持获取自动化备份方案
```
### 升级到新版本
```bash
# 1. 停止当前服务
docker-compose down
# 2. 备份数据（重要！）
tar -czf backup-before-upgrade.tar.gz data/
# 3. 解压新版本源码包
tar -xzf geowiki-pro-vNEW.tar.gz
# 4. 启动新版本
docker-compose up -d
# 5. 验证
curl https://your-domain.com/api/v1/health
```
> 💡 商务客户升级前可联系 [[email protected]](mailto:[email protected]) 获取升级指南和兼容性说明。
---
## 📊 监控与维护
### 健康检查
```bash
# API 健康状态
curl https://your-domain.com/api/v1/health
# Docker 容器状态
docker-compose ps
```
### 日志查看
```bash
# 实时日志
docker-compose logs -f
# 最近 100 行日志
docker-compose logs --tail=100
```
### 性能监控建议
商务客户推荐使用以下监控工具：
- **UptimeRobot**（免费）：HTTP 健康检查 + 宕机告警
- **Prometheus + Grafana**（高级）：完整指标监控
- 商务客户可联系技术支持获取定制监控方案
---
## 🆘 技术支持
### 商务客户专属支持
- 📧 **邮箱**：[[email protected]](mailto:[email protected])
- 📞 **电话**：（商务客户专属）
- 💬 **微信群**：（购买后邀请加入）
- 🕐 **响应时间**：工作日 4 小时内首次响应
### 自助资源
- 📖 [用户手册](/docs/geo-wiki-pro-user-manual)
- ❓ [FAQ](/docs/faq)
- 🛠️ [CLI 工具](/docs/cli-reference)
---
## 📚 下一步
部署完成后，建议您：
1. **配置 HTTPS**（安全必需）
2. **设置自动备份**（数据安全）
3. **配置监控告警**（可用性保障）
4. **加入商务客户微信群**（技术支持 + 版本更新通知）
5. **阅读 [用户手册](/docs/geo-wiki-pro-user-manual)** 了解更多功能
欢迎使用 GEO Wiki Pro！如有任何问题，请随时联系商务团队 🎉