sanguo/sanguo_vnpy_v2
2
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
379836d34ebdb2a6262c726fc89d4a76338ab6a1
sanguo_vnpy_v2/docs/superpowers/specs/2026-07-10-phase3d-live-trading-design.md
T
claude_dev 379836d34e docs(live): D期任务状态更新(D-1/D-3完成)+Windows部署联调清单 
- 设计文档§8: D-1/D-3标✅代码完成+commit号, D-2/D-4待Windows, 附代码层验证说明
- d-phase-windows-deploy.md(新): Windows端一站式清单(D-1实测/D-2自启/D-4a联调/故障排查)
2026-07-11 00:07:18 +08:00

9.8 KiB
Raw Blame History

Phase 3D 实盘交易集成设计（miniQMT bridge 架构）

日期：2026-07-10 | 状态：设计中（网络层已完成，bridge/编排待开发） 前序：Phase 3C 模拟盘（PaperEngine 双源+双层记账，commit 1646903/0656108 已完成） 关联：khquant-analysis（xtquant 参考）、vps-access skill、docs/data-platform/daily-update-design.md

1. 背景与目标

C 期模拟盘已端到端跑通（PaperEngine：raw/qfq 双源 + 总账/分户双层记账 + 软限额 + 占用成本 + 分红送股）。D 期目标：接入实盘，实现「模拟→实盘」同引擎切换。

核心约束（决定架构）：

  • miniQMT 仅 Windows 桌面，必须登录常驻，提供 xtquant Python API
  • sanguo 跑 NAS Linux Docker 容器（sanguo_vnpy_v2）
  • Windows 与 NAS 在不同网络（异地），需跨网打通
  • 实走为日线级（每日 20:30 单根 bar 推进），对延迟不敏感

→ 结论：唯一可行路径是 miniQMT（xtquant），PTrade/QMT 完整版封闭不可集成（详见 khquant-analysis 同源调研）。

2. 总体架构

[网络A · 局域网]                 [公网 VPS]                    [网络B · 异地]
                                 43.133.235.218
NAS Docker                       ┌─ frps(:7000)                Windows 机器
 sanguo_vnpy_v2  ──HTTPS────────►│  Caddy(:443)                 ├ miniQMT 客户端（登录常驻）
 live_orchestrator   下单/查询    │   bridge.mysanguo.top        ├ bridge 服务(:8765) ← D期写
                                  │   → 127.0.0.1:18765          │    ↓ xtquant 本地 IPC
                                  └─ frps(:18765) ◄─frp隧道──── └ frpc（连 frps:7000）

下单链路（6 跳）： sanguo(NAS) → 公网 → Caddy(VPS:443) → frps(18765) → frp隧道 → Windows frpc → bridge(:8765) → xtquant → miniQMT

日线级单 bar 推进，延迟完全无感；高频不适用（非本项目场景）。

3. 网络层（已完成 ✅）

组件 配置 状态
Windows frpc frp v0.69.1，frpc.toml（serverAddr 43.133.235.218:7000 + token + qmt-bridge proxy 8765→18765） ✅ 已连（VPS 18765 监听确认）
frps（VPS） 无 allowPorts 限制 ✅
Caddy（VPS） bridge.mysanguo.top { reverse_proxy 127.0.0.1:18765 } ✅ validate + reload
DNS（NameSilo） bridge A 43.133.235.218 TTL 3600 ✅ 生效
HTTPS 证书 Caddy 自动 ACME（TLS1.3） ✅
全链路验证 curl https://bridge.mysanguo.top → 502 server: Caddy ✅ 502=隧道通到 Windows（8765 待写）

Windows frpc 开机自启：任务计划程序（sanguo-frpc，onstart + 失败重启）或启动文件夹，见 NAS /volume1/stock/frp_windows/README.md。

4. bridge 服务设计（Windows 端，D-1 待开发）

4.1 形态

  • FastAPI HTTP 服务，监听 127.0.0.1:8765（仅本地，frpc 转发外部流量）
  • 启动时初始化 xtquant.XtQuantTrader（连本地 miniQMT 客户端）+ xtdata（行情）
  • 自启：任务计划程序（sanguo-bridge，onstart，依赖 miniQMT 客户端已登录）

4.2 接口（最小集，YAGNI）

方法 路径 入参 返回 说明
GET /health — {status, miniqmt_connected} 健康检查（frpc/Caddy 探活）
POST /order {code, action:buy/sell, price, volume, reason} {order_id, ok} 下单（xt_trader.order_stock）
POST /cancel {order_id} {ok} 撤单
GET /account — {cash, frozen, market_value, total} 资金（xt_trader.query_stock_asset）
GET /positions — [{code, volume, can_use, avg_price, ...}] 持仓（xt_trader.query_stock_positions）
GET /trades ?since=<ts> [{code, action, price, volume, time}] 成交回报（账本同步用）

股票代码格式：xtquant 用 600000.SH / 000001.SZ（sanguo 内部 sh600000，bridge 做转换）。

4.3 xtquant 调用要点（参考 OSkhQuant 架构，不抄代码）

  • xt_trader = XtQuantTrader(path, session_id)；xt_trader.start()；connect() 后 subscribe(account)
  • 下单：xt_trader.order_stock(account, code, order_type, volume, price_type, price, strategy_name, order_remark)
    • price_type：限价 XT_PRICE_LIMITED / 市价 XT_PRICE_LATEST_PRICE 等
    • A 股 T+1：query_stock_positions 的 can_use_volume 即可卖量（buy 当日计 frozen）
  • 行情：xtdata.download_history_data + get_market_data_ex（实盘 step 用实时，非历史）
  • 回调：xt_trader.register_callback 异步接收成交通知

5. sanguo 端改造（D-3 待开发）

5.1 配置（config/data_platform.yaml 加）

live:
  bridge_url: https://bridge.mysanguo.top
  bridge_token: ${BRIDGE_TOKEN}   # 环境变量，不进 git
  enabled: false                   # 总开关，模拟联调时再开

5.2 live_orchestrator 改造（sanguo_trader/live_orchestrator.py）

现状：live_step 恢复状态 → warmup → 当日 bar → engine.step → 存状态。step 返回 (pending_new, closes)。

D 期加「实盘执行分支」：当 account.mode == 'live' 且 live.enabled：

  1. step 产生的当日成交（closes）→ 同步 POST /order 到 bridge（真实下单到 miniQMT）
  2. 次日开盘前，从 bridge GET /positions /account 拉真实持仓/资金，校正 account 账本（真实回报为准，纠模拟撮合漂移）
  3. 鉴权：每个请求带 X-Bridge-Token header

5.3 模拟撮合 vs 实盘下单的关系（关键设计决策）

模式 说明 D 期采用
A 影子下单（推荐先） PaperEngine 照常模拟撮合（账本准），同时把信号 POST bridge「影子」下单到 miniQMT 模拟环境，对比两者验证一致性 ✅ 联调期
B 实盘驱动 真实下单 + 成交回报驱动账本，PaperEngine 退化为信号生成器 切实盘后

→ 联调先用 A（模拟盘端到端，零资金风险），一致性验证后切实盘切 B。

6. 鉴权与安全（⚠️ bridge.mysanguo.top 已公网暴露）

实测：域名一上线即被扫描器（81.171.74.60 等）打 /dump.sql /wp-config.php /secrets.json。必须：

  1. 共享密钥：每个请求 header X-Bridge-Token: <random>，bridge 校验，不符 401。token 走环境变量（sanguo + Windows bridge 两端同值），不进 git
  2. 最小接口：只放 §4.2 的接口，不暴露 xtquant 全能力
  3. 限速：FastAPI middleware 限流（防爆破）
  4. 可选 IP 白名单：sanguo 经 VPS 反代，bridge 看到的源 IP 是 VPS（43.133.235.218）→ bridge 可加白名单只接受 frps 来源
  5. 审计日志：bridge 记录每笔下单（code/action/volume/price/来源 IP/时间），便于复盘异常

7. 端到端联调方案（模拟盘先行）

阶段 环境 资金风险 目标
D-4a miniQMT 模拟客户端（现已在跑） 零 bridge 端到端打通：sanguo 信号 → bridge → miniQMT 模拟下单 → 回报
D-4b 模拟客户端 + 影子对比 零 PaperEngine 模拟撮合 vs bridge 真实下单，验证一致性（成交价/持仓/资金）
D-4c 小资金实盘（切实盘账户） 低 真金白银小单验证，切换模式 B
D-4d 正式实盘 正常 纳入每日 20:30 scheduler

8. 任务拆分（D 期工作清单）

编号 任务 端 依赖 状态
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。

9. 风险与兜底

风险 影响 兜底
Windows/miniQMT/frpc/bridge 四常驻，任一断 下单链路断 日线级 → 「断线次日补」+ bridge /health 探活 + scheduler 重试
VPS 单点 全链路断 接受（日线级）；备选 Tailscale 直连绕 VPS
bridge token 泄露 任意人可下单 环境变量 + 不 commit + 审计日志 + 限速
miniQMT 停新申请（2026/7/6） 新账户无法开 老账户可用；新账户换其他提供 miniQMT 券商（华泰/中泰/国信）
模拟撮合与实盘成交价漂移 账本不准 模式 B 以 bridge 回报为准校正
公网扫描/攻击 bridge 被打 §6 鉴权 + 最小接口 + 限速

10. 相关

  • 源码参考：/volume1/KnowledgeBase/github-repos/OSkhQuant（xtquant 调用链路，CC BY-NC 仅参考架构）
  • khquant-analysis wiki
  • vps-deployment wiki（FRP/Caddy 基建）
  • vps-access skill
  • 前序：docs/superpowers/specs/2026-07-07-phase3c-paper-trading-design.md
  • 网络层落地：NAS /volume1/stock/frp_windows/（frpc + README）
Reference in New Issue View Git Blame Copy Permalink