# 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 仓库（sparse checkout，只拉 bridge 代码）

只需 `sanguo_qmt_bridge/` 子目录，不用全量。cmd 里跑（把 `<粘贴token>` 换成第 2 步的 token）：

```cmd
git clone --no-checkout --depth 1 --sparse http://sanguo:<粘贴token>@git.mysanguo.top/sanguo/sanguo_vnpy_v2.git C:\sanguo_vnpy_v2
cd C:\sanguo_vnpy_v2
git sparse-checkout set sanguo_qmt_bridge
```

三行解释：
- `--no-checkout --sparse`：先不拉文件，建空稀疏仓库
- `--depth 1`：只拉最新一版（不拉 git 历史，省带宽）
- `sparse-checkout set sanguo_qmt_bridge`：只 checkout 这个子目录

结果：`C:\sanguo_vnpy_v2\sanguo_qmt_bridge\` 有 bridge 代码，**不带 vnpy 源码/sanguo_trader/docs 等多余文件**。token 进 URL 后以后 pull 免输。

> 以后 `update.bat` 的 git pull 只更新 `sanguo_qmt_bridge/`（sparse 仓库只拉这部分）。

---

## 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）