⚙️ 本技能遵循公共运行环境契约（最高优先级，先于本文其余内容执行）： 详见 _shared/env-contract.md，执行前先读它。

QuantMind 部署技能

QuantMind 部署运维完整指南。覆盖部署前准备 → 一键/手动部署 → 部署后检查 → 问题排查 → 更新 → 云端训练全流程。本技能针对 AI 编程助手编写，每步都给出可直接执行的命令与判断标准，避免"不知道下一步"卡壳。

0. 安装技能包（让 AI 帮你部署）

本技能包兼容主流 AI 编程工具（Claude Code / Codex / OpenCode / Trae / MarsCode 等），安装后 AI 能自动识别"部署/装不上"等意图并调用本技能指导部署。

方式一：Claude Code / QuantBot（原生 SKILL.md）

# 解压到 Claude Code 全局技能目录
unzip quantmind-operations-skill.zip -d ~/.claude/
# 验证
ls ~/.claude/skills/quantmind-deploy/SKILL.md

方式二：从项目仓库安装（任何工具）

# 项目根目录 skills/ 下即全部技能
cp -r /opt/quantmind/skills/* ~/.claude/skills/

方式三：其他主流 AI 工具（OpenCode / Codex / Trae / MarsCode 等）

各工具虽不原生识别 SKILL.md，但都读取 AGENTS.md（项目级指令）。把技能包要点导入即可：

# ① 通用做法：把 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 执行 quick-deploy.sh

推荐编程工具（部署环境）

架构总览

QuantMind 单机 Docker Compose 部署（docker-compose.yml），11+ 服务：

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 环境要求（多系统 + 硬件）

⚠️ 训练机建议 ≥64GB 内存；若只有 32GB，缩小时间窗/特征数避免 OOM。

1.2 网络检查（部署前必测）

国内服务器常需配置镜像源。部署脚本会自动选 Docker/PyPI/APT 镜像源，也可手动指定。

# 检查 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 未安装（部署脚本会装）"

网络差时的应对：

• 手动指定镜像源：QUANTMIND_MIRROR=aliyun sudo bash deploy.sh（或 tuna/huaweicloud）

• Docker 镜像源：/etc/docker/daemon.json 配置 registry-mirrors（阿里云/腾讯云镜像加速）

• PyPI 源：PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/（构建镜像时 --build-arg）

1.3 提前决定要填写的内容

部署脚本会交互式问你以下内容，提前准备好答案：

1.4 部署前备份

# 若已有旧数据/旧部署，先备份
sudo cp -r /opt/quantmind/data /opt/quantmind/data.bak.$(date +%Y%m%d)

2. 一键部署（推荐）

# 需要 root 权限；默认固定到发布 tag v1.9.0-beta（可复现、可校验）
curl -fsSL https://gitee.com/qusong0627/QuantMind/raw/v1.9.0-beta/deploy/quick-deploy.sh | sudo bash

# 使用最新 master（不推荐生产）
QUANTMIND_DEPLOY_TAG=master curl -fsSL https://gitee.com/qusong0627/QuantMind/raw/master/deploy/quick-deploy.sh | sudo bash

# 校验 deploy.sh 完整性（生产建议设置 SHA256）
QUANTMIND_DEPLOY_SHA256=<sha256> QUANTMIND_DEPLOY_TAG=v1.9.0-beta sudo bash quick-deploy.sh

部署 6 阶段：

1. 系统准备：更新依赖、装 Docker & Compose v2.19+、Node 20、Nginx
2. 代码部署：从 Gitee 克隆到 /opt/quantmind、配置 .env、创建数据目录
3. 后端部署：构建 Docker 镜像、启动 PG/Redis/QuantMind、执行 db_init.sql 初始化数据库
4. 前端部署：npm 依赖 + 构建 + PM2 启动
5. Nginx 配置：反向代理
6. 验证：健康检查 + 防火墙

3. 快速部署（已下载脚本）

sudo bash deploy/quick-deploy.sh
# 指定服务器 IP（公网/局域网/localhost 自动检测）
sudo bash deploy/deploy.sh localhost
sudo bash deploy/deploy.sh 192.168.1.100
QUANTMIND_SERVER_IP=192.168.1.100 sudo bash deploy/deploy.sh

4. 手动部署

sudo git clone https://gitee.com/qusong0627/QuantMind.git /opt/quantmind
cd /opt/quantmind
sudo chmod +x deploy/deploy.sh
sudo ./deploy/deploy.sh

5. 数据库初始化（关键）

deploy.sh 自动执行 backend/shared/db_init.sql（含 users 等全部核心表）：

• 容器内路径 /app/backend/shared/db_init.sql（由 ./backend:/app/backend 挂载提供）

• 优先从 quantmind 容器执行 psql，失败则从 db 容器执行

• 若存在 data/quantmind_init.sql 则补充初始化数据

# 手动执行数据库初始化
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 表存在（最常见部署失败点）：

docker exec quantmind-db psql -U quantmind -d quantmind -c "\dt users"
# 期望看到 users 表；若不存在说明 db_init.sql 没跑成功

6. 部署后检查（按顺序，每步都过再继续）

6.1 容器健康

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

docker exec quantmind-db pg_isready -U quantmind          # 期望 "accepting connections"
docker exec quantmind-redis redis-cli ping                # 期望 "PONG"

6.3 后端 API 健康

curl -s http://localhost:8000/api/v1/health
# 期望返回 {"status":"healthy", ...} 含 api/engine/trade/stream 四服务

6.4 登录验证（关键：验证 users 表 + 认证链路）

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 前端访问

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. 更新部署

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 自动做了什么（客户升级说明）

⚠️ 数据库补丁为可重复执行的幂等 SQL：每次 update 都会重跑一遍所有 data/upgrade_*.sql（无去重记录），需用 IF NOT EXISTS 等自防重。打新版本补丁时在 data/ 新增 upgrade_vX.Y.Z.sql 即可，不用改脚本。

⚠️ update.sh 只重建后端 quantmind 镜像，不 build web/data-gateway/dashboard。前端或可选服务代码有改动时，需走离线包成品镜像或手动 docker compose build 对应服务。

7.2 版本展示与落后提交提示

• 后端 /api/v1/system/version 返回 version / commit / branch / update；管理后台右上角与「用户中心 → 设置」共用该接口。
• deploy/update.sh 写入 backend/shared/version.json（完整 HEAD SHA + rev_count，.gitignore 内）；本地未走 update.sh 时接口回落 dev。
• 落后数来自 Gitea 分支 release-index 上的 release-index.json（维护端 python scripts/publish_release_index.py --push 生成）。禁止改回 Gitee/GitHub compare，禁止把计数文件提交进 master。

7.3 升级后验证

# 容器健康 + 版本号
curl -s http://localhost:8000/api/v1/system/version
# 登录（数据库补丁执行无碍）
curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123","tenant_id":"default"}'

8. 云端 GPU 训练（AutoDL）

推荐把 AutoDL 当训练 Worker，不要在实例里装整套 QuantMind。 AutoDL Python 镜像一般不能嵌套 Docker，走 exec_mode: native_python。完整步骤以仓库文档为准：

• 操作手册：docs/部署指南.md 第十一节
• 节点初始化：deploy/autodl/README.md

模型训练可跑在 AutoDL 远程 GPU 节点（主节点 Docker 默认是 CPU 训练）。

AutoDL 训练节点配置

# 列出训练节点（本地 Docker + AutoDL 远程 GPU）
curl -s -H "$AUTH" "$BASE/api/v1/admin/models/training-nodes"
# 测试节点连接（native_python 测 SSH + Python/GPU；ssh_docker 测 docker）
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/admin/models/training-nodes/test" \
  -d '{"node_id":"autodl-rtx4090"}'

主节点 config/training_nodes.yaml（gitignore）示例：

nodes:
  - id: autodl-rtx4090
    host: connect.xxx.seetacloud.com
    port: <控制台端口>
    user: root
    exec_mode: native_python
    work_dir: /root/workspace
    quantdb_dir: /root/autodl-fs/quantdb

.env 设 TRAINING_MASTER_HOST=<协调机公网IP>。AutoDL 上先跑 deploy/autodl/setup-autodl-native.sh。

AutoDL 远程训练镜像（仅 ssh_docker）

仅当远端已经有 Docker + GPU 直通时才用：

docker build --build-arg TORCH_DEVICE=gpu -f docker/autodl/Dockerfile -t quantmind-train:latest .
bash scripts/setup/build-autodl-remote.sh

远程训练流程

1. 配节点：config/training_nodes.yaml（含 SSH 凭据，不入库）
2. 测连接：training-nodes/test
3. 启动训练：run-training 选 node_id=autodl-x
4. 看状态：training-runs/{run_id}；节点状态 training-nodes/{node_id}/status
5. 模型回传：产物 rsync 回 /data/training_jobs/{run_id}/ 并注册

实例关机后 SSH 端口会变，必须改 yaml 的 port。

8b. AutoDL 实例内原生部署（无 Docker 环境）

实战记录（2026-08-16，RTX 5090 实例）。AutoDL 实例是容器（PID1=bash），宿主机未开嵌套容器权限，Docker 完全不可用。若需在实例内跑完整 QuantMind 平台（而非仅作训练节点），走原生部署。

环境探测（部署前必做）

# Docker 可行性判定：缺 SYS_ADMIN 能力位 + unshare 被禁 = 装不了 Docker（rootless 也不行）
grep CapEff /proc/self/status                      # a80425fb 缺 0x200000 (SYS_ADMIN)
unshare --user --map-root-user true 2>&1           # Operation not permitted → 无 userns
ps -p 1 -o comm=                                    # bash（非 systemd，开机自启只能挂 .bashrc）

原生部署步骤（全部装系统盘，保存镜像才完整）

# 1. 系统依赖（Ubuntu 22.04 源自带 PG14/Redis6，版本够用）
apt-get install -y postgresql redis-server nginx git build-essential cmake swig libgomp1

# 2. Python 3.10（对齐官方镜像；AutoDL 自带 miniconda 是 py3.12，必须另建环境）
conda create -n qm python=3.10 pip
source activate qm

# 3. torch GPU 版（走阿里云 PyPI，实测 4MB/s；官方 pytorch.org 在 AutoDL 被 403）
pip install torch==2.9.1 -i https://mirrors.aliyun.com/pypi/simple/

# 4. 其余依赖（与 Dockerfile.oss 同清单，requirements/*.txt + quantdb-sdk + patch_qlib）
pip install -r requirements.txt -r requirements/production.txt -r requirements/ai.txt
pip install "quantdb-sdk==0.3.3" && python docker/patch_qlib.py

# 5. PG 初始化（实例内无 systemd，用 pg_ctlcluster 拉起）
pg_ctlcluster 14 main start
su - postgres -c "psql -c \"CREATE ROLE quantmind LOGIN PASSWORD 'quantmind2026';\""
su - postgres -c "psql -c 'CREATE DATABASE quantmind OWNER quantmind;'"
PGPASSWORD=quantmind2026 psql -h 127.0.0.1 -U quantmind -d quantmind -f backend/shared/db_init.sql

# 6. Redis：redis-server --daemonize yes --port 6379

# 7. 环境变量：导出对齐 docker-compose.yml 的 env（DB_HOST=127.0.0.1，STORAGE_ROOT=数据目录）

# 8. 启动后端（setsid 彻底脱离 SSH 会话，否则 SSH 断开进程被杀）
cd /root/QuantMind && setsid nohup bash qm-start.sh > data/logs/backend.log 2>&1 < /dev/null &

# 9. 前端：本地 npm run build:react 构建 dist-react（~29M），scp 到 /usr/share/nginx/html/
#    nginx 反代 /api/→127.0.0.1:8000、/ws/→127.0.0.1:8003；$connection_upgrade 变量是
#    docker-nginx 专属，原生 nginx 直接写 Connection "upgrade"

# 10. 开机自启（无 systemd）：写 /etc/autodl.sh（AutoDL 官方开机钩子，PID1 boot.sh 会调用它）
#    内容：service cron start + 调用 /root/qm-autostart.sh（pg_ctlcluster + redis --daemonize + nginx + setsid 后端 + qwenpaw + huntly）
#    cron 看门狗兜底：apt install cron && service cron start && crontab -e 加 "* * * * * bash /root/qm-watchdog.sh"
#    ⚠️ .bashrc 自启无效——PID1 是 boot.sh，不经过交互式登录；实例重启后 cron 不自起，必须写进 autodl.sh

### QwenPaw 原生部署（无 Docker）
```bash
# 源码来源：本地 docker 容器 agentscope/qwenpaw:latest 里 /app 目录（含构建好的 console/dist）
# 打包：docker exec qwenpaw tar czf /tmp/qwenpaw-src.tgz src pyproject.toml setup.py  （~15MB，console 已在 src/qwenpaw/console/）
# 云端：
conda create -n qwenpaw python=3.11 pip -y          # 注意：conda 可能因网络重试失败但实际创建成功，用 ls envs/qwenpaw/bin 确认
/root/miniconda3/envs/qwenpaw/bin/pip install -e /root/QwenPaw -i https://mirrors.aliyun.com/pypi/simple/
/root/miniconda3/envs/qwenpaw/bin/pip install asyncpg redis psycopg2-binary -i https://mirrors.aliyun.com/pypi/simple/
# 环境变量对齐 docker-compose qwenpaw 段：PYTHONPATH=/app + /app 下符号链接到 QuantMind（backend/config/scripts/working/models/logs/db）
#   已补 /etc/hosts: db→127.0.0.1、redis→127.0.0.1、qwenpaw→127.0.0.1、copaw→127.0.0.1
qwenpaw init --defaults --accept-security            # 生成 /app/working/config.json
qwenpaw app --host 0.0.0.0 --port 8088               # 启动（用 /root/qwenpaw-start.sh 带启动锁）
# 后端连 QwenPaw：.env.sh 加 QWENPAW_BASE_URL=http://127.0.0.1:8088 + COPAW_BASE_URL，重启后端
# 前端访问：/api/v1/qwenpaw-ui/ 代理（无需 8088 直接暴露）

Huntly 原生部署（无 Docker）

# 源码来源：本地 docker cp quantmind-huntly:/app/server.jar（~121MB，scp 约 20 分钟）
apt-get install -y default-jre-headless               # JRE 11 即可
java -Xms128m -Xmx1024m -Duser.timezone=GMT+08 -jar server.jar \
  --spring.profiles.active=default --server.port=8090 \
  --huntly.dataDir=/root/huntly/data/ --huntly.luceneDir=/root/huntly/data/lucene
# ⚠️ 首次启动自动建用户 changeme（HUNTLY_DEFAULT_USERNAME/PASSWORD 只在首次生效，之后改环境变量无效）
#    要改账号：sqlite3 db.sqlite "UPDATE users SET username='admin', password='<bcrypt>' WHERE username='changeme'"
#    密码是 bcrypt(10)，用 python bcrypt.hashpw(b"admin123", bcrypt.gensalt(10))
# 后端连 Huntly：.env.sh 里 HUNTLY_USERNAME/HUNTLY_PASSWORD 改对后重启后端，news/health 应返回 up
# ⚠️ 8090 不在 AutoDL 公网映射（只有 6006/6008 映射），前端「后台」链接打不开：
#    方案 A（已落地）：后端 /api/v1/news/huntly-ui/ 做 SPA 子路径代理（见下方「Huntly UI 代理」）——
#    HTML 路径重写 + JS 拦截脚本重写 fetch/XHR/WebSocket/EventSource 的 /api/ → 代理路径
#    前端资讯页「后台」按钮指向 /api/v1/news/huntly-ui/（SERVICE_ENDPOINTS.USER_SERVICE 拼接），无需 8090 公网暴露
#    方案 B（备用）：nginx 单独 server 块 listen 6008 反代 127.0.0.1:8090（6008 映射到公网 443，前端 6006 映射 8443）

### Huntly UI 代理（SPA 子路径代理模式，news.py 已实现）
```bash
# 访问入口：https://<实例ID>.westd.seetacloud.com:8443/api/v1/news/huntly-ui/
# 登录：admin / admin123（Huntly 自己的账号体系，与 QuantMind 后端账号无关）

SPA 子路径代理必须做对四件事，缺一即部分功能失灵（实战踩坑记录）：

1. HTML 路径重写：src="/static/ → src="/api/v1/news/huntly-ui/static/、favicon/manifest 同理
2. JS 拦截脚本注入 <head>：重写 fetch/XMLHttpRequest.open/WebSocket 的 /api/ 前缀 → 代理路径 （EventSource 构造也传 /api/... 字符串，走 fetch 重写不够，Huntly 用的是 new EventSource("/api/...")，需要把 EventSource 也包一层或确认其 URL 已被拦截；当前实现已覆盖）
3. API 路由声明顺序：FastAPI 按声明顺序匹配，@router.api_route("/huntly-ui/api/{path:path}") 必须声明在 @router.get("/huntly-ui/{path:path}")（静态）之前，否则 GET 会被静态路由吞掉 → 不带鉴权转发 → 405/401
4. Set-Cookie 透传：Huntly 是 HttpOnly cookie 会话（auth_token=...; Path=/; HttpOnly），前端 JS 里根本不存 token。 代理响应必须透传 set-cookie 头，浏览器才会把 cookie 存在 QuantMind origin 下；转发时后端 _ensure_session() 的全局 JWT 兜底（带 Authorization + Cookie 双头）保证登录前/后 API 都通

AutoDL 原生部署踩坑清单

部署后验证（AutoDL 原生）

for p in 8000 8001 8002 8003; do curl -s http://127.0.0.1:$p/health; done   # 四服务 healthy
time curl -s -X POST http://127.0.0.1:8000/api/v1/auth/login -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123","tenant_id":"default"}'      # 返回 access_token 且 <1s
#   若 >20s 必是 /.dockerenv 陷阱（见踩坑清单第 2 条）
/root/miniconda3/envs/qm/bin/python -c "import torch; print(torch.cuda.get_device_name(0))"

# 外网访问（AutoDL 控制台「自定义服务」把 6006 映射成公网 8443 后）：
curl -skI https://<实例ID>.westd.seetacloud.com:8443/ | head -1               # 前端 200
curl -sk -X POST https://<实例ID>.westd.seetacloud.com:8443/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123","tenant_id":"default"}'      # 公网登录链路 200

9. 问题排查（诊断树，按顺序走）

9.1 先看这 3 条命令的输出（快速定位）

# 1. 容器状态（谁没起来）
docker compose -f /opt/quantmind/docker-compose.yml ps

# 2. 后端日志（报什么错）
docker compose -f /opt/quantmind/docker-compose.yml logs --tail=100 quantmind

# 3. 数据库连接
docker exec quantmind-db pg_isready -U quantmind

9.2 诊断树

部署后不能访问？
├─ curl localhost:8000/api/v1/health 失败
│   ├─ 容器没起来 → docker compose ps 看状态 → docker compose logs quantmind 看报错
│   ├─ 端口被占 → netstat -tlnp | grep 8000 → 释放冲突端口
│   └─ 数据库连不上 → docker exec quantmind-db pg_isready → 重启 db 容器
├─ health OK 但登录失败（401/500）
│   ├─ users 表不存在 → docker exec quantmind-db psql -U quantmind -d quantmind -c "\dt users"
│   │     → 无表则手动执行 db_init.sql（见第 5 节）
│   └─ SECRET_KEY 不一致 → 检查 .env 的 JWT_SECRET_KEY，重启后端
├─ 登录成功但前端打不开
│   ├─ curl -s -I http://localhost 失败 → nginx -t → systemctl restart nginx
│   ├─ PM2 没起 → pm2 status → pm2 restart quantmind-web
│   └─ 前端构建问题 → cd /opt/quantmind/electron && npm install && npm run dashboard:build
└─ 都正常但页面报"数据缺失"
    ├─ 未配 QuantDB API Key → 后台「数据管理」填 Key（见 [[quantdb-sdk]]）
    └─ 未同步数据 → [[quantmind-operations]] 第 3 节触发同步

9.3 常见问题速查表

9.4 AI 助手部署常见坑（给编程 AI 的提示）

数据目录（持久化）

/opt/quantmind/data/
├── postgres/       # 数据库数据
├── redis/          # Redis 数据
├── quantdb/        # QuantDB A股 parquet
├── quantus/        # 美股 parquet
├── quanthk/        # 港股 parquet
├── quantbc/        # 区块链 parquet
├── quantfutures/   # 期货 parquet
├── logs/           # 日志
└── models/         # 模型文件

相关技能

• [[quantmind-operations]] — 部署后数据同步、模型训练、推理

• [[quantdb-sdk]] — QuantDB 数据源配置（API Key）

• [[simulation-trading]] — 部署后模拟盘验证