nofx/docs/getting-started/docker-deploy.zh-CN.md

🐳 Docker 一键部署教程

本教程将指导你使用 Docker 快速部署 NOFX AI 交易竞赛系统。

📋 前置要求

在开始之前，请确保你的系统已安装：

• Docker: 版本 20.10 或更高
• Docker Compose: 版本 2.0 或更高

安装 Docker

提示：Docker Compose 版本说明

新用户建议：

• 推荐使用 Docker Desktop：自动包含最新 Docker Compose，无需单独安装
• 安装简单，一键搞定，提供图形界面管理
• 支持 macOS、Windows、部分 Linux 发行版

旧用户提醒：

• 弃用独立 docker-compose：不再推荐下载独立的 Docker Compose 二进制文件
• 使用内置版：Docker 20.10+ 自带 docker compose 命令（注意是空格）
• 如果还在使用旧的 docker-compose，请升级到新语法

macOS / Windows

下载并安装 Docker Desktop

安装后验证：

docker --version
docker compose --version  # 注意：使用空格，不再是连字符

Linux (Ubuntu/Debian)

推荐方式：使用 Docker Desktop（如果可用）或 Docker CE

# 安装 Docker (自动包含 compose)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 将当前用户加入 docker 组
sudo usermod -aG docker $USER
newgrp docker

# 验证安装（新命令）
docker --version
docker compose --version  # Docker 24+ 自带，无需单独安装

🚀 快速开始（3步完成部署）

第 1 步：准备配置文件

# 复制配置文件模板
cp config.json.example config.json

# 编辑配置文件，填入你的 API 密钥
nano config.json  # 或使用其他编辑器

必须配置的字段：

{
  "use_default_coins": true,
  "api_server_port": 8081,
  "jwt_secret": "YOUR_JWT_SECRET_CHANGE_IN_PRODUCTION"  // ← 填入一个长随机字符串作为JWT密钥
}

⚠️ 重要安全提醒：

• jwt_secret 字段是用户认证系统的关键安全配置
• 必须设置一个长度至少32位的随机字符串
• 在生产环境中，建议使用64位以上的随机字符串
• 可以使用命令生成：openssl rand -base64 64

配置说明：

• 🔐 用户认证：系统现在支持用户注册登录，每个用户都有独立的AI模型和交易所配置
• 🚫 移除traders配置：不再需要在config.json中预配置交易员，用户可以通过Web界面创建
• 🔑 JWT密钥：用于保护用户会话安全，强烈建议在生产环境中设置复杂密钥

第 2 步：一键启动

# 构建并启动所有服务（首次运行）
docker compose up -d --build

# 后续启动（不重新构建）
docker compose up -d

启动过程说明：

• --build: 构建 Docker 镜像（首次运行或代码更新后使用）
• -d: 后台运行（detached mode）

第 3 步：访问系统

部署成功后，打开浏览器访问：

• Web 界面: http://localhost:3000
• API 文档: http://localhost:8080/api/health

📊 服务管理

查看运行状态

# 查看所有容器状态
docker compose ps

# 查看服务健康状态
docker compose ps --format json | jq

查看日志

# 查看所有服务日志
docker compose logs -f

# 只查看后端日志
docker compose logs -f backend

# 只查看前端日志
docker compose logs -f frontend

# 查看最近 100 行日志
docker compose logs --tail=100

停止服务

# 停止所有服务（保留数据）
docker compose stop

# 停止并删除容器（保留数据）
docker compose down

# 停止并删除容器和卷（清除所有数据）
docker compose down -v

重启服务

# 重启所有服务
docker compose restart

# 只重启后端
docker compose restart backend

# 只重启前端
docker compose restart frontend

更新服务

# 拉取最新代码
git pull

# 重新构建并重启
docker compose up -d --build

🔧 高级配置

修改端口

编辑 docker-compose.yml，修改端口映射：

services:
  backend:
    ports:
      - "8080:8080"  # 改为 "你的端口:8080"

  frontend:
    ports:
      - "3000:80"    # 改为 "你的端口:80"

资源限制

在 docker-compose.yml 中添加资源限制：

services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

环境变量

创建 .env 文件来管理环境变量：

# .env
TZ=Asia/Shanghai
BACKEND_PORT=8080
FRONTEND_PORT=3000

然后在 docker-compose.yml 中使用：

services:
  backend:
    ports:
      - "${BACKEND_PORT}:8080"

📁 数据持久化

系统会自动持久化以下数据到本地目录：

• ./decision_logs/: AI 决策日志
• ./coin_pool_cache/: 币种池缓存
• ./config.json: 配置文件（挂载）

数据位置：

# 查看数据目录
ls -la decision_logs/
ls -la coin_pool_cache/

# 备份数据
tar -czf backup_$(date +%Y%m%d).tar.gz decision_logs/ coin_pool_cache/ config.json

# 恢复数据
tar -xzf backup_20241029.tar.gz

🐛 故障排查

容器无法启动

# 查看详细错误信息
docker compose logs backend
docker compose logs frontend

# 检查容器状态
docker compose ps -a

# 重新构建（清除缓存）
docker compose build --no-cache

端口被占用

# 查找占用端口的进程
lsof -i :8080  # 后端端口
lsof -i :3000  # 前端端口

# 杀死占用端口的进程
kill -9 <PID>

配置文件未找到

# 确保 config.json 存在
ls -la config.json

# 如果不存在，复制模板
cp config.json.example config.json

健康检查失败

# 检查健康状态
docker inspect nofx-backend | jq '.[0].State.Health'
docker inspect nofx-frontend | jq '.[0].State.Health'

# 手动测试健康端点
curl http://localhost:8080/api/health
curl http://localhost:3000/health

前端无法连接后端

# 检查网络连接
docker compose exec frontend ping backend

# 检查后端服务是否正常
docker compose exec frontend wget -O- http://backend:8080/health

清理 Docker 资源

# 清理未使用的镜像
docker image prune -a

# 清理未使用的卷
docker volume prune

# 清理所有未使用的资源（慎用）
docker system prune -a --volumes

🔐 安全建议

1. JWT密钥安全配置

   # 生成强随机JWT密钥
   openssl rand -base64 64
   
   # 或者使用其他工具生成
   head -c 64 /dev/urandom | base64
   

   JWT密钥要求：

   • 长度至少32位，推荐64位以上
   • 使用随机生成的字符串
   • 在生产环境中绝不使用默认值
   • 定期更换（会使现有用户需要重新登录）

2. 不要将 config.json 提交到 Git

   # ~~确保 config.json 在 .gitignore 中~~
   # ~~echo "config.json" >> .gitignore~~
   

   注意：现在使用trading.db数据库，请确保不提交敏感数据

3. 使用环境变量存储敏感信息

   # docker-compose.yml
   services:
     backend:
       environment:
         - JWT_SECRET=${JWT_SECRET}
       # 用户的API密钥现在通过Web界面配置，不再需要环境变量
   

4. 限制 API 访问

   # 只允许本地访问
   services:
     backend:
       ports:
         - "127.0.0.1:8080:8080"
   

5. 定期更新镜像

   docker compose pull
   docker compose up -d
   

🌐 生产环境部署

使用 Nginx 反向代理

# /etc/nginx/sites-available/nofx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api/ {
        proxy_pass http://localhost:8080/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

配置 HTTPS (Let's Encrypt)

# 安装 Certbot
sudo apt-get install certbot python3-certbot-nginx

# 获取 SSL 证书
sudo certbot --nginx -d your-domain.com

# 自动续期
sudo certbot renew --dry-run

使用 Docker Swarm (集群部署)

# 初始化 Swarm
docker swarm init

# 部署堆栈
docker stack deploy -c docker-compose.yml nofx

# 查看服务状态
docker stack services nofx

# 扩展服务
docker service scale nofx_backend=3

📈 监控与日志

日志管理

# 配置日志轮转（已在 docker-compose.yml 中配置）
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

# 查看日志统计
docker compose logs --timestamps | wc -l

监控工具集成

可以集成 Prometheus + Grafana 进行监控：

# docker-compose.yml (添加监控服务)
services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana
    ports:
      - "3001:3000"

🆘 获取帮助

• GitHub Issues: 提交问题
• 文档: 查看 README.md
• 社区: 加入我们的 Discord/Telegram 群组

📝 常用命令速查表

# 启动
docker compose up -d --build       # 构建并启动
docker compose up -d               # 启动（不重新构建）

# 停止
docker compose stop                # 停止服务
docker compose down                # 停止并删除容器
docker compose down -v             # 停止并删除容器和数据

# 查看
docker compose ps                  # 查看状态
docker compose logs -f             # 查看日志
docker compose top                 # 查看进程

# 重启
docker compose restart             # 重启所有服务
docker compose restart backend     # 重启后端

# 更新
git pull && docker compose up -d --build

# 清理
docker compose down -v             # 清除所有数据
docker system prune -a             # 清理 Docker 资源

---

🎉 恭喜！你已经成功部署了 NOFX AI 交易竞赛系统！

如有问题，请查看故障排查部分或提交 Issue。