Codex
41 KiB
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，env 容器复用、三变量启动和 git mirror 加速设计见 pikasTech/HWLAB#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 发布证据。code-only fast lane 必须消费独立 devops-infra 集群提供的 git mirror/relay；该 mirror/relay 是跨项目 DevOps 基础设施，不属于 hwlab-v02 runtime namespace，也不改变当前 G14 registry 的部署位置或镜像引用真相。
内部架构
CI/CD 内部由 UniDesk 手动触发入口、PipelineRun、component planner、BuildKit publish、GitOps promotion、Argo sync、GitHub flush 和公网验收构成。v0.2 不设置 branch poller、control-plane reconciler 或其他 CronJob；source branch 只保存源码和人写配置；v0.2-gitops branch 保存 catalog 和 rendered runtime desired state；live runtime 是最终通过证据。
v0.2 的 GitOps 写路径采用真正写 mirror：promotion 先把 v0.2-gitops 写入 devops-infra 本地 git mirror/relay，Argo CD 从本地 mirror/relay 读取该 revision 并 rollout，CI 关键路径不等待 GitHub push。GitHub pikasTech/HWLAB 仍是长期源码与归档上游，但对 v0.2-gitops 来说是由 mirror/relay 负责 flush 的异步上游，不再是 promotion task 的同步写入目标。
API 接口说明
| 接口 | 说明 |
|---|---|
scripts/g14-gitops-render.mjs --lane v02 |
v02 GitOps render 入口，负责 namespace、runtime path、catalog 和 endpoint 固定。 |
Tekton hwlab-v02-ci-image-publish |
构建 affected images、复用 unchanged digest，并 promotion 到 v0.2-gitops。 |
devops-infra git mirror/relay |
读写 v0.2 allowlist refs；CI 读 source/catalog、写 v0.2-gitops，并通过手动 CLI flush 到 GitHub。 |
Argo argocd/hwlab-g14-v02 |
从 devops-infra 本地 mirror/relay 的 v0.2-gitops:deploy/gitops/g14/runtime-v02 同步到 hwlab-v02。 |
http://74.48.78.17:19666/ |
v02 Cloud Web 公网入口。 |
http://74.48.78.17:19667/health/live |
v02 API/live 公网验收入口。 |
规格目标
v0.2固定作为 G14 上的新增 CI/CD lane，不改写现有G14DEV/PROD lane。v0.2source 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、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 |
| Manual trigger | UniDesk CLI bun scripts/cli.ts hwlab g14 control-plane trigger-current --lane v02 --confirm |
| Scheduler/CronJob | 不创建、不保留 v02 CronJob；发布只由手动 CLI 创建 commit-pinned PipelineRun |
| 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 |
| Git mirror/relay | 独立 devops-infra 集群读写服务；不设 CronJob；读 source/catalog，写 v0.2-gitops，按需由 UniDesk CLI 手动 sync/flush |
| 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。
真相源
v0.2 的发布真相按以下顺序判断：
- live runtime：
hwlab-v02namespace 中 Deployment/StatefulSet template、Pod ready、事件、日志和19666/19667公网 health。 - Argo desired state：
argocd/hwlab-g14-v02的 revision、sync、health、source branch 和 runtime path。 - devops-infra mirror/relay 中的 GitOps branch：
v0.2-gitops中的deploy/artifact-catalog.v02.json与deploy/gitops/g14/runtime-v02/**。 - Tekton 执行证据：UniDesk
trigger-current返回的 PipelineRun、TaskRun result、gitops-promote终态。 - GitHub 上游归档状态：mirror/relay flush 后的
origin/v0.2-gitops与origin/v0.2。 - 干净 source workspace：
origin/v0.2、deploy/deploy.json、模板、render 脚本和--no-write输出。
旧 commit 记忆、G14/G14-gitops DEV/PROD 产物、D601 legacy 路径、GitHub 上游尚未 flush 的短暂落后、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 链路
标准链路如下：
- UniDesk CLI
hwlab g14 control-plane trigger-current --lane v02 --confirm解析当前origin/v0.2完整 source commit SHA，先复核devops-inframirror 的localV02ref，必要时自动执行一次 bounded manualgit-mirror syncJob，再创建 commit-pinnedhwlab-v02-ci-poll-<short12>PipelineRun；默认--dry-run只返回将要创建的 manifest 和 mirror pre-sync 计划。 prepare-source通过devops-inframirror checkoutv0.2source，并从 mirror 中的v0.2-gitops读取上一版deploy/artifact-catalog.v02.json。- CI/CD 校验只保留最小构建、语法、打包和冒烟检查；旧 DEV/D601/main gate、运行时内部证明型校验、健康诊断重断言和历史预检不进入 lane。
- planner 根据 component input 判断 affected/reused services。
- affected service 通过 BuildKit 发布到 G14 本地 registry；reused service 复用 catalog digest。
- promotion 刷新
deploy/artifact-catalog.v02.json，renderdeploy/gitops/g14/runtime-v02/**，只推送到devops-inframirror/relay 的v0.2-gitops。 hwlab-g14-v02从本地 mirror/relay 的v0.2-gitops:deploy/gitops/g14/runtime-v02同步到hwlab-v02。- UniDesk CLI 或 mirror/relay flush 操作把本地
v0.2-gitops推送到 GitHub canonical remote；flush 不在 CI runtime-ready 的关键路径内，但必须可查询 pending、lastFlushed 和 failure。 - 验收只观察
hwlab-v02runtime 和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 发布入口。运行时不得为每个版本硬编码 namespace、catalog、runtime path 或健康判断；版本差异只通过 deploy.json.lanes[profile]、GitOps render 输入和实际 runtime 对象表达，新增版本不得新增运行时代码分支。
v0.2 不设自动轮询发布。历史上若存在 hwlab-v02-branch-poller、hwlab-v02-control-plane-reconciler 或等价 CronJob，均视为迁移残留，应由 UniDesk control-plane apply 清理；后续发布、重跑、暂停和恢复都通过手动 CLI 触发或停止创建新的 PipelineRun 完成，不新增替代 CronJob。
devops-infra git mirror/relay 同样不设周期 CronJob。标准触发命令 bun scripts/cli.ts hwlab g14 control-plane trigger-current --lane v02 --confirm 会在创建 PipelineRun 前按需同步 mirror；bun scripts/cli.ts hwlab g14 git-mirror sync --confirm 只作为显式 mirror 维护或诊断入口。promotion 成功后可执行 bun scripts/cli.ts hwlab g14 git-mirror flush --confirm 把本地 v0.2-gitops 推送到 GitHub。git-mirror apply 维护 mirror 的 PVC、读服务、写服务、同步/flush 脚本和旧 CronJob 清理；git-mirror sync 创建一次性 Job，只同步 allowlist refs v0.2、v0.2-gitops、G14 和 G14-gitops，先 fetch 到隐藏 staging refs，校验 commit/tree/object closure，再用 update-ref 发布到公开 refs。这样 mirror read path 与 GitOps write path 都落在本地磁盘和集群网络，同时避免 CI 看到 ref 已更新但对象还不可 checkout 的半发布窗口。
hwlab-cli 不属于 v0.2 CI/CD service matrix。它是 G14:/root/hwlab-v02 固定 repo 内的短连接源码 client，只用 Bun 直接调用 Cloud Web 同源 API；不得加入 PipelineRun services 参数、artifact catalog、BuildKit publish、runtime desired state、Deployment、Service、Job 或 image build。若出现 build-hwlab-cli TaskRun、hwlab-cli artifact service、CLI 镜像或 CLI 常驻服务，均视为旧门禁/旧断言残留，直接删除并回到 docs/reference/spec-v02-hwlab-cli.md 的短连接 client 口径。
rpt004:mvp:e2e、runner:issue-visibility:preflight 和 dev-base-image:preflight 不属于 v0.2 最小 CI/CD 校验入口；它们代表旧验收、旧 runner 可见性预检或旧镜像基础预检口径。v0.2 check/validate 不再引用这些任务，若它们重新进入默认 check plan、package script 或 PipelineRun，应直接删除该入口，而不是为其补兼容逻辑。
写 mirror 的一致性模型是 local-first、manual-flush。promotion task 只能持有 mirror/relay 写凭证，不持有 GitHub deploy key；GitHub deploy key 只存在于 devops-infra mirror/relay sync/flush 边界。mirror/relay 必须在本地 receive 期间完成 object closure、目标 branch allowlist、non-fast-forward 拒绝和 changed-path 最小校验；receive 成功后本地 ref 即为 Argo 可消费事实。flush 失败不得回滚已经 rollout 的本地 GitOps revision，但必须保留 pending/outbox 状态，下一次手动 flush 可重试并输出 last error，不得静默丢弃。
性能预算与回归判定
v0.2 fast lane 的性能目标是让 code-only/env-reuse 场景主要受 G14 集群调度、PVC 和本地磁盘 I/O 限制，而不是受 GitHub 网络、重复依赖安装或无效 runtime 等待限制。性能预算只用于发现退化和指导排障，不新增发布门禁；发现退化时先按本节做现场热探测，再决定是否需要完整 CI/CD 复跑。
代表性 env-reuse 场景的对比基线如下。后续更换 runner、PVC、Tekton controller、Argo repo server 或 mirror 存储后，必须重新测量并更新本表的预算口径。
| 场景 | 关键路径总耗时 | 主要阶段表现 | 判定口径 |
|---|---|---|---|
| env-reuse + mirror-write 初始路径 | 约 108s | prepare-source 约 56s；包含无效 npm ci 和多余探针；runtime wait 仍执行 |
只作为旧基线，不应回归。 |
移除 prepare-source 中的 npm ci |
约 76s | prepare-source 降到约 21s；其余路径仍有多余探针和 runtime wait |
不应再恢复依赖安装。 |
| 剪裁 fast-path 探针 | 约 50s | prepare-source 约 11s；gitops-promote 约 7s；runtime-ready 约 17s |
runtime 有实际变化时的合理预算。 |
| P1 no-op runtime skip | 约 37s | prepare-source 约 10s；plan-artifacts 约 6s；collect-artifacts 约 7s；gitops-promote 约 8s；runtime-ready 跳过 |
source-only 且 runtime identity-only 变化时的目标预算。 |
当前预算判定：source-only、所有 service 都复用 artifact、GitOps runtime 只发生 source identity 变化时，总耗时应接近 40s；超过 50s 需要先查是否误触发 runtime-ready、是否发生 GitHub 直连、是否恢复了 npm ci 或无效 preflight。真正需要 rollout 的 code-only 变更允许约 50s，因为 runtime-ready 必须等待 Argo 与 workload 收敛。涉及 BuildKit publish、env image rebuild、registry push 或真实 runtime 滚动时，不适用 40s 预算，应按 affected service 的 build 耗时单独测量。
关键阶段预算如下：
| 阶段 | 正常预算 | 退化信号 |
|---|---|---|
prepare-source |
约 10-12s | 超过 20s、出现 npm ci、访问 GitHub canonical remote、catalog fetch 超过数秒。 |
source-clone |
约 1-2s | 超过 5s 通常说明没有命中 devops-infra mirror 或 PVC/网络异常。 |
catalog-fetch |
小于 1s | 超过 3s 先查 mirror refs、object closure 和 catalog branch。 |
plan-artifacts |
约 5-7s | buildServices 或 rolloutServices 非空但本轮只改 CI/CD 文档/脚本时，先查 component input 与 catalog 是否加载。 |
collect-artifacts |
约 6-8s | 未输出运行时服务矩阵的 artifact_reuse 或全部 runtime services reuse 时，先查 catalog digest、PipelineRun services 参数和 service identity；hwlab-cli 不应出现在 build/reuse 统计中。 |
gitops-promote no-op |
约 7-9s | 未输出 skipped-runtime-unchanged，或写入了 v0.2-gitops，说明 runtime 比对未命中。 |
runtime-ready |
no-op 应跳过；真实 rollout 约 15-20s | no-op 场景出现 TaskRun 即为 P1 退化；真实 rollout 超时则按 Argo/workload 排障。 |
性能优化原理
prepare-source 不安装依赖。该 task 只负责 checkout source、读取上一版 catalog、输出 source identity 和基础文件，不运行 npm ci、不探测 npm registry、不做与后续 task 重复的工具链检查。需要依赖的语法检查、render test 或 build task 必须使用各自镜像内已有工具或在专属阶段处理，不能把全仓依赖安装塞回 source 准备阶段。
Git 读写都走 devops-infra 本地 mirror/relay。读路径用 HTTP mirror checkout v0.2 source 和 v0.2-gitops catalog；写路径把 promotion 推到 mirror/relay 的 v0.2-gitops，Argo 也从 mirror/relay 读取。这样 source clone、catalog fetch、GitOps clone/push 都落在集群内网络和本地磁盘，GitHub 只通过手动 sync/flush 进入或离开本地 mirror，不在 CI 关键路径内。
env image 复用把系统依赖和业务代码身份分离。environmentDigest 表示可复用运行环境，HWLAB_BOOT_REPO、HWLAB_BOOT_COMMIT 和 HWLAB_BOOT_SH 表示本次代码启动身份。code-only 变更只更新 boot metadata 和 runtime identity，不发布新 env image；只有 environmentInputHash 变化时才进入 env rebuild。
P1 no-op runtime skip 只跳过无实际 runtime 变化的等待。planner 输出 buildServices=[] 且 rolloutServices=[] 后，gitops-promote 会在写入前对旧 runtime-v02 与新 render 结果做归一化比较：忽略 source commit、artifact source commit、boot commit 和等价 commit env/annotation 这类 identity-only 字段。如果归一化结果相同，promotion 输出 skipped-runtime-unchanged，把 Tekton result runtime-ready-required=false 写出，并跳过 GitOps commit、push、Argo hard refresh 和 runtime-ready。如果 workload spec、image digest、env image、SecretRef、Service、Ingress、FRP、ConfigMap 或 rollout service 有实际变化，必须保持 runtime-ready-required=true 并等待 runtime 收敛。
快速优化不能绕过 fail-closed 语义。mirror miss、commit ancestry 不合法、boot script 缺失、digest 缺失、Argo observer RBAC 不足、workload 未 ready 或公网 health 不一致，都不能为了追求耗时而降级为 warning。允许跳过的只有已经证明 runtime desired state 没有实际变化的等待。
快速排障
先看一次 PipelineRun 总览，确认是否是性能退化、构建退化还是 runtime 收敛失败：
bun scripts/cli.ts ssh G14:k3s script -- 'set -eu
ns=hwlab-ci
pr=<pipeline-run-name>
kubectl get pipelinerun -n "$ns" "$pr" \
-o jsonpath="status={.status.conditions[0].status}{\"\\n\"}reason={.status.conditions[0].reason}{\"\\n\"}message={.status.conditions[0].message}{\"\\n\"}start={.status.startTime}{\"\\n\"}done={.status.completionTime}{\"\\n\"}"
echo taskruns
kubectl get taskrun -n "$ns" -l tekton.dev/pipelineRun="$pr" \
-o jsonpath="{range .items[*]}{.metadata.name}{\"\\t\"}{.metadata.labels.tekton\\.dev/pipelineTask}{\"\\t\"}{.status.conditions[0].status}{\"\\t\"}{.status.conditions[0].reason}{\"\\t\"}{.status.startTime}{\"\\t\"}{.status.completionTime}{\"\\n\"}{end}" | sort -k2,2
echo skipped
kubectl get pipelinerun -n "$ns" "$pr" \
-o jsonpath="{range .status.skippedTasks[*]}{.name}{\"\\n\"}{end}" | sort
'
再抓关键日志。正常 no-op fast lane 应看到 source-clone 约 1-2s、catalog-fetch 小于 1s、所有 runtime services reuse、skipped-runtime-unchanged、gitops-commit 和 gitops-push 为 skipped，并且 runtime-ready 出现在 skipped tasks 中。输出中不应出现 build-hwlab-cli。
bun scripts/cli.ts ssh G14:k3s script -- 'set -eu
ns=hwlab-ci
pr=<pipeline-run-name>
for task in prepare-source plan-artifacts collect-artifacts gitops-promote runtime-ready; do
tr=$(kubectl get taskrun -n "$ns" \
-l tekton.dev/pipelineRun="$pr",tekton.dev/pipelineTask="$task" \
-o jsonpath="{.items[0].metadata.name}" 2>/dev/null || true)
[ -n "$tr" ] || { echo "--- $task skipped/no-taskrun ---"; continue; }
pod=$(kubectl get pod -n "$ns" -l tekton.dev/taskRun="$tr" \
-o jsonpath="{.items[0].metadata.name}")
echo "--- $task $pod selected logs ---"
kubectl logs -n "$ns" "$pod" --all-containers=true | \
grep -E "skipped-runtime-unchanged|runtime-ready-required|runtime-identity-only|g14-cicd-timing|git-operation|g14-ci-plan|artifact_reuse|buildSkippedCount|gitops-commit|gitops-push" || true
done
'
常见故障按以下顺序处理：
| 现象 | 优先检查 | 处理原则 |
|---|---|---|
prepare-source 回到 20s 以上 |
日志是否出现 npm ci、npm registry probe、GitHub URL、SSH setup 或长时间 catalog fetch |
拆掉无效依赖安装和重复探针；读路径必须回到 mirror。 |
source-clone 超过 5s |
PipelineRun 参数 git-read-url、mirror service、PVC I/O、git-mirror status |
不要改回 GitHub 直连；先修 mirror/read service。 |
| catalog 缺失导致全量 build | prepare-source 是否从 v0.2-gitops 取到 deploy/artifact-catalog.v02.json |
先 git-mirror sync --confirm；必要时查 mirror refs/object closure。 |
buildSkippedCount 不是 9 |
g14-ci-plan 的 affectedServices、buildServices、rolloutServices 和 changed path summary |
真实业务变更可以 build；CI/CD 文档或 render-only 变更不应误触发全量 build。 |
no-op 仍执行 runtime-ready |
gitops-promote 是否输出 runtime-ready-required=false 和 skipped-runtime-unchanged |
查 runtime 归一化比较；不要直接删除 runtime-ready，只修 no-op 判定。 |
mirror pendingFlush=true 长期存在 |
bun scripts/cli.ts hwlab g14 git-mirror status 和最近一次 flush 错误 |
手动 git-mirror flush --confirm；flush 不影响已 rollout 本地 revision，但不能静默积压。 |
Argo Synced/Healthy 但公网不通 |
hwlab-v02-frpc 日志、master frps allowlist、19666/19667 |
修 FRP allowlist 或 frpc；不要把 DEV/PROD 入口当作 v02 证据。 |
runtime-ready 超时 |
Argo app revision、workload Pod template source commit、Pod events、observer RBAC | 真实 rollout 必须 fail closed；先定位 Argo 或 workload，不要降低等待为 warning。 |
性能退化排障结束后，只把可复用的预算、原理和入口更新到本文；一次性 PipelineRun 名称、Pod 名称、日志全文和临时证据放到 issue 或 PR，不写入长期规格。
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 |
UniDesk trigger-current 解析到的 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/<serviceId>.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/relay 是 allowlisted、PVC-backed 或等价持久化服务，负责缓存 GitHub 对象并承接 v0.2-gitops 本地写入。只有 mirror/relay sync/flush 边界持有 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/relay 接入方式遵循“CI 写本地、GitHub 异步归档、读自动加速”。GitOps 和 deploy spec 中的 repo 字段仍记录 canonical GitHub URL 作为身份字段；launcher 或只读 runtime image 内的 resolver 负责读路径自动分流。需要 push v0.2-gitops 的 promotion task 必须 push devops-infra 本地 mirror/relay，不得在 CI 关键路径直接 push GitHub canonical remote。
registry 与 git mirror/relay 分属不同基础设施边界。registry 保持当前 G14 hwlab-ci/hwlab-registry，继续通过 repository prefix 服务 HWLAB、AgentRun 和后续 lane；新增 devops-infra git mirror/relay 不触发 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 状态；启用 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。
Kubernetes 与 Argo 边界
hwlab-v02namespace 只能由v0.2GitOps lane 管理。argocd/hwlab-v02AppProject destination 只能包含hwlab-v02。argocd/hwlab-g14-v02source 必须指向devops-infra本地 mirror/relay 中的v0.2-gitops:deploy/gitops/g14/runtime-v02，destination 必须是hwlab-v02。hwlab-v02-frpc只能暴露19666/19667，不能复用17666/17667或18666/18667。v0.2Secret、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。 v0.2不得创建或依赖 CronJob；hwlab-v02-branch-poller、hwlab-v02-control-plane-reconciler或同类调度器出现时应清理，而不是接入发布链路。- 旧 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/relay 必须来自独立
devops-infra服务；hwlab-v02runtime namespace 不部署 mirror、不持有 GitHub deploy key、不在 mirror miss 时直连 GitHub fallback。 - GitOps promotion 必须写入
devops-infra本地 mirror/relay 的v0.2-gitops；除 mirror/relay flush 外，不得在 CI 关键路径直接 push GitHub canonical remote。 - mirror/relay write 必须只允许 allowlist refs，拒绝 non-fast-forward，拒绝越界 changed paths，并在 receive 成功前完成 object closure 校验。
这些硬边界优先在自然写入点做最小内联断言：render 断言 namespace/runtime path，promotion 断言 GitOps branch/changed paths，Argo spec 断言 destination，验收断言端口和 runtime identity。不要为每条设计约定再新增独立 preflight、guard、gate 或报告生成器。
G14 DEV/PROD 不变边界
接入 v0.2 不得改变以下对象：
G14source branch 的 poller/reconciler 语义。G14-gitopsDEV/PROD catalog 与 runtime desired state。hwlab-dev与hwlab-prodnamespace。hwlab-g14-dev与hwlab-g14-prodArgo Application。- DEV
17666/17667与 PROD18666/18667FRP 入口。 - D601 legacy 回溯路径和旧运行面边界。
如果 v0.2 接入失败，回滚或暂停只能作用于 hwlab-v02 lane：停止手动触发新的 v02 PipelineRun、暂停或删除 hwlab-g14-v02、回滚 v0.2-gitops runtime path、关闭 hwlab-v02-frpc 或清理 hwlab-v02 namespace 资源；不得通过新增 CronJob 维持重试，也不得重启、删除或回滚 DEV/PROD 运行面。
验收标准
v0.2 CI/CD 通过必须同时满足：
hwlab-ci中存在hwlab-v02-ci-image-publish和hwlab-v02-tekton-runner；不存在 v02 CronJob。hwlab-v02-branch-poller与hwlab-v02-control-plane-reconciler不再作为 v02 标准对象，若历史残留应由 UniDesk control-plane apply 清理。- 最新
v0.2source commit 对应的 PipelineRun 完成，且 promotion 写入v0.2-gitops。 v0.2-gitops中存在deploy/artifact-catalog.v02.json与deploy/gitops/g14/runtime-v02/**。argocd/hwlab-g14-v02指向devops-infra本地 mirror/relay 的v0.2-gitops:deploy/gitops/g14/runtime-v02，sync revision 与目标 GitOps revision 对齐。hwlab-v02中长驻 workload ready，没有把 DEV/PROD namespace 当成v0.2通过证据。gitops-promote推送本地 mirror/relay 的v0.2-gitops后应触发argocd/hwlab-g14-v02hard refresh，减少 GitOps push 与 Argo 仓库发现之间的漂移窗口；refresh 触发失败只作为低噪声事件输出，最终通过仍由runtime-ready判定。- mirror/relay status 必须能显示本地
v0.2-gitopsrevision、GitHub 已 flush revision、pending flush revision 和最近一次 flush 错误；CI 通过不要求 GitHub flush 已完成，但运维观察必须能看到上游是否落后。 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-infragit mirror/cache miss、commit ancestry 拒绝或 boot script 校验失败必须导致本轮 rollout fail closed，不得隐式回退到 GitHub 或 env image 内旧代码。http://74.48.78.17:19666/返回v0.2Cloud Web。http://74.48.78.17:19667/health/live返回v0.2runtime health，payload 中的 namespace、revision 或 runtime identity 能与hwlab-v02/v0.2对齐。
GitOps branch 已更新、source branch render 通过、PipelineRun 名称存在或 G14 DEV/PROD health 正常，都不能单独代表 v0.2 CI/CD 通过。
测试规格
T1
阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：确认 origin/v0.2 最新 commit 对应的 PipelineRun 完成，promotion 只写入 v0.2-gitops，且 source branch 没有跟踪 deploy/artifact-catalog.v02.json 或 deploy/gitops/g14/runtime-v02/** 生成物。
T2
阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：查询 Argo hwlab-g14-v02，确认 source repo 为 devops-infra 本地 mirror/relay，branch/path 为 v0.2-gitops:deploy/gitops/g14/runtime-v02，destination namespace 为 hwlab-v02，sync revision 与目标 GitOps revision 对齐。
T3
阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：访问 http://74.48.78.17:19666/ 和 http://74.48.78.17:19667/health/live，确认公网入口、payload environment、revision 和 runtime identity 都指向 v02，不把 DEV/PROD health 当作 v02 证据。
T4
阅读 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 内旧代码。
T7
阅读 docs/reference/spec-v02-cicd.md，然后用 cli 手动测试以下内容：触发一次 v0.2 code-only promotion，确认 gitops-promote 只 push 到 devops-infra 本地 mirror/relay，Argo 从本地 mirror/relay rollout；再执行 git-mirror flush --confirm，确认 GitHub origin/v0.2-gitops 快进到同一 revision，status 中 pending 清空。
规格的实现情况
| 规格项 | 状态 | 说明 |
|---|---|---|
| v02 独立 source/GitOps/runtime lane | 已实现 | v0.2、v0.2-gitops、hwlab-v02 和 runtime-v02 已固定。 |
| 手动 CLI trigger/pipeline/promotion | 已实现 | 通过 UniDesk trigger-current 创建 commit-pinned PipelineRun；v02 不设 CronJob，由 hwlab-v02-ci-image-publish 与 GitOps promotion 管理。 |
| v02 runtime readiness fail-closed | 已实现 | gitops-promote 推送后触发 Argo hard refresh；runtime-ready 读取 workload Pod template source commit，timeout、observer RBAC 不足或未就绪会让 PipelineRun 失败。 |
| v02 裁撤服务不进入发布面 | 已实现 | v02 Tekton build service set、artifact catalog 和 runtime render 只包含保留服务；v02 Argo 开启 prune 清理旧 live 对象；裁撤服务仍可保留在 DEV legacy 源码中。 |
| Argo v02 Application | 已实现 | hwlab-g14-v02 指向 v02 GitOps path 和 namespace。 |
FRP 19666/19667 入口 |
已实现 | 由 hwlab-v02-frpc 与 master frps allowlist 共同提供。 |
| SecretRef 独立与 provider 验收 | 已实现/持续约束 | SecretRef 已独立；验收必须做真实短连接聊天。 |
| env 容器复用三变量启动 | 已实现/持续约束 | device-pod fast lane 已由 CI/CD 自动推导 HWLAB_BOOT_REPO、HWLAB_BOOT_COMMIT、HWLAB_BOOT_SH；code-only rollout 复用 env image digest，只更新代码身份。 |
devops-infra git mirror/relay 加速 |
已实现/持续约束 | source/catalog/runtime checkout 读路径和 GitOps promotion 写路径均使用独立基础设施集群 mirror/relay；Argo source 指向本地 mirror，GitHub flush 由 UniDesk CLI 手动触发，不设置 CronJob。runtime namespace 不持有 GitHub deploy key，registry 保持 G14 hwlab-ci/hwlab-registry。 |
hwlab-cli 不进 CI/CD service matrix |
已实现/持续约束 | CLI 是固定 repo 短连接 client，不发布镜像、不生成 artifact、不创建 build-hwlab-cli TaskRun；相关旧入口出现时直接删除。 |
| CI/CD fast lane 性能预算 | 已实现/持续约束 | env-reuse no-op 目标约 40s；真实 runtime rollout 目标约 50s；不得恢复 prepare-source 依赖安装、GitHub 关键路径写入或 no-op runtime 等待。 |
| 自动 registry GC | 未实现 | 初期不启用自动 GC，后续需 lane/profile 保护集。 |
平行 lane 运维边界
后续新增 v0.x 或其他平行 runtime lane 时，优先复用本节的判定顺序和排障边界，避免把一次性补丁沉淀成新的宽泛门禁。本节只保留可复用的运维边界；具体执行记录、排障流水和一次性证据应放在 issue 或 PR 中。
Secret 导入与重启边界
平行 lane 的 Secret 必须独立命名，不能在 runtime 里直接引用 DEV Secret。允许把 DEV 当前值一次性导入到目标 lane 的独立 Secret 名，但验证只能输出 Secret 对象、key、字节数和哈希指纹，不能打印 Secret value、token 片段、完整 DB URL 或 auth.json 内容。
v0.2 至少需要独立维护以下 SecretRef：
hwlab-v02-postgres/POSTGRES_PASSWORD。hwlab-cloud-api-v02-db/database-url。hwlab-v02-code-agent-provider/openai-api-key。hwlab-v02-code-agent-codex-auth/auth.json。
Code Agent 的 Secret 修复不是只改一个 Secret 对象就结束。hwlab-cloud-api 通过 env 读取 OPENAI_API_KEY，Secret 更新后必须滚动 hwlab-v02/hwlab-cloud-api。DeepSeek profile 还通过 hwlab-deepseek-proxy 的 initContainer 把 DEEPSEEK_API_KEY 渲染进 Moon Bridge 配置，Secret 更新后也必须滚动 hwlab-v02/hwlab-deepseek-proxy，否则 proxy 仍会使用旧配置并返回上游鉴权失败。
Code Agent 验收
/health/live 中 codeAgent=ready、codexStdio=ready 只能证明运行时结构、二进制、workspace、token boundary 和会话 supervisor 就绪；它不证明真实 provider 鉴权可用。涉及 Code Agent 的扩容验收必须追加一次真实短连接聊天闭环：用 Prefer: respond-async 和 X-HWLAB-Short-Connection: 1 提交 /v1/agent/chat，再轮询 /v1/agent/chat/result/<traceId>，只有 status=completed 且 assistant reply 非空才算通过。
如果 trace 里出现 Authentication Fails、upstream stream error 或 codex_stdio_provider_retry，先按 profile 分层判断：deepseek profile 走 hwlab-deepseek-proxy.<namespace>.svc.cluster.local:4000/v1/responses 和 Moon Bridge；codex-api profile 走 Pod-local loopback forwarder。不要用 codex-api readiness 掩盖 DeepSeek 专用凭证或 Moon Bridge 配置问题。
长耗时 smoke 不应通过 UniDesk SSH 长连接等待完整 Codex turn。Codex 首 token 可能超过短查询窗口，验证应使用短连接 submit/result/trace 轮询，避免把控制通道超时误判成 provider 失败。
GitOps 与 runtime 收敛
GitOps promotion 成功不等于 runtime 已经运行新版本。验收必须等待 argocd/hwlab-g14-v02 的 sync revision 对齐最新 v0.2-gitops revision，并确认 19667/health/live 的 environment、endpoint、关键 SecretRef 和 service revision 与目标 lane 对齐。
Argo Synced/Healthy 也不能单独替代公网验证。FRP server 侧 allowPorts 缺失时，hwlab-v02-frpc 会反复报告 port not allowed；这种问题应修 master 侧 frps allowlist 并只重启 hwlab-frps-dev，不要改 DEV/PROD GitOps、Service 或 v02 runtime path。修复后必须同时验证新增 19666/19667 和既有 DEV 17666/17667。
后续扩容建议
下一条平行 lane 建议先列一张最小资源映射表，再落地 CI/CD：source branch、GitOps branch、runtime namespace、runtime path、Argo Application、FRP ports、artifact catalog、Postgres Secret、Cloud API DB Secret、Code Agent provider Secret、Codex auth Secret、DeepSeek proxy restart 对象和公网验收 URL。映射表是执行清单，不是新 gate；只有 branch、namespace、runtime path、GitOps branch、Argo destination、SecretRef 名称和公网端口这些硬边界需要内联断言。
Secret、FRP 和 Argo 问题都应先在目标运行面做最小真实闭环，再进入完整 CI/CD 复跑。不要用完整 PipelineRun 反复探索 Secret 值、FRP allowlist 或 provider 鉴权；CI/CD 只负责固化已经在目标 namespace 证明可行的配置和源码。