From 53dafe297a4d9cb4771ff4916c3473fffacef8c0 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 29 May 2026 20:41:43 +0800 Subject: [PATCH] docs: specify v02 git mirror boot variables --- docs/reference/spec-v02-cicd.md | 47 ++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/docs/reference/spec-v02-cicd.md b/docs/reference/spec-v02-cicd.md index 71a22c5a..c68823d8 100644 --- a/docs/reference/spec-v02-cicd.md +++ b/docs/reference/spec-v02-cicd.md @@ -2,11 +2,11 @@ 本文是 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)，原 `docs/plan/hwlab-v02-namespace-cicd.md` 阶段计划全文已迁入该 issue 评论。本文只记录稳定规格、边界和判定标准；不要把一次性执行记录、排障流水账或临时证据写入本文。 +实施跟踪见 [pikasTech/HWLAB#530](https://github.com/pikasTech/HWLAB/issues/530)，env 容器复用、三变量启动和 git mirror 加速设计见 [pikasTech/HWLAB#572](https://github.com/pikasTech/HWLAB/issues/572)。原 `docs/plan/hwlab-v02-namespace-cicd.md` 阶段计划全文已迁入 #530 评论。本文只记录稳定规格、边界和判定标准；不要把一次性执行记录、排障流水账或临时证据写入本文。 ## 在系统中的职责划分 -`v0.2` CI/CD 是 G14 上的加法 lane：source branch、GitOps branch、runtime namespace、artifact catalog、Argo Application、Tekton Pipeline 和 FRP 入口均独立于 DEV/PROD。它共享 G14 k3s、Tekton controller、Argo CD controller、本地 registry 和构建工具，但不能复用 DEV/PROD runtime path、namespace、Application 或公网端口作为 v02 发布证据。 +`v0.2` CI/CD 是 G14 上的加法 lane：source branch、GitOps branch、runtime namespace、artifact catalog、Argo Application、Tekton Pipeline 和 FRP 入口均独立于 DEV/PROD。它共享 G14 k3s、Tekton controller、Argo CD controller、本地 registry 和构建工具，但不能复用 DEV/PROD runtime path、namespace、Application 或公网端口作为 v02 发布证据。code-only fast lane 可以消费独立 `devops-infra` 集群提供的只读 git mirror/cache；该 mirror/cache 是跨项目 DevOps 基础设施，不属于 `hwlab-v02` runtime namespace，也不改变当前 G14 registry 的部署位置或镜像引用真相。 ## 内部架构 @@ -50,6 +50,8 @@ CI/CD 内部由 branch poller、PipelineRun、component planner、BuildKit publi | 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` | +| Git mirror/cache | 独立 `devops-infra` 集群只读服务 | +| Registry | 维持当前 G14 `hwlab-ci/hwlab-registry` | `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。 @@ -103,11 +105,35 @@ CI/CD 内部由 branch poller、PipelineRun、component planner、BuildKit publi `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` 发布入口。 +## Env 容器复用与三变量启动 + +`v0.2` code-only fast lane 的 runtime desired state 由三类输入组成：可复用 env image digest、自动推导的 code boot metadata、以及既有 service runtime config。开发者仍按当前 DEV/OPS 流程提交 `v0.2` source commit 和维护 `deploy/deploy.json`；发布入口不得要求人工填写 repo、commitId 或 boot script 路径。 + +code boot metadata 固定映射到三个启动环境变量： + +| 变量 | 自动推导来源 | 约束 | +| --- | --- | --- | +| `HWLAB_BOOT_REPO` | `v0.2` lane 的 canonical GitHub source repo 配置 | 必须是 canonical GitHub URL；用于身份记录，运行时读取由 resolver 自动分流到 mirror/cache。 | +| `HWLAB_BOOT_COMMIT` | `hwlab-v02-branch-poller` 观察到的 `origin/v0.2` 完整 source commit SHA，也就是 PipelineRun revision | 必须是完整 40 位 commit SHA；禁止 branch、tag、`latest` 或人工覆盖。 | +| `HWLAB_BOOT_SH` | service model 或 `deploy/deploy.json` 中 serviceId 到 boot script 的映射，默认形态为 `deploy/runtime/boot/.sh` | 必须是 repo 内相对路径；禁止绝对路径、`..` 越界和从 env image 中隐式寻找旧脚本。 | + +CI/CD 必须把三变量同时写入 `deploy/artifact-catalog.v02.json`、rendered workload Pod template env/annotation 和 runtime health identity。三变量是由 lane 自动推导的发布事实，不是人工 OPS 参数；如果自动推导缺失或无法证明 `HWLAB_BOOT_COMMIT` 属于 `v0.2` 允许 ancestry，本轮 promotion 必须失败。 + +推荐启动形态是 initContainer + `emptyDir` + generic env image。initContainer 或 env image 内的 launcher 读取三变量，通过 resolver 把 `HWLAB_BOOT_REPO` 的只读 fetch/checkout 自动分流到 `devops-infra` git mirror/cache，按 `HWLAB_BOOT_COMMIT` checkout 到 Pod 私有 `emptyDir`；main container 复用同一 env image，并执行 checkout 后代码目录里的 `$HWLAB_BOOT_SH`。env image 只承载系统依赖、runtime、launcher、git client 和通用工具，不把业务代码或旧 boot script 当作运行真相。 + +code-only 变更时，planner 必须输出 `envChanged=false`、`codeChanged=true`，跳过 BuildKit image publish，复用上一版 env image digest，只更新 catalog 和 workload Pod template 中的 `HWLAB_BOOT_COMMIT`、code identity annotation 与相关 health metadata。Kubernetes 原生 Deployment/StatefulSet rolling update 仍由 Pod template hash 变化触发；不需要在容器内长期驻留 watcher，也不把 `git pull` 结果作为运行真相。 + +`devops-infra` git mirror/cache 是只读、allowlisted、PVC-backed 或等价持久化服务，只缓存 GitHub 对象。只有 mirror controller 持有 GitHub 远端凭证；`hwlab-v02`、AgentRun 和其他业务 namespace 只能访问只读 mirror/cache endpoint，不持有 GitHub deploy key。runtime checkout 失败、mirror miss 超过明确等待窗口、commit ancestry 不满足 lane 约束或 boot script 校验失败时，Pod 必须启动失败或 NotReady，不得回退到 env image 内旧代码，也不得在业务 namespace 直连 GitHub 拉取。 + +git mirror/cache 接入方式遵循“写 GitHub、读自动加速”。GitOps 和 deploy spec 中的 repo 字段仍记录 canonical GitHub URL；launcher 或只读 runtime image 内的 resolver 负责读路径自动分流。任何需要 push `v0.2-gitops` 的 promotion task 必须继续 push GitHub canonical remote，不能被 mirror rewrite 劫持。 + +registry 与 git mirror/cache 分属不同基础设施边界。registry 保持当前 G14 `hwlab-ci/hwlab-registry`，继续通过 repository prefix 服务 HWLAB、AgentRun 和后续 lane；新增 `devops-infra` git mirror/cache 不触发 registry 迁移，也不要求在 `devops-infra` 复制 registry。 + ## 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 状态。 +- catalog 必须记录 lane/profile、source branch、GitOps branch、source commitId、serviceId、image tag、digest、component identity 和 publish/reuse 状态；启用 env 容器复用时还必须记录 `runtimeMode=env-reuse-git-mirror-checkout`、`environmentImage`、`environmentDigest`、`environmentInputHash`、`bootRepo`、`bootCommit`、`bootSh`、`codeInputHash` 和三变量写入证据。 - 同一 source commit 对同一 service 应生成同一镜像；lane 差异放在 manifest、env、SecretRef、namespace、FRP 和 DB 配置中，不 bake 进镜像。 - `deploy/deploy.json` 只承载人写 runtime intent，不承载 digest、publish state 或 reuse evidence。 @@ -134,6 +160,8 @@ CI/CD 内部由 branch poller、PipelineRun、component planner、BuildKit publi - 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` 调用链。 +- env 容器复用 fast lane 中，`HWLAB_BOOT_REPO`、`HWLAB_BOOT_COMMIT` 和 `HWLAB_BOOT_SH` 必须由 CI/CD 自动推导并写入 GitOps desired state，不得作为人工发布参数或 runtime 临时 patch。 +- git mirror/cache 必须来自独立 `devops-infra` 只读服务；`hwlab-v02` runtime namespace 不部署 mirror、不持有 GitHub deploy key、不在 mirror miss 时直连 GitHub fallback。 这些硬边界优先在自然写入点做最小内联断言：render 断言 namespace/runtime path，promotion 断言 GitOps branch/changed paths，Argo spec 断言 destination，验收断言端口和 runtime identity。不要为每条设计约定再新增独立 preflight、guard、gate 或报告生成器。 @@ -161,6 +189,9 @@ CI/CD 内部由 branch poller、PipelineRun、component planner、BuildKit publi - `hwlab-v02` 中长驻 workload ready，没有把 DEV/PROD namespace 当成 `v0.2` 通过证据。 - `gitops-promote` 推送 `v0.2-gitops` 后应触发 `argocd/hwlab-g14-v02` hard refresh，减少 GitOps push 与 Argo 仓库发现之间的漂移窗口；refresh 触发失败只作为低噪声事件输出，最终通过仍由 `runtime-ready` 判定。 - `runtime-ready` 必须以 workload Pod template 的 source commit 判断 Argo 刷新，并在 Argo 刷新超时、observer RBAC 不足或 workload 未就绪时失败；不得把 CrashLoop、未刷新或公网不可用的 runtime 标成绿色。 +- 启用 env 容器复用的服务必须在 catalog、Pod template annotation/env 和 `/health/live` 或等价 runtime identity 中同时暴露 env image digest 与 `HWLAB_BOOT_REPO`/`HWLAB_BOOT_COMMIT`/`HWLAB_BOOT_SH`；只暴露镜像 digest 不能证明 code-only rollout 已生效。 +- code-only rollout 的 PipelineRun 必须能证明没有发布新 env image、复用了上一版 env digest、只更新 boot commit/code identity，并由 Kubernetes Pod template hash 触发滚动。 +- `devops-infra` git mirror/cache miss、commit ancestry 拒绝或 boot script 校验失败必须导致本轮 rollout fail closed，不得隐式回退到 GitHub 或 env image 内旧代码。 - `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` 对齐。 @@ -184,6 +215,14 @@ GitOps branch 已更新、source branch render 通过、PipelineRun 名称存在 阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：涉及 Code Agent 时使用短连接 submit/result/trace 轮询，确认 `status=completed` 且 assistant reply 非空；不得只用 `/health/live` 中 `codeAgent=ready` 证明 provider 鉴权通过。 +## T5 + +阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：对启用 env 容器复用的服务触发一次 code-only commit，确认 PipelineRun 标记 `envChanged=false`、复用上一版 env digest、catalog 与 Pod template 写入 `HWLAB_BOOT_REPO`、`HWLAB_BOOT_COMMIT`、`HWLAB_BOOT_SH`，runtime health 同时暴露 env digest 和 boot commit，且 `HWLAB_BOOT_COMMIT` 来自完整 `origin/v0.2` source commit SHA。 + +## T6 + +阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：在不打印任何 GitHub 凭证的前提下确认 runtime checkout 读路径命中 `devops-infra` git mirror/cache，业务 namespace 没有 GitHub deploy key；模拟 mirror miss 或非法 commit 时 rollout fail closed，不回退到 GitHub 直连或 env image 内旧代码。 + ## 规格的实现情况 | 规格项 | 状态 | 说明 | @@ -195,6 +234,8 @@ GitOps branch 已更新、source branch render 通过、PipelineRun 名称存在 | Argo v02 Application | 已实现 | `hwlab-g14-v02` 指向 v02 GitOps path 和 namespace。 | | FRP `19666/19667` 入口 | 已实现 | 由 `hwlab-v02-frpc` 与 master frps allowlist 共同提供。 | | SecretRef 独立与 provider 验收 | 已实现/持续约束 | SecretRef 已独立；验收必须做真实短连接聊天。 | +| env 容器复用三变量启动 | 规划中 | 由 CI/CD 自动推导 `HWLAB_BOOT_REPO`、`HWLAB_BOOT_COMMIT`、`HWLAB_BOOT_SH`，code-only rollout 复用 env image digest，只更新代码身份。 | +| `devops-infra` git mirror/cache 加速 | 规划中 | 独立基础设施集群承载只读 mirror/cache；runtime namespace 不持有 GitHub deploy key，registry 保持 G14 `hwlab-ci/hwlab-registry`。 | | 自动 registry GC | 未实现 | 初期不启用自动 GC，后续需 lane/profile 保护集。 | ## 平行 lane 运维边界