sanguo_vnpy_v2/docs/archive/deployment/d-phase-windows-deploy.md

Phase 3D Windows 端部署 + 联调清单

D 期实盘集成：Windows miniQMT bridge 部署 + sanguo 联调一站式清单。 前序：D-1 bridge MVP（commit eff9ed2）+ D-3 sanguo 影子下单（commit ff84b3d）代码已完成。 本清单是 Windows 端实操（D-1 实测 / D-2 自启 / D-4a 联调）——这些步骤 miniQMT 只在 Windows，必须人工执行。

架构回顾

sanguo(NAS) ──HTTPS──► Caddy(VPS:443 bridge.mysanguo.top)
                             ↓ 反代
                         frps(18765) ◄─frp隧道─ Windows frpc
                                                         ↓
                                           bridge(:8765) → xtquant → miniQMT

0. 前提确认

• miniQMT 客户端已登录常驻（极简模式 / 独立交易）
• check_xtquant.py 跑通（import + connect + query 三步 ✅，账户 66639661）
• frpc 已配 + 连上 VPS（curl https://bridge.mysanguo.top/health 返回 502 = 隧道通，bridge 未启）

1. 获取 bridge 代码

从 gitea 拉 sanguo_qmt_bridge/ 目录（bridge.py / xt_gateway.py / auth.py / requirements.txt / README.md）：

http://git.mysanguo.top/sanguo/sanguo_vnpy_v2/src/branch/master/sanguo_qmt_bridge

下到 Windows，例如 C:\sanguo_qmt_bridge\

2. 安装 + 配置

cd C:\sanguo_qmt_bridge
pip install -r requirements.txt   # fastapi + uvicorn

# 生成 BRIDGE_TOKEN（随机密钥，记下来！sanguo 端要同值）
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 设为系统环境变量（永久）
[Environment]::SetEnvironmentVariable("BRIDGE_TOKEN", "上面生成的密钥", "User")

重开终端使 BRIDGE_TOKEN 生效。userdata / account 默认值已对（D:\国金QMT交易端模拟\userdata_mini / 66639661），如不同设 MINIQMT_USERDATA / ACCOUNT_ID 环境变量。

3. 启动 + 实测（D-1 验证）

cd C:\sanguo_qmt_bridge
uvicorn bridge:app --host 127.0.0.1 --port 8765

启动日志看到「xtquant 连接成功」。另开终端测：

curl http://127.0.0.1:8765/health
# {"status":"ok","miniqmt_connected":true}

curl -H "X-Bridge-Token: 你的密钥" http://127.0.0.1:8765/account
# {"ok":true,"cash":10000000.0,"frozen":0.0,"market_value":0.0,"total":10000000.0}

curl -H "X-Bridge-Token: 你的密钥" http://127.0.0.1:8765/positions
# {"ok":true,"positions":[]}

✅ 三接口通 = D-1 完成。

4. 公网联调（sanguo → bridge）

NAS sanguo 容器经 bridge.mysanguo.top 访问。在 NAS 测全链路：

ssh sanguo-nas
/var/packages/Docker/target/usr/bin/docker exec sanguo_vnpy_v2 \
  curl -H "X-Bridge-Token: 你的密钥" https://bridge.mysanguo.top/health
# {"status":"ok","miniqmt_connected":true}  → 公网 6 跳全通

5. sanguo 端开影子下单（D-3 启用）

NAS config/data_platform.yaml：

live:
  enabled: true              # D-4a 联调开（默认 false）
  bridge_url: https://bridge.mysanguo.top
  shadow: true

设 sanguo 容器 BRIDGE_TOKEN 环境变量（= Windows 同值），重启容器生效：

docker restart sanguo_vnpy_v2

6. D-4a 端到端联调

触发一次 live_step（有当日成交时会影子下单到 bridge）：

docker exec sanguo_vnpy_v2 python -c \
  "from sanguo_trader.live_orchestrator import run_live_step; \
   run_live_step('/volume1/stock/sanguo_vnpy/data/quant_trading.db')"

观察：

• Windows bridge 日志：应有 POST /order（影子下单）+ miniQMT 客户端出现委托记录
• NAS：paper_shadow_orders 表有记录（幂等去重）

7. 开机自启（D-2）

bridge + frpc 都要开机自启（任务计划程序 schtasks，Windows 自带，不用 nssm）：

# sanguo-bridge（onstart，依赖 miniQMT 已先启动登录）
schtasks /create /tn "sanguo-bridge" /tr "cmd /c cd /d C:\sanguo_qmt_bridge && uvicorn bridge:app --host 127.0.0.1 --port 8765" /sc onstart /ru SYSTEM /f

# sanguo-frpc（配置见 NAS /volume1/stock/frp_windows/，同样 schtasks onstart 或启动文件夹）

miniQMT 客户端本身也要开机自启登录（其自身设置或启动文件夹 shell:startup）。

故障排查

现象	排查
/health miniqmt_connected:false	miniQMT 未登录 / userdata 路径错 / 账户 ID 错
401 token 无效	sanguo 与 Windows 的 BRIDGE_TOKEN 不一致
公网 502	frpc 断 / bridge 没启；先 curl 127.0.0.1:8765/health 验本地
影子下单未触发	live.enabled 是否 true / 当日是否有成交 / BRIDGE_TOKEN 是否设 / bridge_url 是否对
重复下单	不会 —— paper_shadow_orders 表 UNIQUE(account_id, trade_id) 幂等去重