# VPS 触及面清单 + Commit 环境标签约定

> 解决痛点：NAS 上修了一堆 bug，事后回溯"哪些 VPS 也中招、要不要推 VPS"认知负担大、易错。
> 本文档把"事后回溯每个 commit"换成"事前对照一张稳定清单"。
>
> **判定原则（钥匙）**：维度是「VPS 运行时是否触发这个 bug」，**不是**「文件改了没」。
> 改了文件 ≠ VPS 中招（可能只改注释 / VPS 不跑这段）；没改文件 ≠ VPS 不中招。

## 一、核心事实：物理层已天然隔离

`promote.sh` 是**白名单推送**（`ALL_MODS` + `ROOT_FILES`，见 `scripts/nas_sync/promote.sh:22-25`）：
`docker/` 被 exclude（line 49），`Dockerfile` / `entrypoint.sh` / `.gitea/` 不在白名单 → **物理上进不了 VPS**。

所以"NAS 专属文件会不会污染 VPS"无风险。真问题是「VPS 运行时是否也中招」——用下表判。

## 二、VPS 触及面表（基于代码核查 2026-08-02）

| 归属 | 模块 / 路径 | VPS 运行时场景 |
|------|-------------|----------------|
| 🔴 **VPS 触及**（改动落这 = 要考虑推 VPS） | `sanguo_data/` | schtask 每日采集（bs_eod/xt_eod/akshare） |
| 🔴 | `sanguo_backtest/` | CTA 回测入口（load_data / metrics / 引擎） |
| 🔴 | `sanguo_portfolio/runner_backtest.py` | 组合回测入口（VPS **直接调 run_backtest，不走 pool**） |
| 🔴 | `sanguo_portfolio/runner_live.py` `sanguo_live/` `sanguo_qmt_bridge/` | 实盘 / miniQMT 桥 |
| 🔴 | `sanguo_common/` | 被上述引用 |
| 🔴 | provider 取数（`sanguo_data/` 内） | verify_unified_e2e.py 验证 |
| 🔴 | `scripts/data_platform/*.py` | VPS schtask 跑的采集/merge/verify 脚本 |
| 🟡 **弱触及** | `requirements-lock.txt` | VPS 手动 pip 装，lock 仅作参考（不自动装） |
| 🟢 **NAS 专属**（不用推 VPS） | `sanguo_orchestrator/` | **仅 web(uvicorn) 启动**；VPS 不跑 web→不跑 ProcessPool→不触发 spawn |
| 🟢 | `sanguo_api/`（routes/app/uvicorn 部分） | VPS 无常驻 web |
| 🟢 | `sanguo_web/`（前端） | VPS 不 serve 前端 |
| 🟢 | `docker/` `Dockerfile` `entrypoint.sh` | VPS 无 docker |
| 🟢 | `.gitea/workflows/` | NAS/Mac runner 跑 |
| 🟢 | `config/`（vnpy_db 等 NAS 容器 config） | VPS 用 `SANGUO_DB_PATH` env 覆盖，不读此 config |

### ⚠️ 混合模块（需看具体文件，不能整模块一刀切）

| 模块 | VPS 触及部分 | NAS 专属部分 |
|------|--------------|--------------|
| `sanguo_portfolio/` | `runner_backtest.py` `runner_live.py`（回测/实盘主体） | 若改动仅触及 orchestrator 调度（pool/worker/timeout）→ NAS 专属 |
| `sanguo_api/` | 若 model/schema 被 runner 复用（待核对） | routes/app（web） |

> 判定混合模块：看 diff 的具体文件路径，对照上表"VPS 触及部分"。

## 三、Commit 环境标签约定（CI 强制，以后 commit 必打）

CI 的 `enforce-label` 步骤强制：本次 push 的 commit **必须**带 `[vps]` 或 `[nas]`，无标签 → **CI 直接 fail**（merge commit 豁免）。

```
<type>(<scope>): <desc> [nas]   # NAS/docker 专属(VPS 不中招)
<type>(<scope>): <desc> [vps]   # VPS 也中招(含通用 shared 代码), 待推 VPS
```

- 一条 commit 混合多环境 → 打主导面 + 正文注明（如 `[nas] 注:runner_backtest.py 一行属 vps`）。
- `[vps]` 触发链：nas-verify 绿后 CI 自动开/更新 `[待推VPS]` issue（**open=黄/待推**）；人工/agent 推 vps-deploy.yml → 成功打 `vps-deployed` tag → issue 自动关（**close=绿/已推**）。

## 四、判定流程（3 步，30 秒）

1. **看 scope/标签**：commit message 有 `[nas]/[vps]/[vps]` → 直接得结论。
2. **无标签则对照触及面表**：diff 的文件路径落在 🔴 区 = 要推 VPS；落在 🟢 区 = 不用推；🟡/混合 = 复核。
3. **复核运行时语义**（混合/存疑时）：问"VPS 跑这段代码吗？"——对照上表 VPS 运行时场景列。

## 五、近期 commit 判定（2026-08-02 回溯，含技术债标注）

| commit | scope | 标签 | VPS 适用 | 说明 |
|--------|-------|------|----------|------|
| `b66a6c5` fix(ashare_engine) load_data 绕 peewee | sanguo_backtest | **[vps]** | 🔴 **要推** | VPS CTA 回测走 load_data，库大也死锁 |
| `2ff8eca` perf(metrics) rolling 向量化 | sanguo_backtest | **[vps]** | 🔴 **要推** | 分钟级卡死，VPS 算 metrics 也卡 |
| `b2c41c7` fix(backtest) benchmark 缺失降级 | sanguo_backtest | **[vps]** | 🔴 **要推** | VPS 回测也走 metrics |
| `9588a77` feat(portfolio) 回测可观测性 | runner_backtest | **[vps]** | 🔴 **要推** | VPS 回测入口 |
| `7a14d7d` feat(portfolio) strategy 全链透传 | runner_backtest | **[vps]** | 🔴 **要推** | 改到 runner_backtest（API→orchestrator 部分是 NAS） |
| `c263aa1` `3d934f5` chore(cta_engine) logging | sanguo_backtest | [vps] | 🟡 可推 | 无害 logging |
| `6d23f7b` fix(portfolio) worker _TIMEOUT | orchestrator worker | [nas] | 🟢 不用推 | pool 超时，VPS 不走 pool |
| `e22c8ee` feat(portfolio) max_pool 透传 | model+handler+前端 | [nas] | 🟢 不用推 | pool 调度参数，VPS 不走 pool |
| `2cb2ab0` fix(config) vnpy_db NAS dbbardata | config | [nas] | 🟢 不用推 | VPS 用 env 覆盖不读 config |
| `4c5270c` `c049e0e` `857d43c` fix(frontend) | sanguo_web | [nas] | 🟢 不用推 | 前端，VPS 无 web |
| `a17f291` fix(api) /health 端点 | sanguo_api | [nas] | 🟢 不用推 | VPS 不跑 web |
| `6d786fb` fix(orchestrator) spawn PYTHONPATH | orchestrator+entrypoint | [nas] | 🟢 不用推 | VPS 不跑 ProcessPool |
| `c210197` `0f6cdbe` `5c5bd9d` entrypoint/Dockerfile | docker | [nas] | 🟢 不用推 | NAS 专属 |
| `ca0ec01` ci(nas-verify) /health gate | .gitea | [nas] | 🟢 不用推 | 不推 VPS |
| `1989a54` fix(deps) requirements-lock | deps | [vps] | 🟡 弱 | VPS pip 参考 |

**⚠️ 技术债（🔴 标注的 5 条，VPS 回测逻辑修复）**：`b66a6c5` `2ff8eca` `b2c41c7` `9588a77` `7a14d7d`。
若 VPS 当前版本落后于这些 commit，VPS 回测仍带病（CTA 死锁/metrics 卡死/可观测性缺失/strategy 字段）。
→ **建议**：确认 VPS 当前 sha，若落后则触发一次 `vps-deploy.yml` 补推（nas-verify 已绿）。