diff --git a/docs/plan/hwlab-v02-namespace-cicd.md b/docs/plan/hwlab-v02-namespace-cicd.md index 6e030806..52fd2d4d 100644 --- a/docs/plan/hwlab-v02-namespace-cicd.md +++ b/docs/plan/hwlab-v02-namespace-cicd.md @@ -8,8 +8,8 @@ - Source workspace：`G14:/root/hwlab-v02`，固定跟踪 `origin/v0.2`。 - Runtime namespace：`hwlab-v02`。 - GitOps branch：规划使用 `v0.2-gitops`，避免写入 `G14-gitops` 的 DEV/PROD desired state。 -- Artifact catalog：规划使用 `deploy/artifact-catalog.v02.json`。 -- Runtime path：规划使用 `deploy/gitops/g14/runtime-v02`。 +- Artifact catalog：规划使用 `v0.2-gitops:deploy/artifact-catalog.v02.json`；它是 CI/CD 生成物和 artifact identity truth，不在 `v0.2` source branch 跟踪或手写维护。 +- Runtime path：规划使用 `v0.2-gitops:deploy/gitops/g14/runtime-v02`；它是 rendered desired state，不在 `v0.2` source branch 跟踪。 - Argo CD Application：规划使用 `hwlab-g14-v02`。 - Public FRP entry：Cloud Web `http://74.48.78.17:19666/`，API/live `http://74.48.78.17:19667/health/live`。 @@ -18,9 +18,75 @@ - 不删除、不重命名、不复用 `hwlab-dev` 或 `hwlab-prod` namespace。 - 不改写现有 `G14` branch poller、`G14-gitops` DEV/PROD runtime path 或 `hwlab-g14-dev` / `hwlab-g14-prod` Argo Application。 - 不复用 DEV/PROD 的 FRP 端口、Secret、DB 凭据、PVC 或运行态热修资源。 +- 不清理或重构 `G14` source branch 里已经存在的历史生成物；本计划只规定 `v0.2` 起新增生成物彻底隔离到 GitOps branch。 +- 不在 `v0.2` source branch 新增或维护 `deploy/artifact-catalog.v02.json`、`deploy/gitops/g14/runtime-v02/*` 或 rendered Tekton/Argo runtime manifests。 +- 阻碍 `v0.2` 扩容的旧 DEV/D601/main 门禁一律从 `v0.2` 调用链彻底拆除；不做兼容性迁移、fallback、legacy mode、绕路或在旧门禁上叠加例外。 - 不在 master server 上运行仓库级 check、browser smoke、镜像构建或集群写操作。 - 在计划被 issue 追踪并人工确认前，不执行 namespace 创建、Argo sync、FRP 切流或 Tekton 控制面 apply。 +## 技术决策：v0.2 生成物隔离 + +`G14` 分支上现有 source 里的历史生成物保持不动，避免为了整理历史而影响 DEV/PROD 稳定性。从 `v0.2` 开始采用更严格的 source/GitOps 分层：source branch 只存人类意图、源码、模板、脚本和计划；GitOps branch 存 CI/CD 生成的 artifact catalog、runtime manifests 和 Argo 可消费的 desired state。 + +`v0.2` source branch 可以包含： + +- `deploy/deploy.json` 或等价 lane 配置，作为 human-authored runtime intent。 +- k8s 模板、render 脚本、CI/CD helper 和文档计划。 +- artifact catalog schema、示例或说明，但示例不得伪装成当前发布真相。 + +`v0.2-gitops` branch 必须包含： + +- `deploy/artifact-catalog.v02.json`，记录 image tag、digest、source commit、component commit/hash、publish/reuse evidence。 +- `deploy/gitops/g14/runtime-v02/*`，记录 Argo CD 实际消费的 rendered manifests。 +- 必要的 generated rollout metadata，但不得包含 Secret 值。 + +CI/CD 的初始化规则：Tekton 执行 `v0.2` lane 时必须先读取 `v0.2-gitops:deploy/artifact-catalog.v02.json`。首次初始化时若该文件尚不存在，只允许由 `v0.2` lane 的正式初始化步骤创建第一版 catalog；不得 fallback 到 `G14` source catalog、`G14-gitops` catalog、DEV runtime path 或 source branch 生成物。publish 成功后，刷新后的 catalog 和 runtime manifests 只提交到 `v0.2-gitops`，不得写回 `v0.2` source branch。 + +真相源划分如下： + +| 内容 | `v0.2` source branch | `v0.2-gitops` branch | +|---|---|---| +| 人类运行配置 | 是，`deploy/deploy.json` 或 lane 配置 | 否 | +| 模板和 render 逻辑 | 是 | 否 | +| artifact identity | 否 | 是，`deploy/artifact-catalog.v02.json` | +| rendered runtime manifests | 否 | 是，`deploy/gitops/g14/runtime-v02/*` | +| Argo CD 消费路径 | 否 | 是 | + +这个决策的目标是避免 `v0.2` source branch 出现“看似可手改、实际由 CI 生成”的半真相文件；后续所有复用、跳过构建、digest 对齐和 runtime identity 判断都必须以 GitOps branch 的 artifact catalog 为输入。 + +## 陈旧门禁与处理策略 + +扩容 `v0.2` 时会遇到两类历史依赖：核心 artifact/GitOps 机制需要保留并参数化；旧 DEV-only 自检、preflight、guard 和报告校验不得进入 `v0.2` 路径。凡是阻碍 `v0.2` 的旧门禁，处理方式只有从 `v0.2` 调用链删除；不做兼容性迁移、不做 fallback、不保留 legacy mode、不在旧门禁上加例外。 + +必须参数化保留的核心路径： + +| 位置 | 当前问题 | v0.2 处理 | +|---|---|---| +| `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。 | + +不应进入 `v0.2` 发布门禁的陈旧路径： + +| 位置 | 陈旧点 | 处理 | +|---|---|---| +| `scripts/src/dev-gate-preflight.mjs` | 默认 `origin/main`、`hwlab-dev`、D601/kubectl 口径和旧 `16666/16667` DEV 入口。 | 从 `v0.2` 发布调用链删除；不得改造成 `v0.2` 兼容门禁。 | +| `scripts/src/artifact-runtime-readiness-guard.mjs` | 以 source catalog、latest-main 和 DEV runtime identity 为核心假设。 | 从 `v0.2` 发布调用链删除；如需检查，新增只读 `v0.2` 最小 runtime identity 检查，不复用旧 guard。 | +| `scripts/validate-artifact-catalog.mjs` | 强制校验 `deploy/artifact-catalog.dev.json` 与 `hwlab-dev`。 | 不在 `v0.2` 路径运行；不把它改成多 lane 兼容脚本。 | +| `scripts/src/deploy-desired-state-plan.mjs` | 默认从 source 读取 DEV catalog，容易形成 source desired-state 幻觉。 | 不作为 `v0.2` apply 前门禁；若阻碍扩容，直接移出 `v0.2` 发布流程。 | +| `scripts/src/dev-cloud-workbench-smoke-lib.mjs`、`scripts/src/rpt004-mvp-e2e-harness.mjs`、M3/M4 DEV smoke | 固定 DEV 端口、DEV-LIVE 术语和历史报告 schema。 | 不复用为 `v0.2` gate；必要时新增独立 `v02` smoke，只验证 `19666/19667` 与 `hwlab-v02`。 | +| `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` 新增门禁必须保持最小，只覆盖以下高价值风险： + +- 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` 通过证据。 + ## 实施阶段 1. 文档与 issue 基线 @@ -33,14 +99,15 @@ - Secret 计划只记录对象名和 key，不在文档、issue、日志或 trace 中写入值。 3. GitOps desired state 扩容 - - 扩展 render 支持显式 lane 参数：source branch `v0.2`、catalog `deploy/artifact-catalog.v02.json`、runtime path `deploy/gitops/g14/runtime-v02`、namespace `hwlab-v02`。 - - 新增 `v0.2-gitops` 生成分支或等价隔离 GitOps 目标；不得把 v02 生成物写入 DEV/PROD runtime path。 + - 扩展 render 支持显式 lane 参数：source branch `v0.2`、GitOps branch `v0.2-gitops`、catalog `deploy/artifact-catalog.v02.json`、runtime path `deploy/gitops/g14/runtime-v02`、namespace `hwlab-v02`。 + - render 在执行时从 `v0.2-gitops` 读取上一版 catalog；catalog 缺失时只能执行 `v0.2` 正式初始化或失败，不能 fallback 到 DEV/G14 catalog。 + - 新增 `v0.2-gitops` 生成分支或等价隔离 GitOps 目标；不得把 v02 生成物写入 DEV/PROD runtime path，也不得写回 `v0.2` source branch。 - 新增 frpc runtime manifest，只暴露 `19666/19667`，内部服务端口继续按现有 Cloud Web `8080`、edge/API `6667` 约定。 4. Tekton lane 扩容 - 在 `hwlab-ci` 中新增 `v0.2` poller/reconciler，或把现有控制面改为显式多 lane 配置。 - `v0.2` PipelineRun 前缀使用 `hwlab-v02-ci-poll-`，方便和 `hwlab-g14-ci-poll-` 区分。 - - build/publish helper 可复用现有工具镜像、registry 和 BuildKit 机制，但产物 catalog、GitOps branch、runtime path 必须隔离。 + - Pipeline 必须 checkout `v0.2` source 和 `v0.2-gitops` generated state；build/publish helper 可复用现有工具镜像、registry 和 BuildKit 机制，但产物 catalog、GitOps branch、runtime path 必须隔离。 5. Argo CD 扩容 - 新增 `hwlab-g14-v02` Application，source 指向 `v0.2` 专属 GitOps lane，destination 指向 `hwlab-v02`。 @@ -50,6 +117,7 @@ 6. `deploy.json` 扩容 - 在 `v0.2` 分支上新增显式 v02 environment 或 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 中显式启用。 7. 验收