From 7088cef730a0064ea8525cb36c770de3d2b94b8e Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 28 May 2026 15:30:40 +0800 Subject: [PATCH] docs: add v0.2 decisions without extra gates --- docs/plan/hwlab-v02-namespace-cicd.md | 57 ++++++++++++++++----------- 1 file changed, 34 insertions(+), 23 deletions(-) diff --git a/docs/plan/hwlab-v02-namespace-cicd.md b/docs/plan/hwlab-v02-namespace-cicd.md index aba142b8..929b69e6 100644 --- a/docs/plan/hwlab-v02-namespace-cicd.md +++ b/docs/plan/hwlab-v02-namespace-cicd.md @@ -65,7 +65,7 @@ CI/CD 的初始化规则：Tekton 执行 `v0.2` lane 时必须先读取 `v0.2-gi | `scripts/g14-gitops-render.mjs` | 默认 `G14`、`G14-gitops`、`deploy/artifact-catalog.dev.json`、`runtime-dev`/`runtime-prod`。 | 增加显式 lane/source/gitops/catalog/runtime/namespace/endpoint 参数；`v0.2` 只写 `v0.2-gitops`。 | | `scripts/refresh-artifact-catalog.mjs` | catalog path、namespace、environment、endpoint 被 DEV-only 断言固定。 | 改成 lane contract；`v0.2` 从 GitOps checkout 读写 `deploy/artifact-catalog.v02.json`，不读写 source catalog。 | | `scripts/src/g14-ci-plan-lib.mjs` | 复用判断依赖 artifact catalog；默认路径仍是 DEV catalog。 | 保留复用能力，但 `v0.2` 必须传入 GitOps catalog path；catalog 缺失只能触发 `v0.2` 正式初始化或失败，不得回退到 DEV/source catalog。 | -| `scripts/artifact-publish.mjs` / `scripts/g14-artifact-publish.mjs` | preflight 仍把 `hwlab-dev`、DEV catalog 和 DEV-only contract 作为唯一合法目标。 | 保留 build/publish helper；`v0.2` 调用链必须删除这类 DEV-only preflight，如需保护只新增 `v0.2` 最小 preflight。 | +| `scripts/artifact-publish.mjs` / `scripts/g14-artifact-publish.mjs` | preflight 仍把 `hwlab-dev`、DEV catalog 和 DEV-only contract 作为唯一合法目标。 | 保留 build/publish helper；`v0.2` 调用链必须删除这类 DEV-only preflight，只在 build/publish 自然写入点做最小内联断言。 | 不应进入 `v0.2` 发布门禁的陈旧路径： @@ -79,13 +79,13 @@ CI/CD 的初始化规则：Tekton 执行 `v0.2` lane 时必须先读取 `v0.2-gi | `scripts/validate-contract.mjs`、旧 `deploy/README.md` / `deploy/master-edge/*` | 仍含历史 `16666/16667` 或 D601 DEV 合同。 | 不让这些旧合同阻塞 `v0.2`；若某项仍被 CI 调用，先从 `v0.2` CI 删除该调用。 | | source branch 中的 rendered `deploy/gitops/g14/tekton/*` | 可能是历史生成快照，不是 Argo/Tekton 当前真相。 | `v0.2` 不在 source 更新这些生成物；只改 render 入口和 GitOps branch 输出。 | -`v0.2` 新增门禁必须保持最小，只覆盖以下高价值风险： +`v0.2` 不新增综合 preflight 或大范围 guard。只保留以下硬边界，并优先在已有自然写入点做内联断言：render 断言 runtime path/namespace，promote 断言 GitOps branch/changed paths，Argo spec 断言 Application destination，验收只看 `19666/19667` 与 `hwlab-v02` identity。不要为每一条设计约定再写一个独立 gate。 -- lane 边界：source branch 必须是 `v0.2`，GitOps branch 必须是 `v0.2-gitops`，namespace 必须是 `hwlab-v02`。 -- 生成物边界：`v0.2` source branch 在 publish 后不得出现 `deploy/artifact-catalog.v02.json` 或 `deploy/gitops/g14/runtime-v02/*` 变更。 -- Secret 边界：文档、issue、trace 和 report 只出现 SecretRef 名称和 key，不出现 Secret 值。 -- Argo 边界：`hwlab-g14-v02` 只能指向 `v0.2-gitops:deploy/gitops/g14/runtime-v02` 和 `hwlab-v02`。 -- 入口边界：公网验收只使用 `74.48.78.17:19666/19667`，不得把 `17666/17667` 或 `18666/18667` 作为 `v0.2` 通过证据。 +- source branch 必须是 `v0.2`，GitOps branch 必须是 `v0.2-gitops`，runtime namespace 必须是 `hwlab-v02`。 +- runtime path 必须是 `deploy/gitops/g14/runtime-v02`，Argo Application 必须指向 `v0.2` GitOps lane 和 `hwlab-v02`。 +- `v0.2` source branch 在 publish 后不得出现 `deploy/artifact-catalog.v02.json` 或 `deploy/gitops/g14/runtime-v02/*` 变更。 +- 文档、issue、trace 和 report 只出现 SecretRef 名称和 key，不出现 Secret 值。 +- 公网验收只使用 `74.48.78.17:19666/19667`，不得把 `17666/17667` 或 `18666/18667` 作为 `v0.2` 通过证据。 ## G14 与 v0.2 CI/CD 共存风险 @@ -98,30 +98,40 @@ G14 与 `v0.2` 可以共享 G14 k3s、Tekton controller、Argo CD controller、 | GitOps 写错分支 | `v0.2` promotion 误 push 到 `G14-gitops`。 | promote 前硬校验 `sourceBranch=v0.2`、`gitopsBranch=v0.2-gitops`，且 changed paths 只能在 `deploy/artifact-catalog.v02.json` 与 `deploy/gitops/g14/runtime-v02/**`。 | | runtime path 串线 | `v0.2` 写入 `runtime-dev` 或 `runtime-prod`。 | `v0.2` render 输出路径硬限制为 `deploy/gitops/g14/runtime-v02`；发现 DEV/PROD runtime path 变更直接失败。 | | artifact catalog 串线 | `v0.2` 读取或复用 `deploy/artifact-catalog.dev.json`、`G14-gitops` catalog 或 source branch 生成物。 | `v0.2` 只读写 `v0.2-gitops:deploy/artifact-catalog.v02.json`；缺失只能正式初始化或失败，不 fallback。 | -| 旧门禁阻塞 | DEV/D601/main 门禁拦住 `v0.2` 发布。 | 从 `v0.2` 调用链删除旧门禁；需要保护时只新增 `v0.2` 最小检查。 | +| 旧门禁阻塞 | DEV/D601/main 门禁拦住 `v0.2` 发布。 | 从 `v0.2` 调用链删除旧门禁；需要保护时只在自然写入点做最小内联断言。 | | Argo Application 指错 | `hwlab-g14-v02` 指到 `G14-gitops`、`runtime-dev` 或 `hwlab-dev`。 | Application spec 固定为 `v0.2-gitops:deploy/gitops/g14/runtime-v02`，destination 固定为 `hwlab-v02`。 | | namespace 资源串用 | Secret、PVC、ServiceAccount、FRP Deployment 或 runtime Service 复用 DEV/PROD。 | namespace 独立；runtime SecretRef 只在 `hwlab-v02` 内解析；cluster-scoped 资源必须独立命名或禁止进入 `v0.2` runtime。 | -| registry tag/digest 混淆 | G14 和 `v0.2` 使用同服务同 short SHA tag 时被误判为同一运行态。 | runtime manifest 优先 digest pin；catalog 必须记录 lane、source branch、GitOps branch 和 source commit。若 lane-specific build args 存在，image tag 必须带 lane 前缀。 | -| 清理任务误删 | stale PipelineRun cleanup、registry GC 或 Argo prune 误触 G14 DEV/PROD。 | cleanup selector 必须带 lane label；registry GC 以 `G14-gitops` 与 `v0.2-gitops` 两个分支的 digest union 作为保护集。 | +| registry tag/digest 混淆 | G14 和 `v0.2` 使用短 SHA tag 时被误判为同一运行态。 | `v0.2` 镜像 tag 使用完整 source commitId，runtime manifest 使用 digest pin；lane 身份记录在 catalog 和 runtime annotation。不要把 lane-specific 配置 bake 进镜像。 | +| 清理任务误删 | stale PipelineRun cleanup、registry GC 或 Argo prune 误触 G14 DEV/PROD。 | 初期不新增自动 registry GC；如后续启用 cleanup，selector 必须带 lane label，registry GC 保护集取 `G14-gitops` 与 `v0.2-gitops` 的 digest union。 | | 并发资源争抢 | 两个分支同时 build，G14 DEV rollout 变慢。 | `v0.2` 初期使用较低 poller 频率或手动触发；设置 Pipeline resources requests/limits；G14 DEV/PROD 优先级高于 `v0.2`。 | | 观测混淆 | 把 `17666/17667` 或 `18666/18667` 的结果当成 `v0.2` 通过。 | `v0.2` 验收只认 `19666/19667`；health payload 必须能看到 lane、namespace 或 revision 与 `hwlab-v02` 对齐。 | `v0.2` 第一阶段不得做“一个 Pipeline 入口同时兼容两个分支”的设计。正确做法是：G14 保持现有 poller、reconciler、pipeline 和 GitOps branch 不变；`v0.2` 新增独立 poller、reconciler、pipeline 和 GitOps branch，复用底层脚本库、工具镜像、registry 和 controller。共享实现能力，不共享状态、默认入口或生成物。 -## 扩容前必须冻结的决策 +## 扩容前决策表 -开始创建 namespace、改 Tekton/Argo 或触发 `v0.2` CI/CD 前，必须先冻结以下事项；未冻结时只允许继续文档和只读调查。 +开始创建 namespace、改 Tekton/Argo 或触发 `v0.2` CI/CD 前，先按下表定案。该表不是新增门禁清单；除硬边界外，设计约定和 runbook 不得自动实现为新的 preflight、guard、gate 或报告生成器。 -- `v0.2` CI 控制面资源命名：Pipeline、poller、reconciler、PipelineRun 前缀、ServiceAccount/RBAC label 和 cleanup selector。 -- `v0.2-gitops` 初始化方式：首版 branch、首版 `deploy/artifact-catalog.v02.json`、首版 `deploy/gitops/g14/runtime-v02` 的创建责任和提交身份。 -- `deploy.json` 的 lane 表达：是新增 `v02` environment，还是新增显式 lane 字段；不能把现有 `dev` 或 `prod` 改义成 `v0.2`。 -- 镜像 tag 策略：若 `v0.2` 与 G14 构建输入完全一致，可共用 digest；若存在 lane-specific build args、配置或基础镜像差异，tag 必须带 lane 前缀。 -- SecretRef 与数据面：`hwlab-v02` 使用哪些 Secret 名称、DB/database/schema/PVC 是否独立，以及哪些 key 允许被 runtime 引用。 -- Argo CD 边界：Application 名称、project 权限、destination namespace、source branch/path、sync policy 和 prune 范围。 -- FRP 边界：`19666/19667` 的 frps 放行、frpc 名称、Service 指向和验收 URL；不得复用 DEV/PROD 端口。 -- 最小验收口径：必须明确哪些 checks 算 `v0.2` 通过，哪些旧 DEV/M3/RPT smoke 不进入 `v0.2` gate。 -- 回滚/暂停动作：失败时暂停 poller、删除或 suspend Application、保留/删除 namespace 资源的顺序；回滚不得触碰 `hwlab-dev` 或 `hwlab-prod`。 -- 资源配额和优先级：`v0.2` 构建并发、CPU/memory 上限和 poller 频率，必须避免影响 G14 DEV/PROD。 +| 决策项 | 建议定案 | 性质与降噪要求 | +|---|---|---| +| CI 控制面命名 | 使用独立 `hwlab-v02-*`：`hwlab-v02-ci-image-publish`、`hwlab-v02-branch-poller`、`hwlab-v02-control-plane-reconciler`、`hwlab-v02-ci-poll-`。 | 硬边界；只防覆盖 G14 资源，不扩展成大范围命名审计。 | +| ServiceAccount/RBAC | 推荐新建 `hwlab-v02-tekton-runner`，权限只覆盖 `v0.2` GitOps 写入、PipelineRun 创建和 `hwlab-v02` 运行面观察。 | 设计边界；不做复杂权限 gate，先通过清晰命名和最小 RBAC manifest 表达。 | +| `v0.2-gitops` 初始化 | 新建独立分支 `v0.2-gitops`；首版只放 `deploy/artifact-catalog.v02.json` 和 `deploy/gitops/g14/runtime-v02/*`；提交身份使用 CI/GitOps bot。 | 硬边界；catalog 缺失只能正式初始化或失败，不 fallback 到 G14/DEV。 | +| `deploy.json` lane 表达 | 在 `v0.2` source branch 新增显式 `lanes.v02` 或等价 lane 字段，由 render `--lane v02` 读取；不把现有 `dev` 或 `prod` 改义成 `v0.2`。 | 设计定案；不要为 schema 选择额外做兼容迁移路线。 | +| 镜像 tag | `v0.2` 镜像 tag 使用完整 40 位 source commitId；runtime 以 digest pin 为部署身份；catalog 记录 lane/sourceBranch/gitopsBranch/sourceCommitId/digest。 | 简化策略；不引入 `v02-` tag，不把 lane 差异 bake 进镜像。 | +| 构建输入边界 | 同一 commit 对同一 service 应生成同一镜像；lane 差异放入 manifest/env/SecretRef/namespace/FRP/DB 配置。 | 设计边界；若同 commit 生成不同镜像，先修构建边界，不用 lane tag 掩盖。 | +| SecretRef | `hwlab-v02` 使用独立 Secret 对象；key 名可以沿用服务合同，值不得复用 DEV/PROD，文档只记录对象名和 key。 | 硬安全边界；只禁止 Secret 值外泄，不做 Secret 内容读取 gate。 | +| 数据面 | 推荐独立 DB user + 独立 database；PVC 独立；如后续选择 schema 隔离，必须在计划中单独说明原因。 | 设计定案；不把 DB 方案选择变成 CI gate。 | +| Argo CD | 新建 `hwlab-g14-v02`，source 固定 `v0.2-gitops:deploy/gitops/g14/runtime-v02`，destination 固定 `hwlab-v02`。 | 硬边界；通过 Application spec 表达，不新增平行 Argo 审计脚本。 | +| Argo prune | 允许在 `hwlab-v02` Application 范围内 prune；不得跨 namespace 或管理 DEV/PROD 资源。 | 运行策略；不做 apply 前大检查，靠 Application scope 和 resource labels 限定。 | +| FRP | frpc 名称用 `hwlab-v02-frpc`，只暴露 `19666/19667`，Service 指向 `hwlab-v02` 内 Cloud Web 和 edge/API。 | 硬入口边界；验收只认 v02 端口。 | +| 最小验收 | 只看 `hwlab-g14-v02` revision/sync、`hwlab-v02` 长驻 workload ready、`19666/19667` health/runtime identity。 | 验收口径；旧 DEV/M3/RPT smoke 不进入 `v0.2` gate。 | +| 旧门禁 | DEV/D601/main 门禁凡阻碍 `v0.2`，直接从 `v0.2` 调用链删除。 | 硬治理原则；不做兼容迁移、fallback、legacy mode 或旧门禁例外。 | +| 资源策略 | 初期手动触发或低频 poller；限制 `v0.2` 构建并发和 CPU/memory，G14 DEV/PROD 优先。 | 运行策略；不作为发布 gate。 | +| 清理策略 | 初期不启用新增自动 registry GC；若后续启用，cleanup selector 必须带 `lane=v02`，registry GC 保护集取 `G14-gitops` + `v0.2-gitops` digest union。 | 运行手册；不是扩容前 gate。 | +| 回滚/暂停 | 失败时先停 `hwlab-v02-branch-poller`，再 suspend/delete `hwlab-g14-v02`，最后处理 `hwlab-v02` runtime 资源。 | runbook；不阻塞首次部署，且不得触碰 DEV/PROD。 | +| G14 到 `v0.2` 同步 | bugfix 用显式 cherry-pick 或人工 merge，不做自动同步，不让 `v0.2` 反向影响 G14。 | 分支治理；不做自动 gate。 | +| 变更路径 | 文档和计划可直推 `origin/v0.2`；namespace、Argo、Tekton、Secret、DB、FRP 和 rollout 变更必须引用 issue 和 plan 分步执行。 | 执行纪律；不引入额外 PR/gate 要求。 | ## 实施阶段 @@ -144,6 +154,7 @@ G14 与 `v0.2` 可以共享 G14 k3s、Tekton controller、Argo CD controller、 - 在 `hwlab-ci` 中新增 `v0.2` 独立 poller/reconciler/Pipeline，不复用或覆盖现有 G14 控制面资源名。 - `v0.2` PipelineRun 前缀使用 `hwlab-v02-ci-poll-`，方便和 `hwlab-g14-ci-poll-` 区分。 - Pipeline 必须 checkout `v0.2` source 和 `v0.2-gitops` generated state；build/publish helper 可复用现有工具镜像、registry 和 BuildKit 机制，但产物 catalog、GitOps branch、runtime path 必须隔离。 + - 镜像 tag 使用完整 source commitId，最终部署 identity 以 digest pin 为准。 5. Argo CD 扩容 - 新增 `hwlab-g14-v02` Application，source 指向 `v0.2` 专属 GitOps lane，destination 指向 `hwlab-v02`。 @@ -151,7 +162,7 @@ G14 与 `v0.2` 可以共享 G14 k3s、Tekton controller、Argo CD controller、 - 首次同步先 dry-run / diff / health 观察，再进入真实 sync。 6. `deploy.json` 扩容 - - 在 `v0.2` 分支上新增显式 v02 environment 或 lane 配置，服务清单以 `hwlab-v02` 为目标 namespace。 + - 在 `v0.2` 分支上新增显式 `lanes.v02` 或等价 lane 配置，服务清单以 `hwlab-v02` 为目标 namespace。 - 不把现有 `dev` 或 `prod` 环境静默改义为 v02。 - `deploy.json` 只承载 human-authored runtime intent；image digest、publish state、source commit、reuse evidence 不得写入 `deploy.json`。 - 如果 render 需要新增 schema 字段，字段必须向后兼容现有 DEV/PROD 配置，并在 v02 lane 中显式启用。