From 379836d34ebdb2a6262c726fc89d4a76338ab6a1 Mon Sep 17 00:00:00 2001 From: claude_dev Date: Sat, 11 Jul 2026 00:07:18 +0800 Subject: [PATCH] =?UTF-8?q?docs(live):=20D=E6=9C=9F=E4=BB=BB=E5=8A=A1?= =?UTF-8?q?=E7=8A=B6=E6=80=81=E6=9B=B4=E6=96=B0(D-1/D-3=E5=AE=8C=E6=88=90)?= =?UTF-8?q?+Windows=E9=83=A8=E7=BD=B2=E8=81=94=E8=B0=83=E6=B8=85=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 设计文档§8: D-1/D-3标✅代码完成+commit号, D-2/D-4待Windows, 附代码层验证说明 - d-phase-windows-deploy.md(新): Windows端一站式清单(D-1实测/D-2自启/D-4a联调/故障排查) --- docs/deployment/d-phase-windows-deploy.md | 133 ++++++++++++++++++ .../2026-07-10-phase3d-live-trading-design.md | 21 +-- 2 files changed, 145 insertions(+), 9 deletions(-) create mode 100644 docs/deployment/d-phase-windows-deploy.md diff --git a/docs/deployment/d-phase-windows-deploy.md b/docs/deployment/d-phase-windows-deploy.md new file mode 100644 index 0000000..4cbb073 --- /dev/null +++ b/docs/deployment/d-phase-windows-deploy.md @@ -0,0 +1,133 @@ +# 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. 安装 + 配置 + +```powershell +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 验证） + +```powershell +cd C:\sanguo_qmt_bridge +uvicorn bridge:app --host 127.0.0.1 --port 8765 +``` + +启动日志看到「xtquant 连接成功」。另开终端测： + +```powershell +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 测全链路： + +```bash +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`： + +```yaml +live: + enabled: true # D-4a 联调开（默认 false） + bridge_url: https://bridge.mysanguo.top + shadow: true +``` + +设 sanguo 容器 `BRIDGE_TOKEN` 环境变量（**= Windows 同值**），重启容器生效： + +```bash +docker restart sanguo_vnpy_v2 +``` + +## 6. D-4a 端到端联调 + +触发一次 live_step（有当日成交时会影子下单到 bridge）： + +```bash +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）： + +```powershell +# 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)` 幂等去重 | diff --git a/docs/superpowers/specs/2026-07-10-phase3d-live-trading-design.md b/docs/superpowers/specs/2026-07-10-phase3d-live-trading-design.md index e74b752..6d5e0f8 100644 --- a/docs/superpowers/specs/2026-07-10-phase3d-live-trading-design.md +++ b/docs/superpowers/specs/2026-07-10-phase3d-live-trading-design.md @@ -138,15 +138,18 @@ D 期加「实盘执行分支」：当 `account.mode == 'live'` 且 `live.enable ## 8. 任务拆分（D 期工作清单） -| 编号 | 任务 | 端 | 依赖 | -|------|------|-----|------| -| D-1 | bridge 服务（FastAPI + xtquant + 鉴权 + 6 接口）| Windows | — | -| D-2 | bridge 自启（任务计划程序）+ frpc 自启确认 | Windows | D-1 | -| D-3 | sanguo live_orchestrator 实盘分支 + config + 鉴权客户端 | NAS | D-1 接口定义 | -| D-4a | 模拟盘端到端联调（影子下单打通）| 两端 | D-1/D-3 | -| D-4b | 模拟撮合 vs 实盘下单一致性验证 | 两端 | D-4a | -| D-4c | 小资金实盘切模式 B | 两端 | D-4b | -| D-5 | 文档/验收/部署 | — | D-4 | +| 编号 | 任务 | 端 | 依赖 | 状态 | +|------|------|-----|------|------| +| D-1 | bridge MVP（health/order/account/positions + 鉴权）| Windows | — | ✅ 代码完成 commit `eff9ed2`，待 Windows 实测 | +| D-2 | bridge 自启（任务计划程序）+ frpc 自启 | Windows | D-1 | ⏳ 待 Windows 配置（见 d-phase-windows-deploy.md §7）| +| D-3 | sanguo 影子下单分支（bridge_client + live_orchestrator + 幂等）| NAS | D-1 | ✅ 代码完成 commit `ff84b3d`，待联调 | +| D-4a | 模拟盘端到端联调（影子下单打通）| 两端 | D-1/D-3 | ⏳ 待 Windows bridge 部署 + NAS 开 enabled | +| D-4b | 模拟撮合 vs 实盘下单一致性验证 | 两端 | D-4a | ⏳ | +| D-4c | 小资金实盘切模式 B | 两端 | D-4b | ⏳ | +| D-5 | 文档/验收/部署 | — | D-4 | 🔄 进行中（设计文档状态 + Windows 部署清单）| + +> **代码层验证**：D-1（4 接口 ast + 逻辑 review）、D-3（Sub Agent 自测：symbol 转换 8 例 + 幂等 5 例 + guard 4 例 + persistence 7 测试无回归；Main Agent review import 完整）均通过。 +> **端到端验证**（D-4a/b/c）依赖 Windows bridge 实跑 + NAS 联调，见 `docs/deployment/d-phase-windows-deploy.md`。 ---