claude_dev
67d1c1ef2f
- ci-cd: enforce-label(本次push无标签→fail,merge豁免) + check-vps-needed(nas-verify绿后对比vps-deployed tag,有[vps]未部署→开issue) - vps-deploy: 成功打vps-deployed tag + 关issue(gap清空) - scripts/ci/vps_pending_check.py: issue开/关/更新(CI复用) - docs: vps-impact-map触及面表 + vps-deploy-pending判定记录 - CLAUDE.md: 部署流程段补标签约定
6.2 KiB
6.2 KiB
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-deployedtag → issue 自动关（close=绿/已推）。
四、判定流程（3 步，30 秒）
- 看 scope/标签：commit message 有
[nas]/[vps]/[vps]→ 直接得结论。 - 无标签则对照触及面表：diff 的文件路径落在 🔴 区 = 要推 VPS；落在 🟢 区 = 不用推；🟡/混合 = 复核。
- 复核运行时语义（混合/存疑时）：问"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 已绿）。