From 73773e2a9b170235f4c6e8e62cd729e832d4c3d0 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 28 May 2026 18:26:09 +0800 Subject: [PATCH] docs: add v0.2 cicd spec --- AGENTS.md | 1 + docs/plan/hwlab-v02-namespace-cicd.md | 2 +- docs/reference/g14-gitops-cicd.md | 2 +- docs/reference/spec-v02-cicd.md | 147 ++++++++++++++++++++++++++ 4 files changed, 150 insertions(+), 2 deletions(-) create mode 100644 docs/reference/spec-v02-cicd.md diff --git a/AGENTS.md b/AGENTS.md index fa1250bf..422c18c1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,6 +62,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 - DEV 运行态、端口、k3s 和 DB DNS 边界：[docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md) - G14 GitOps 发布、SecretRef preflight、runner/host 边界、镜像发布和单纯文档/CLI 直推规则：[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)、[docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md) - G14 GitOps CI/CD、Tekton/Argo CD、集群内 registry 和无锁镜像化发布：[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md) +- v0.2 CI/CD 加法 lane、`v0.2-gitops`、`hwlab-v02` 和 `19666/19667` 规格：[docs/reference/spec-v02-cicd.md](docs/reference/spec-v02-cicd.md) - G14 CI/CD 性能基线、根因分析和加速收益估算：[docs/reference/g14-cicd-performance.md](docs/reference/g14-cicd-performance.md) - Code Agent 对话就绪与真实回复判定：[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md) - DEV runtime hotfix runbook 与只读审计：[docs/reference/dev-runtime-hotfix-runbook.md](docs/reference/dev-runtime-hotfix-runbook.md) diff --git a/docs/plan/hwlab-v02-namespace-cicd.md b/docs/plan/hwlab-v02-namespace-cicd.md index 284ad374..4b4a0496 100644 --- a/docs/plan/hwlab-v02-namespace-cicd.md +++ b/docs/plan/hwlab-v02-namespace-cicd.md @@ -1,6 +1,6 @@ # HWLAB v0.2 namespace 与 CI/CD 扩容计划 -本文是 `v0.2` 分支上的执行计划，用于把 `hwlab-v02` 作为 G14 上的独立运行面接入当前 Tekton + GitOps + Argo CD 体系。目标是只做加法扩容，保持现有 G14 DEV/PROD 100% 稳定。 +本文是 `v0.2` 分支上的执行计划，用于把 `hwlab-v02` 作为 G14 上的独立运行面接入当前 Tekton + GitOps + Argo CD 体系。目标是只做加法扩容，保持现有 G14 DEV/PROD 100% 稳定。长期规格、命名、硬边界和验收标准以 [../reference/spec-v02-cicd.md](../reference/spec-v02-cicd.md) 为准；本文只保留迁移阶段、风险处理和执行顺序。 ## 固定命名 diff --git a/docs/reference/g14-gitops-cicd.md b/docs/reference/g14-gitops-cicd.md index 17338814..9ba23d35 100644 --- a/docs/reference/g14-gitops-cicd.md +++ b/docs/reference/g14-gitops-cicd.md @@ -8,7 +8,7 @@ G14 是 HWLAB 当前 DEV/PROD 原生 k8s 与 GitOps 运行面目标。G14 CI/CD - CI：Tekton 在 G14 k3s 内运行 `hwlab-g14-ci-image-publish` Pipeline，由 `scripts/g14-gitops-render.mjs` 直接生成原生 task；最小校验固定为 `repo-reports-guard`、`g14-contract-check`、`codex-api-forwarder-check`，随后按 component plan 做 per-service BuildKit publish 与 GitOps promote；没有 `CI.json` runner、DIND 单任务发布或 Docker fallback。 - Artifact：镜像使用 commit tag，例如 `127.0.0.1:5000/hwlab/hwlab-cloud-api:`；digest 由 registry 返回，CI report 只作为审计证据，不作为 CD 真相。发布态 artifact catalog 由 Tekton 写入 `G14-gitops:deploy/artifact-catalog.dev.json`。 - Branch split：`G14` 是源码监控分支，只保存人写源码、声明和 seed contract；`G14-gitops` 是 Tekton promotion 写入的生成分支，保存 `deploy/artifact-catalog.dev.json` 与 `deploy/gitops/g14/**` desired state。CI/CD 不再把 catalog promotion commit 写回 `G14`。 -- v0.2 扩容线：`v0.2` 必须从当前 `G14` fork 出来，并以 `G14:/root/hwlab-v02` 作为固定 source workspace、`hwlab-v02` 作为固定 runtime namespace。`v0.2` CI/CD 只能作为新增 lane 接入现有 G14 Tekton/Argo 体系，不得改写、删除、暂停或重定向现有 `G14` poller、`G14-gitops` DEV/PROD desired state、`hwlab-dev` 或 `hwlab-prod`。 +- v0.2 扩容线：`v0.2` 必须从当前 `G14` fork 出来，并以 `G14:/root/hwlab-v02` 作为固定 source workspace、`hwlab-v02` 作为固定 runtime namespace。`v0.2` CI/CD 只能作为新增 lane 接入现有 G14 Tekton/Argo 体系，不得改写、删除、暂停或重定向现有 `G14` poller、`G14-gitops` DEV/PROD desired state、`hwlab-dev` 或 `hwlab-prod`；详细规格见 [spec-v02-cicd.md](spec-v02-cicd.md)。 - CD：Argo CD 只消费 `G14-gitops:deploy/gitops/g14/runtime-dev` 与 `deploy/gitops/g14/runtime-prod` 的 Git desired state，不重新构建镜像，不读取 D601 状态，不获取 legacy DEV CD Lease。 - FRP：G14 DEV 通过 `hwlab-dev/hwlab-g14-frpc` 暴露 `17666/17667`，G14 PROD 通过 `hwlab-prod/hwlab-g14-prod-frpc` 暴露 `18666/18667`；`v0.2` 规划通过 `hwlab-v02` 内独立 frpc 暴露 `19666/19667`。master frps 的 `deploy/frp/frps.dev.toml` 与实际 `/etc/frp/frps.toml` 必须放行对应端口，但 `v0.2` 放行只能新增 19xxx 入口，不能复用或覆盖 DEV/PROD 入口。 - 并行性：不同 source commit 的 CI build 不共享发布锁；并行安全由 immutable commit tag/digest 和 Git desired state 保证。最终运行版本由 Argo CD 当前同步的 Git revision 决定。 diff --git a/docs/reference/spec-v02-cicd.md b/docs/reference/spec-v02-cicd.md new file mode 100644 index 00000000..8c43ba6c --- /dev/null +++ b/docs/reference/spec-v02-cicd.md @@ -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-` | +| 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-` 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；reused service 复用 catalog digest。 +6. promotion 刷新 `deploy/artifact-catalog.v02.json`，render `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`，destination 必须是 `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，promotion 断言 GitOps branch/changed paths，Argo spec 断言 destination，验收断言端口和 runtime identity。不要为每条设计约定再新增独立 preflight、guard、gate 或报告生成器。 + +## 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`，sync revision 与目标 GitOps revision 对齐。 +- `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，payload 中的 namespace、revision 或 runtime identity 能与 `hwlab-v02`/`v0.2` 对齐。 + +GitOps branch 已更新、source branch render 通过、PipelineRun 名称存在或 `G14` DEV/PROD health 正常，都不能单独代表 `v0.2` CI/CD 通过。