Feat: Update docs

- 重构文档结构 - 更新文档内容 - 制定roadmap - 提供中/EN 双语文档
2026-06-04 09:58:22 +08:00 · 2025-11-01 15:05:24 -04:00
parent ba35d29eee
commit fcacfbd79d
36 changed files with 5756 additions and 1149 deletions
@@ -0,0 +1,489 @@
+# 🐳 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](https://www.docker.com/products/docker-desktop/)
+
+**安装后验证：**
+```bash
+docker --version
+docker compose --version  # 注意：使用空格，不再是连字符
+```
+
+#### Linux (Ubuntu/Debian)
+**推荐方式：使用 Docker Desktop（如果可用）或 Docker CE**
+
+```bash
+# 安装 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 步：准备配置文件
+
+```bash
+# 复制配置文件模板
+cp config.example.jsonc config.json
+
+# 编辑配置文件，填入你的 API 密钥
+nano config.json  # 或使用其他编辑器
+```
+
+**必须配置的字段：**
+```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 步：一键启动
+
+```bash
+# 构建并启动所有服务（首次运行）
+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
+
+## 📊 服务管理
+
+### 查看运行状态
+```bash
+# 查看所有容器状态
+docker compose ps
+
+# 查看服务健康状态
+docker compose ps --format json | jq
+```
+
+### 查看日志
+```bash
+# 查看所有服务日志
+docker compose logs -f
+
+# 只查看后端日志
+docker compose logs -f backend
+
+# 只查看前端日志
+docker compose logs -f frontend
+
+# 查看最近 100 行日志
+docker compose logs --tail=100
+```
+
+### 停止服务
+```bash
+# 停止所有服务（保留数据）
+docker compose stop
+
+# 停止并删除容器（保留数据）
+docker compose down
+
+# 停止并删除容器和卷（清除所有数据）
+docker compose down -v
+```
+
+### 重启服务
+```bash
+# 重启所有服务
+docker compose restart
+
+# 只重启后端
+docker compose restart backend
+
+# 只重启前端
+docker compose restart frontend
+```
+
+### 更新服务
+```bash
+# 拉取最新代码
+git pull
+
+# 重新构建并重启
+docker compose up -d --build
+```
+
+## 🔧 高级配置
+
+### 修改端口
+
+编辑 `docker-compose.yml`，修改端口映射：
+
+```yaml
+services:
+  backend:
+    ports:
+      - "8080:8080"  # 改为 "你的端口:8080"
+
+  frontend:
+    ports:
+      - "3000:80"    # 改为 "你的端口:80"
+```
+
+### 资源限制
+
+在 `docker-compose.yml` 中添加资源限制：
+
+```yaml
+services:
+  backend:
+    deploy:
+      resources:
+        limits:
+          cpus: '2'
+          memory: 2G
+        reservations:
+          cpus: '1'
+          memory: 1G
+```
+
+### 环境变量
+
+创建 `.env` 文件来管理环境变量：
+
+```bash
+# .env
+TZ=Asia/Shanghai
+BACKEND_PORT=8080
+FRONTEND_PORT=3000
+```
+
+然后在 `docker-compose.yml` 中使用：
+
+```yaml
+services:
+  backend:
+    ports:
+      - "${BACKEND_PORT}:8080"
+```
+
+## 📁 数据持久化
+
+系统会自动持久化以下数据到本地目录：
+
+- `./decision_logs/`: AI 决策日志
+- `./coin_pool_cache/`: 币种池缓存
+- `./config.json`: 配置文件（挂载）
+
+**数据位置：**
+```bash
+# 查看数据目录
+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
+```
+
+## 🐛 故障排查
+
+### 容器无法启动
+
+```bash
+# 查看详细错误信息
+docker compose logs backend
+docker compose logs frontend
+
+# 检查容器状态
+docker compose ps -a
+
+# 重新构建（清除缓存）
+docker compose build --no-cache
+```
+
+### 端口被占用
+
+```bash
+# 查找占用端口的进程
+lsof -i :8080  # 后端端口
+lsof -i :3000  # 前端端口
+
+# 杀死占用端口的进程
+kill -9 <PID>
+```
+
+### 配置文件未找到
+
+```bash
+# 确保 config.json 存在
+ls -la config.json
+
+# 如果不存在，复制模板
+cp config.example.jsonc config.json
+```
+
+### 健康检查失败
+
+```bash
+# 检查健康状态
+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
+```
+
+### 前端无法连接后端
+
+```bash
+# 检查网络连接
+docker compose exec frontend ping backend
+
+# 检查后端服务是否正常
+docker compose exec frontend wget -O- http://backend:8080/health
+```
+
+### 清理 Docker 资源
+
+```bash
+# 清理未使用的镜像
+docker image prune -a
+
+# 清理未使用的卷
+docker volume prune
+
+# 清理所有未使用的资源（慎用）
+docker system prune -a --volumes
+```
+
+## 🔐 安全建议
+
+1. **JWT密钥安全配置**
+   ```bash
+   # 生成强随机JWT密钥
+   openssl rand -base64 64
+   
+   # 或者使用其他工具生成
+   head -c 64 /dev/urandom | base64
+   ```
+   
+   **JWT密钥要求：**
+   - 长度至少32位，推荐64位以上
+   - 使用随机生成的字符串
+   - 在生产环境中绝不使用默认值
+   - 定期更换（会使现有用户需要重新登录）
+
+2. ~~**不要将 config.json 提交到 Git**~~
+   ```bash
+   # ~~确保 config.json 在 .gitignore 中~~
+   # ~~echo "config.json" >> .gitignore~~
+   ```
+   
+   *注意：现在使用trading.db数据库，请确保不提交敏感数据*
+
+3. **使用环境变量存储敏感信息**
+   ```yaml
+   # docker-compose.yml
+   services:
+     backend:
+       environment:
+         - JWT_SECRET=${JWT_SECRET}
+       # 用户的API密钥现在通过Web界面配置，不再需要环境变量
+   ```
+
+4. **限制 API 访问**
+   ```yaml
+   # 只允许本地访问
+   services:
+     backend:
+       ports:
+         - "127.0.0.1:8080:8080"
+   ```
+
+4. **定期更新镜像**
+   ```bash
+   docker compose pull
+   docker compose up -d
+   ```
+
+## 🌐 生产环境部署
+
+### 使用 Nginx 反向代理
+
+```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)
+
+```bash
+# 安装 Certbot
+sudo apt-get install certbot python3-certbot-nginx
+
+# 获取 SSL 证书
+sudo certbot --nginx -d your-domain.com
+
+# 自动续期
+sudo certbot renew --dry-run
+```
+
+### 使用 Docker Swarm (集群部署)
+
+```bash
+# 初始化 Swarm
+docker swarm init
+
+# 部署堆栈
+docker stack deploy -c docker-compose.yml nofx
+
+# 查看服务状态
+docker stack services nofx
+
+# 扩展服务
+docker service scale nofx_backend=3
+```
+
+## 📈 监控与日志
+
+### 日志管理
+
+```bash
+# 配置日志轮转（已在 docker-compose.yml 中配置）
+logging:
+  driver: "json-file"
+  options:
+    max-size: "10m"
+    max-file: "3"
+
+# 查看日志统计
+docker compose logs --timestamps | wc -l
+```
+
+### 监控工具集成
+
+可以集成 Prometheus + Grafana 进行监控：
+
+```yaml
+# 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**: [提交问题](https://github.com/yourusername/open-nofx/issues)
+- **文档**: 查看 [README.md](README.md)
+- **社区**: 加入我们的 Discord/Telegram 群组
+
+## 📝 常用命令速查表
+
+```bash
+# 启动
+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。