nofx/DOCKER_DEPLOY.md

🐳 Docker 一键部署教程

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

📋 前置要求

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

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

安装 Docker

macOS / Windows

下载并安装 Docker Desktop

Linux (Ubuntu/Debian)

# 安装 Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

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

# 验证安装
docker --version
docker-compose --version

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

第 1 步：准备配置文件

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

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

必须配置的字段：

{
  "traders": [
    {
      "id": "my_trader",
      "name": "My AI Trader",
      "ai_model": "deepseek",
      "binance_api_key": "YOUR_BINANCE_API_KEY",       // ← 填入你的币安 API Key
      "binance_secret_key": "YOUR_BINANCE_SECRET_KEY", // ← 填入你的币安 Secret Key
      "deepseek_key": "YOUR_DEEPSEEK_API_KEY",         // ← 填入你的 DeepSeek API Key
      "initial_balance": 1000.0,
      "scan_interval_minutes": 3
    }
  ],
  "use_default_coins": true,
  "api_server_port": 8080
}

第 2 步：一键启动

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

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

启动过程说明：

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

第 3 步：访问系统

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

• Web 界面: http://localhost:3000
• API 文档: http://localhost:8080/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/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. 不要将 config.json 提交到 Git

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

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

   # docker-compose.yml
   services:
     backend:
       environment:
         - BINANCE_API_KEY=${BINANCE_API_KEY}
         - BINANCE_SECRET_KEY=${BINANCE_SECRET_KEY}
   

3. 限制 API 访问

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

4. 定期更新镜像

   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。