Files
lpt-be/.agents/notes/implemented/process/2026-11-08-branch-bound-deploy.md
T
cat-shark 27ddf8be5a docs: 规则与技能迁入 .agents/,并接入决策笔记
- roles/ 与 skills/ 迁移到 .agents/ 下,AGENTS.md 引用同步
- 收录 8 篇决策笔记到 .agents/notes/
- .rgignore 排除 archived 历史快照
2026-11-18 15:01:05 +08:00

2.8 KiB
Raw Blame History

Agent Note: 出包环境由分支绑定,不靠参数切换

Status: implemented

Problem

同一份代码要出 dev 与 prod 两个包。如果只靠流水线参数(或本地配置)区分环境,那么「用 dev 的代码发到 prod 的 namespace」只是一次手滑——而这类手滑的代价最大:库表迁移已经跑上去、前端已经指到生产后端, 回滚时数据形状已经不匹配。

Decision

一个分支对一个环境,绑定关系写进流水线第一步并直接拒绝不匹配的组合,而不是打印警告。

仓库 dev 分支 prod 分支 说明
lpt-be / lpt-fe / lpt-ai dev master main(lpt-ai)仅作历史冻结点,不再发版
lpt-android dev master 两个分支只差默认 API 地址,不参与 k8s 部署
lpt-infra master master 单分支,靠 dev/ 与 prod/ 目录区分清单
  • 触发方式固定为 workflow_dispatch + 选择 environment,流水线首步校验「分支 ↔ 环境」,不匹配即 exit 1。
  • 网关地址、registry 等推动参数全部来自流水线的环境分支开关;禁止用 tag 触发部署(tag 打出来就跟分支脱钩了)。
  • 跨仓库同环境同批发:dev 配 dev、master 配 master。lpt-ai 的结果字段与 lpt-be 的读取形状是硬耦合, 跨环境出包会让旧版读取方静默降级,界面不报错。

Alternatives considered

  • 单分支 + 部署参数区分环境 — 不必维护两条长期分支,也少了合并这一步。放弃是因为环境成了「一次运行里的一个 字符串」:谁都能选错,代码里哪一行是生产配置也无从判断,出事后连「线上跑的是哪份代码」都要翻流水线记录才能答。
  • 出包后打 tag,用 tag 决定环境 — 发布形态更接近常规 CI。但本项目的分支本身就是环境契约,再叠一层 tag 会让 两个事实源打架;且 tag 一旦从错误分支打出,校验分支就再也拦不住。

Consequences

  • 收益:环境错配从一个「可能发生的事故」变成一个「跑不起来的流水线」;线上代码与分支一一对应,可以直接回答。
  • 代价与已知上限:每次上生产都要「dev 合并进 master」这一次显式动作,合并冲突要自己解;dev 上验证过的 东西与 master 上的形态之间隔了一次合并,必须同批升级关联仓库才不会错配。历史例外:lpt-ai 的 main 停在 冻结点 7c751bf,看见它在仓库列表里不代表还能发版。

Verification

  • 规则位置:lpt-be/.gitea/workflows/deploy.yml、lpt-fe/.gitea/workflows/deploy.yml、 lpt-ai/.gitea/workflows/deploy.yml 的 Validate branch ↔ environment 首步。
  • 清单分区:lpt-infra/dev/ 与 lpt-infra/prod/。