From 8f51b026faf5cfd3e780f1425a9c7c2acd29d242 Mon Sep 17 00:00:00 2001
From: claude_dev <claude-dev@sanguo.local>
Date: Sat, 11 Jul 2026 07:48:41 +0800
Subject: [PATCH] =?UTF-8?q?docs(deploy):=20Windows=20bridge=E9=83=A8?=
 =?UTF-8?q?=E7=BD=B2+=E5=8D=8A=E8=87=AA=E5=8A=A8=E6=9B=B4=E6=96=B0?=
 =?UTF-8?q?=E4=B8=80=E7=AB=99=E5=BC=8Fmd(git=20clone+update.bat,=20?=
 =?UTF-8?q?=E7=85=A7=E7=9D=80=E5=81=9A)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/deployment/windows-bridge-setup.md | 136 ++++++++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 docs/deployment/windows-bridge-setup.md

diff --git a/docs/deployment/windows-bridge-setup.md b/docs/deployment/windows-bridge-setup.md
new file mode 100644
index 0000000..3dc88a0
--- /dev/null
+++ b/docs/deployment/windows-bridge-setup.md
@@ -0,0 +1,136 @@
+# Windows bridge 部署 + 半自动更新（一站式）
+
+> sanguo QMT bridge（Windows 端 FastAPI + xtquant）的完整部署 + 以后半自动更新。
+> 照着做即可，不用手动拷贝文件。
+
+## 0. 前提
+
+- miniQMT 客户端已安装，能登录账号 `66639661`（测试客户端/模拟）
+- `check_xtquant.py` 已跑通（import + connect + query 三步 ✅）
+- frpc 已配 + 连上 VPS（`curl https://bridge.mysanguo.top/health` 返回 502 = 隧道通）
+
+---
+
+## 1. 装 Git for Windows
+
+下载 https://git-scm.com/download/win → 一路「Next」默认安装。
+
+装完打开 cmd，验证：
+```cmd
+git --version
+```
+
+---
+
+## 2. 生成 gitea token（必须本人操作）
+
+1. 浏览器开 `https://git.mysanguo.top`，登录 **sanguo** 账号
+2. 右上角**头像 → 设置（Settings）**
+3. 左侧 **应用（Applications）** → 找「管理 Access Tokens / 个人访问令牌」
+4. 新建：
+   - 名字：`windows-bridge`
+   - 权限：勾 **`repository`**（读仓库即可）
+5. 点「生成令牌」→ **立刻复制** token（形如 `abcdef123456...`，只显示这一次，存好）
+
+---
+
+## 3. clone 仓库
+
+cmd 里跑（把 `<粘贴token>` 换成第 2 步复制的 token）：
+```cmd
+git clone http://sanguo:<粘贴token>@git.mysanguo.top/sanguo/sanguo_vnpy_v2.git C:\sanguo_vnpy_v2
+```
+
+token 进 URL 后，以后 pull 免输。代码在 `C:\sanguo_vnpy_v2\sanguo_qmt_bridge\`。
+
+---
+
+## 4. 装依赖 + 设 BRIDGE_TOKEN
+
+```cmd
+cd C:\sanguo_vnpy_v2\sanguo_qmt_bridge
+pip install -r requirements.txt
+```
+
+设 bridge 鉴权密钥（和 NAS sanguo 端同值；当前测试用 `<你的BRIDGE_TOKEN>`，切实盘前换）：
+
+```cmd
+:: 临时（当前 cmd 窗口）
+set BRIDGE_TOKEN=<你的BRIDGE_TOKEN>
+
+:: 永久（系统环境变量，推荐）
+setx BRIDGE_TOKEN "<你的BRIDGE_TOKEN>"
+```
+> 用 `setx` 后**重开一个 cmd 窗口**才生效。
+
+---
+
+## 5. 首次启动
+
+**双击** `C:\sanguo_vnpy_v2\sanguo_qmt_bridge\update.bat`
+
+它会：git pull（首次=已最新）+ 启动 bridge。看到日志 `xtquant 连接成功` 即就绪。
+
+> 也可以手动：`cd C:\sanguo_vnpy_v2\sanguo_qmt_bridge && uvicorn bridge:app --host 127.0.0.1 --port 8765`
+
+---
+
+## 6. 验证（另开一个 cmd）
+
+```cmd
+curl http://127.0.0.1:8765/health
+```
+期望：`{"status":"ok","miniqmt_connected":true}`
+
+```cmd
+curl -H "X-Bridge-Token: <你的BRIDGE_TOKEN>" http://127.0.0.1:8765/account
+```
+期望：`{"ok":true,"cash":10000000.0,...}`
+
+三接口通 = bridge 就绪。
+
+---
+
+## 7. 以后每次更新（核心：半自动）
+
+bridge 代码有更新时（Claude push 到 gitea 后），你只需：
+
+**双击 `C:\sanguo_vnpy_v2\sanguo_qmt_bridge\update.bat`**
+
+自动 git pull 拉最新 + 重启 bridge（新窗口跑 uvicorn，旧窗口可关）。**不用手动下文件、不用手动拷贝**。
+
+`update.bat` 会显示当前 git 版本（commit），方便对照。
+
+---
+
+## 8. 开机自启（可选，D-2）
+
+让 bridge 开机自动起。最简单——**启动文件夹**：
+
+1. Win+R 输 `shell:startup` 回车，打开启动文件夹
+2. 在里面新建快捷方式，指向 `C:\sanguo_vnpy_v2\sanguo_qmt_bridge\update.bat`
+3. （miniQMT 客户端也设开机自启登录，bridge 依赖它）
+
+开机后 update.bat 自动跑（pull + 启动 bridge）。
+
+---
+
+## 9. 故障排查
+
+| 现象 | 排查 |
+|------|------|
+| `git clone` 报 401/无权限 | token 错/过期，重新生成（第 2 步）|
+| `update.bat` git pull 失败 | 网络 / token 过期，看 update.bat 输出 |
+| `/health` miniqmt_connected:false | miniQMT 未登录 / userdata 路径错 / 账号未就绪 |
+| bridge 启动 `xtquant import 失败` | xtquant 不在 site-packages，确认 miniQMT 安装目录的 site-packages 在 PYTHONPATH |
+| 下单 `[120141][证券交易未初始化]` | **非交易日**（miniQMT 交易日才初始化交易通道），等周一开市。这是 miniQMT 设计，不是 bug |
+| 401 token 无效 | sanguo 与 Windows 的 `BRIDGE_TOKEN` 不一致 |
+| miniQMT 重启后 bridge 失效 | 双击 update.bat 重启 bridge（新版有自动重连，但仍建议重启确认）|
+
+---
+
+## 相关
+
+- bridge 接口契约 / 联调步骤：`docs/deployment/d-phase-windows-deploy.md`
+- D 期设计：`docs/superpowers/specs/2026-07-10-phase3d-live-trading-design.md`
+- bridge 源码：`sanguo_qmt_bridge/`（bridge.py / xt_gateway.py / auth.py / trade_calendar.py / update.bat）