quantmind-deploy

> ⚙️ 本技能遵循公共运行环境契约（最高优先级，先于本文其余内容执行）： > 详见 [_shared/env-contract.md](../_shared/env-contract.md)，执行前先读它。 # QuantMind 部署技能 QuantMind 部署运维完整指南。覆盖**部署前准备 → 一键/手动部署 → 部署后检查 → 问题排查 → 更新 → 云端训练**全流程。本技能针对 AI 编程助手编写，每步都给出可直接执行的命令与判断标准，避免"不知道下一步"卡壳。 ## 0. 安装技能包（让 AI 帮你部署） 本技能包兼容**主流 AI 编程工具**（Claude Code / Codex / OpenCode / Trae / MarsCode 等），安装后 AI 能自动识别"部署/装不上"等意图并调用本技能指导部署。 ### 方式一：Claude Code / QuantBot（原生 SKILL.md） ```bash # 解压到 Claude Code 全局技能目录 unzip quantmind-operations-skill.zip -d ~/.claude/ # 验证 ls ~/.claude/skills/quantmind-deploy/SKILL.md ``` ### 方式二：从项目仓库安装（任何工具） ```bash # 项目根目录 skills/ 下即全部技能 cp -r /opt/quantmind/skills/* ~/.claude/skills/ ``` ### 方式三：其他主流 AI 工具（OpenCode / Codex / Trae / MarsCode 等） 各工具虽不原生识别 SKILL.md，但都读取 **AGENTS.md**（项目级指令）。把技能包要点导入即可： ```bash # ① 通用做法：把 SKILL.md 内容并入 AGENTS.md # 项目根创建/追加 AGENTS.md，把关键流程粘贴进去 cat ~/.claude/skills/quantmind-deploy/SKILL.md >> AGENTS.md # ② OpenAI Codex unzip quantmind-operations-skill.zip -d ~/.codex/ # Codex 读取 ~/.codex/AGENTS.md（把本技能要点放入） # ③ OpenCode unzip quantmind-operations-skill.zip -d ~/.config/opencode/ # 或在项目根 AGENTS.md 引用本技能要点 # ④ 腾讯 Trae / 字节 MarsCode # 克隆仓库后把 SKILL.md 要点写入项目 AGENTS.md，AI 即可按流程部署 ``` ### 让 AI 部署 安装技能后，直接对 AI 助手说： - "帮我部署 QuantMind" → AI 读取本技能，按"部署前准备→部署→检查"执行 - "部署不上，帮我排查" → AI 按"问题排查"诊断树逐项定位 - "一键部署" → AI 执行 `deploy/full-deploy.sh` ### 推荐编程工具（部署环境） | 工具 | 用途 | 说明 | | ------------------------- | ---------- | ----------------------- | | **Claude Code** | AI 编程/部署助手 | 原生支持 SKILL.md，装技能包即自动识别 | | **OpenCode** | AI 编程助手 | 开源，读 AGENTS.md | | **OpenAI Codex** | AI 编程助手 | 读 \~/.codex/AGENTS.md | | **腾讯 Trae / 字节 MarsCode** | AI IDE | 读项目 AGENTS.md | | **VS Code** | 代码编辑 | 前端/后端调试 | | **Docker Desktop** | 容器管理 | 本地调试用，服务器用 docker-ce | | **MobaXterm / Termius** | SSH 终端 | 连服务器执行部署命令 | | **Git** | 版本管理 | 拉取/更新代码 | ## 架构总览 QuantMind 单机 Docker Compose 部署（`docker-compose.yml`），11+ 服务： | 容器 | 服务 | 端口 | 说明 | | ------------------------ | ------------- | --------- | --------------------------- | | `quantmind-db` | PostgreSQL 15 | 5432 | 主数据库 | | `quantmind-redis` | Redis 7 | 6379 | 缓存/消息（DB 0-5 分配） | | `quantmind` | 后端主服务 | 8000-8003 | api/engine/trade/stream 四合一 | | `quantmind-celery` | Celery Worker | — | 异步任务（回测/同步/推理） | | `quantmind-celery-beat` | Celery Beat | — | 定时调度 | | `quantmind-web` | 前端 Web | 80 | Nginx 托管 React 构建产物 | | `quantmind-data-gateway` | 数据网关 | — | 行情/资金流聚合 | | `quantmind-huntly` | Huntly | 8090 | RSS 新闻存储/阅读器 | | `quantmind-rsshub` | RSSHub | 1200 | 通用网站订阅 | | `qwenpaw` | QwenPaw | 8088 | AI 代理（可选）；**默认仅绑 127.0.0.1**，外部直连需 `QWENPAW_BIND=0.0.0.0` | > **QwenPaw 外部访问**：`qwenpaw` 端口默认只绑 `127.0.0.1`（安全收敛口径）。前端 QuantBot 页面用 iframe 直连 > `http://<API网关主机>:8088/`，若在远端浏览器/Electron 打开需要在 `.env` 增加 `QWENPAW_BIND=0.0.0.0`， > 然后 `docker compose up -d qwenpaw`（**改端口映射必须 recreate，`restart` 不生效**），并在云安全组放行 8088 > 且**限定来源 IP**（QwenPaw 为免登录模式）。仅容器内 `http://qwenpaw:8088` 互访则无需改动。 ## 1. 部署前准备（重要，先做完再部署） ### 1.1 环境要求（多系统 + 硬件） | 项目 | 要求 | 说明 | | ----------- | ---------------------------- | ------------------------------------------------------- | | **系统** | Ubuntu 22.04 LTS 或 24.04 LTS | **部署脚本仅支持 Ubuntu 22.04+**，其他系统会被拒绝 | | **Windows** | Docker Desktop + WSL2 后端 | 在 WSL2 终端内执行 `docker compose` | | **macOS** | Docker Desktop 直接运行 | 兼容 | | **云服务器** | 任意 Docker 环境 | 单机即可 | | **CPU 架构** | **仅 x86\_64 / AMD64** | **ARM（aarch64）不支持**——微软 Qlib 框架仅发布 x86\_64，ARM 无法装 Qlib | | **CPU** | 4 核以上 | 推荐 8 核（训练/回测耗 CPU） | | **内存** | 16GB 以上（运行） | 模型训练推荐 **64GB+**，推理/回测 **32GB+**；内存不足会 OOM 训练卡死 | | **磁盘** | 100GB 以上可用 | 数据 + 镜像 + 特征快照（\~15GB）+ 模型 | > ⚠️ 训练机建议 ≥64GB 内存；若只有 32GB，缩小时间窗/特征数避免 OOM。 ### 1.2 网络检查（部署前必测） 国内服务器常需配置镜像源。部署脚本会自动选 Docker/PyPI/APT 镜像源，也可手动指定。 ```bash # 检查 DNS + 各仓库连通性（任一失败先解决再部署） curl -fsSL --connect-timeout 5 https://gitee.com >/dev/null && echo "gitee OK" || echo "gitee FAIL" curl -fsSL --connect-timeout 5 https://registry.npmmirror.com >/dev/null && echo "npm OK" || echo "npm FAIL" curl -fsSL --connect-timeout 5 https://pypi.org >/dev/null && echo "pypi OK" || echo "pypi FAIL" docker info >/dev/null 2>&1 && echo "docker OK" || echo "docker 未安装（部署脚本会装）" ``` **网络差时的应对**： - 手动指定 Docker 镜像源：`QUANTMIND_DOCKER_MIRROR=https://你的加速域名 sudo -E bash deploy/full-deploy.sh` - Docker 镜像源：`/etc/docker/daemon.json` 配置 `registry-mirrors`（阿里云/腾讯云镜像加速） - PyPI 源：`PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/`（构建镜像时 `--build-arg`） ### 1.3 提前决定要填写的内容 部署脚本会**交互式**问你以下内容，提前准备好答案： | 部署时问什么 | 示例答案 | 说明 | | ------------------- | ----------------------------- | --------------------------------- | | 服务器 IP | `192.168.1.100` / `localhost` | 无公网 IP 用 localhost 或局域网 IP | | 选择镜像源 | 国内选阿里云/中科大 | 网络差时自动选，也可 `QUANTMIND_MIRROR=` 指定 | | 是否确认部署 | `y` | 确认后开始安装 | | （可选）QuantDB API Key | `qdb_xxx` | **部署后**在后台填，见 \[\[quantdb-sdk]] | ### 1.4 部署前备份 ```bash # 若已有旧数据/旧部署，先备份 sudo cp -r /opt/quantmind/data /opt/quantmind/data.bak.$(date +%Y%m%d) ``` ## 2. 一键部署（推荐） ```bash # 完整一键部署：从 CDN 下载完整业务数据/模型/Qlib 数据 + 镜像包，恢复后开箱即用 curl -fsSL https://gitee.com/qusong0627/QuantMind/raw/master/deploy/full-deploy.sh | sudo bash # 自定义 CDN / 分支 / 镜像加速 sudo QUANTMIND_OFFLINE_BASE_URL='https://cdn.example.com/quantmind-offline' \ QUANTMIND_REF='master' \ QUANTMIND_DOCKER_MIRROR='https://你的镜像加速域名' \ bash deploy/full-deploy.sh ``` **部署 8 阶段**（详见 `docs/部署指南.md` 第四节）： 1. 安装系统依赖与 Docker / Compose，配置镜像加速； 2. 从 CDN 下载离线包并 SHA-256 全量校验（支持断点续传 / 复用）； 3. 导入 Docker 镜像（9 个；`rsshub` 部署时在线拉取）； 4. 拉取代码（支持 Compose/Dockerfile 受控覆盖层）； 5. 恢复业务数据、模型与 Qlib 数据； 6. 恢复 PostgreSQL 业务数据（已有数据默认保留）； 7. 恢复 QwenPaw 持久化卷； 8. 构建启动全部服务并自动配置 QwenPaw 运行时。 ## 3. 源码部署（已下线） > 在线源码部署脚本 `deploy/deploy.sh` / `quick-deploy.sh` 已从仓库移除。请使用第 2 节「一键部署」（`deploy/full-deploy.sh`），或按第 4 节用 `docker compose` 手动部署。 ## 4. 手动部署（源码） ```bash sudo git clone https://gitee.com/qusong0627/QuantMind.git /opt/quantmind cd /opt/quantmind # 编写 .env：DB_PASSWORD / SECRET_KEY / JWT_SECRET_KEY / STORAGE_MODE=local（见 docs/部署指南.md） sudo docker compose build quantmind sudo docker compose up -d ``` 详见 `docs/部署指南.md` 第五节「完全手动部署」。 ## 5. 数据库初始化（关键） 服务启动时自动幂等重放 **`backend/shared/db_init.sql`**（含 users 等全部核心表）： - 容器内路径 `/app/backend/shared/db_init.sql`（由 `./backend:/app/backend` 挂载提供） - 优先从 quantmind 容器执行 psql，失败则从 db 容器执行 - 若存在 `data/quantmind_init.sql` 则补充初始化数据 ```bash # 手动执行数据库初始化 docker exec quantmind bash -c "psql -h db -U quantmind -d quantmind -f /app/backend/shared/db_init.sql --quiet -v ON_ERROR_STOP=0" ``` **初始化后必须验证 users 表存在**（最常见部署失败点）： ```bash docker exec quantmind-db psql -U quantmind -d quantmind -c "\dt users" # 期望看到 users 表；若不存在说明 db_init.sql 没跑成功 ``` ## 6. 部署后检查（按顺序，每步都过再继续） ### 6.1 容器健康 ```bash docker compose -f /opt/quantmind/docker-compose.yml ps # 期望 quantmind/quantmind-celery/quantmind-celery-beat/quantmind-web/quantmind-db/quantmind-redis 都 Up ``` ### 6.2 数据库 & Redis ```bash docker exec quantmind-db pg_isready -U quantmind # 期望 "accepting connections" docker exec quantmind-redis redis-cli ping # 期望 "PONG" ``` ### 6.3 后端 API 健康 ```bash curl -s http://localhost:8000/api/v1/health # 期望返回 {"status":"healthy", ...} 含 api/engine/trade/stream 四服务 ``` ### 6.4 登录验证（关键：验证 users 表 + 认证链路） ```bash curl -s -X POST http://localhost:8000/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"admin123","tenant_id":"default"}' # 期望返回 access_token；若 401/500 → users 表问题（见排查） ``` ### 6.5 前端访问 ```bash curl -s -I http://localhost | head -1 # 期望 200 OK ``` ### 6.6 登录后台 + 配置数据源 1. 浏览器访问 `http://服务器IP`，用 admin 登录 2. 后台「数据管理」配置 **QuantDB API Key**（见 \[\[quantdb-sdk]]） 3. 触发一次数据同步（见 \[\[quantmind-operations]] 第 3 节） ## 7. 更新部署 ```bash cd /opt/quantmind # 一键更新脚本（同步代码 → 重建核心镜像 → 重启服务 → 导入数据库补丁 → 健康检查，不动数据库数据） sudo bash deploy/update.sh # 更新到指定分支或 tag sudo bash deploy/update.sh --ref master # 覆盖服务器上未提交的代码改动（谨慎，用 --force 而非 --force-sync） sudo bash deploy/update.sh --force # 纯代码改动，跳过镜像重建 sudo bash deploy/update.sh --no-build # 手动更新 git pull origin master docker compose build docker compose up -d ``` ### 7.1 update.sh 自动做了什么（客户升级说明） | 步骤 | 行为 | 数据是否受影响 |