147 lines
4.9 KiB
Markdown
147 lines
4.9 KiB
Markdown
# 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）
|