@@ -0,0 +1,147 @@
# v0.2 CI/CD 规格
本文是 HWLAB `v0.2` 在 G14 上接入 CI/CD 的长期规格。目标是把 `v0.2` 作为独立加法 lane 接入现有 G14 k3s、Tekton、GitOps 和 Argo CD 体系，同时保持 `G14` DEV/PROD 发布面稳定。
实施跟踪见 [pikasTech/HWLAB#530 ](https://github.com/pikasTech/HWLAB/issues/530 )，阶段计划见 [../plan/hwlab-v02-namespace-cicd.md ](../plan/hwlab-v02-namespace-cicd.md )。本文只记录稳定规格、边界和判定标准；不要把一次性执行记录、排障流水账或临时证据写入本文。
## 规格目标
- `v0.2` 固定作为 G14 上的新增 CI/CD lane，不改写现有 `G14` DEV/PROD lane。
- `v0.2` source branch 只保存源码、人写配置、模板、脚本和文档；CI/CD 生成物只进入 `v0.2-gitops` 。
- `hwlab-v02` 是唯一 runtime namespace； `74.48.78.17:19666/19667` 是唯一公网验收入口。
- 共享 G14 k3s、Tekton controller、Argo CD controller、本地 registry、工具镜像和脚本库；隔离分支、catalog、runtime path、Application、Pipeline、CronJob、ServiceAccount、SecretRef、PVC 和 FRP 入口。
- 旧 DEV/D601/main 门禁不得进入 `v0.2` 发布调用链；新增检查只覆盖固定 branch、namespace、catalog、runtime path、GitOps branch、Argo destination 和公网入口这些硬边界。
## 固定命名
| 对象 | v0.2 规格 |
| --- | --- |
| Source branch | `v0.2` |
| Source workspace | `G14:/root/hwlab-v02` |
| GitOps branch | `v0.2-gitops` |
| Artifact catalog | `v0.2-gitops:deploy/artifact-catalog.v02.json` |
| Runtime path | `v0.2-gitops:deploy/gitops/g14/runtime-v02` |
| Runtime namespace | `hwlab-v02` |
| Tekton Pipeline | `hwlab-ci/hwlab-v02-ci-image-publish` |
| Branch poller | `hwlab-ci/hwlab-v02-branch-poller` |
| Control-plane reconciler | `hwlab-ci/hwlab-v02-control-plane-reconciler` |
| Tekton ServiceAccount | `hwlab-ci/hwlab-v02-tekton-runner` |
| PipelineRun prefix | `hwlab-v02-ci-poll-<short12>` |
| Argo CD AppProject | `argocd/hwlab-v02` |
| Argo CD Application | `argocd/hwlab-g14-v02` |
| FRP Deployment | `hwlab-v02/hwlab-v02-frpc` |
| Web entry | `http://74.48.78.17:19666/` |
| API/live entry | `http://74.48.78.17:19667/health/live` |
`scripts/g14-gitops-render.mjs --lane v02` 是当前 `v0.2` GitOps render 入口。该 lane 必须把默认 source branch 改为 `v0.2` 、GitOps branch 改为 `v0.2-gitops` 、catalog 改为 `deploy/artifact-catalog.v02.json` 、runtime endpoint 改为 `19667` 、web endpoint 改为 `19666` ，并使用完整 source commit 作为 image tag。
## 真相源
`v0.2` 的发布真相按以下顺序判断：
1. live runtime： `hwlab-v02` namespace 中 Deployment/StatefulSet template、Pod ready、事件、日志和 `19666/19667` 公网 health。
2. Argo desired state： `argocd/hwlab-g14-v02` 的 revision、sync、health、source branch 和 runtime path。
3. GitOps branch： `v0.2-gitops` 中的 `deploy/artifact-catalog.v02.json` 与 `deploy/gitops/g14/runtime-v02/**` 。
4. Tekton 执行证据：`hwlab-v02-branch-poller` 、PipelineRun、TaskRun result、`gitops-promote` 终态。
5. 干净 source workspace： `origin/v0.2` 、`deploy/deploy.json` 、模板、render 脚本和 `--no-write` 输出。
旧 commit 记忆、`G14` /`G14-gitops` DEV/PROD 产物、D601 legacy 路径、source branch 中历史 generated 文件和临时 worktree 只能作为线索，不能作为 `v0.2` 发布通过证据。
## Source 与 GitOps 分层
`v0.2` source branch 可以包含：
- 源码、测试、文档和人写计划。
- `deploy/deploy.json` 或等价 lane 配置。
- k8s 模板、render 脚本、CI/CD helper 和 catalog schema。
`v0.2` source branch 不得跟踪：
- `deploy/artifact-catalog.v02.json` 。
- `deploy/gitops/g14/runtime-v02/**` 。
- Tekton/Argo 的 rendered runtime desired state。
- image digest、publish state、reuse evidence 或 CI 生成的 rollout metadata。
`v0.2-gitops` branch 必须包含：
- `deploy/artifact-catalog.v02.json` ，记录 image tag、digest、source commit、component identity、publish/reuse 状态。
- `deploy/gitops/g14/runtime-v02/**` ，作为 Argo CD 实际消费的 desired state。
- 必要的 generated metadata，但不得包含 Secret 值。
首次初始化时，如果 `v0.2-gitops:deploy/artifact-catalog.v02.json` 尚不存在，只允许由 `v0.2` lane 的正式初始化步骤创建第一版 catalog。不得 fallback 到 `G14` source catalog、`G14-gitops` catalog、DEV runtime path 或 source branch 生成物。
## CI/CD 链路
标准链路如下：
1. `hwlab-v02-branch-poller` 轮询 `origin/v0.2` ，按 source commit 创建 `hwlab-v02-ci-poll-<short12>` PipelineRun。
2. `prepare-source` checkout `v0.2` source，并从 `v0.2-gitops` 读取上一版 `deploy/artifact-catalog.v02.json` 。
3. 原语校验 task 只覆盖 repo 报告护栏、GitOps render 合同和必要的代码语法/单元检查；旧 DEV/D601/main gate 不进入 lane。
4. planner 根据 component input 判断 affected/reused services。
5. affected service 通过 BuildKit 发布到 G14 本地 registry；
6. promotion 刷新 `deploy/artifact-catalog.v02.json` ， `deploy/gitops/g14/runtime-v02/**` ，只推送到 `v0.2-gitops` 。
7. `hwlab-g14-v02` 从 `v0.2-gitops:deploy/gitops/g14/runtime-v02` 同步到 `hwlab-v02` 。
8. 验收只观察 `hwlab-v02` runtime 和 `19666/19667` 。
`v0.2` 可以复用 G14 的 registry、proxy、BuildKit、工具镜像和脚本库；不得复用 `hwlab-g14-ci-image-publish` 、`hwlab-g14-branch-poller` 、`hwlab-g14-control-plane-reconciler` 、`G14-gitops` runtime path 或 DEV/PROD Argo Application 作为 `v0.2` 发布入口。
## Artifact 与镜像身份
- `v0.2` 镜像 tag 使用完整 40 位 source commitId。
- runtime manifest 必须使用 digest pin 作为部署身份。
- catalog 必须记录 lane/profile、source branch、GitOps branch、source commitId、serviceId、image tag、digest、component identity 和 publish/reuse 状态。
- 同一 source commit 对同一 service 应生成同一镜像；lane 差异放在 manifest、env、SecretRef、namespace、FRP 和 DB 配置中，不 bake 进镜像。
- `deploy/deploy.json` 只承载人写 runtime intent，不承载 digest、publish state 或 reuse evidence。
## Kubernetes 与 Argo 边界
- `hwlab-v02` namespace 只能由 `v0.2` GitOps lane 管理。
- `argocd/hwlab-v02` AppProject destination 只能包含 `hwlab-v02` 。
- `argocd/hwlab-g14-v02` source 必须指向 `v0.2-gitops:deploy/gitops/g14/runtime-v02` ， `hwlab-v02` 。
- `hwlab-v02-frpc` 只能暴露 `19666/19667` ，不能复用 `17666/17667` 或 `18666/18667` 。
- `v0.2` Secret、DB 凭据、PVC、ServiceAccount 和 runtime config 必须独立命名或独立 namespace scope；文档、issue、trace 和 report 只记录 SecretRef 名称与 key，不记录值。
- `v0.2` 初期不新增自动 registry GC；后续如启用清理，selector 必须带 lane/profile 标签，registry digest 保护集必须同时覆盖 `G14-gitops` 与 `v0.2-gitops` 。
## 硬边界
以下边界是 `v0.2` CI/CD 的最小硬约束：
- source branch 必须是 `v0.2` 。
- GitOps branch 必须是 `v0.2-gitops` 。
- runtime namespace 必须是 `hwlab-v02` 。
- artifact catalog 必须是 `deploy/artifact-catalog.v02.json` 。
- runtime path 必须是 `deploy/gitops/g14/runtime-v02` 。
- Argo Application 必须是 `hwlab-g14-v02` ，且只能部署到 `hwlab-v02` 。
- source branch publish 后不得出现 `deploy/artifact-catalog.v02.json` 或 `deploy/gitops/g14/runtime-v02/**` 变更。
- GitOps promotion 的 changed paths 只能落在 `deploy/artifact-catalog.v02.json` 与 `deploy/gitops/g14/runtime-v02/**` 及必要的 v02 Argo/GitOps 元数据。
- 公网验收只能使用 `19666/19667` 。
- 旧 DEV/D601/main gate、fallback、legacy mode 和双路径兼容不得进入 `v0.2` 调用链。
这些硬边界优先在自然写入点做最小内联断言：render 断言 namespace/runtime path， ，
## G14 DEV/PROD 不变边界
接入 `v0.2` 不得改变以下对象：
- `G14` source branch 的 poller 语义。
- `G14-gitops` DEV/PROD catalog 与 runtime desired state。
- `hwlab-dev` 与 `hwlab-prod` namespace。
- `hwlab-g14-dev` 与 `hwlab-g14-prod` Argo Application。
- DEV `17666/17667` 与 PROD `18666/18667` FRP 入口。
- D601 legacy 回溯路径和旧运行面边界。
如果 `v0.2` 接入失败，回滚或暂停只能作用于 `hwlab-v02` lane：停止 `hwlab-v02-branch-poller` 、暂停或删除 `hwlab-g14-v02` 、回滚 `v0.2-gitops` runtime path、关闭 `hwlab-v02-frpc` 或清理 `hwlab-v02` namespace 资源；不得重启、删除或回滚 DEV/PROD 运行面。
## 验收标准
`v0.2` CI/CD 通过必须同时满足：
- `hwlab-ci` 中存在 `hwlab-v02-ci-image-publish` 、`hwlab-v02-branch-poller` 、`hwlab-v02-control-plane-reconciler` 和 `hwlab-v02-tekton-runner` 。
- 最新 `v0.2` source commit 对应的 PipelineRun 完成，且 promotion 写入 `v0.2-gitops` 。
- `v0.2-gitops` 中存在 `deploy/artifact-catalog.v02.json` 与 `deploy/gitops/g14/runtime-v02/**` 。
- `argocd/hwlab-g14-v02` 指向 `v0.2-gitops:deploy/gitops/g14/runtime-v02` ，
- `hwlab-v02` 中长驻 workload ready，没有把 DEV/PROD namespace 当成 `v0.2` 通过证据。
- `http://74.48.78.17:19666/` 返回 `v0.2` Cloud Web。
- `http://74.48.78.17:19667/health/live` 返回 `v0.2` runtime health， `hwlab-v02` /`v0.2` 对齐。
GitOps branch 已更新、source branch render 通过、PipelineRun 名称存在或 `G14` DEV/PROD health 正常，都不能单独代表 `v0.2` CI/CD 通过。
Codex