feat: support named runtime lanes

2026-07-15 16:47:05 +02:00
parent 0d9747fd5b
commit 6ee345168b
8 changed files with 458 additions and 94 deletions
@@ -0,0 +1,61 @@
+# R9.8.2 命名 runtime lane renderer 任务报告
+
+## 任务定位
+
+- MDTODO：`R9.8.2`
+- Issue：`pikasTech/HWLAB#2548`
+- Target：`NC01`
+- targetWorkspace：`/root/hwlab-v03/.worktree/2548-production-runtime-lane`
+- repository：`pikasTech/HWLAB`
+- ref：`fix/2548-production-runtime-lane`
+- base：`release`
+- verifiedCommit：`0d9747fd5b458459349d4efa9735d3f4e459f0f8`
+
+## Primary workspace 轻量准备
+
+- 只读取 AgentRun resource bundle 与以下 skill：
+  - `dad-dev`、`unidesk-daddev`、`unidesk-trans`。
+  - `git-spec`、`docs-spec`、`cli-spec`。
+  - `unidesk-gh`、`unidesk-cicd`。
+- GitHub Issue 读取和进展写入使用 UniDesk `gh` 受控 CLI。
+- 未把 runner primary workspace 当作 HWLAB 源码或 Target 验证面。
+
+## Target 源码修改
+
+- 将稳定 runtime lane id 识别与 `vNN` 版本默认推导拆分。
+- `vNN` 继续沿用已有 branch、catalog、namespace、runtime path、endpoint 与端口默认。
+- 命名 lane 从 `deploy/deploy.yaml` 读取：
+  - node、source/GitOps branch 与 Git read/write URL。
+  - artifact catalog、runtime path、namespace 与 image tag mode。
+  - public endpoints、service/NodePort 与 FRP 端点。
+- 命名 lane 缺少必填 YAML 字段时 fail-closed，不从 lane id 推导 branch、namespace、路径、端口或 endpoint。
+- 保持 `scripts/gitops-render.mjs` 单 renderer，未增加数据库 projector、migration、HTTP/SSE fallback、锁、租约或第二状态库。
+- 未生成或提交 `.tekton/hwlab-nc01-production-pac.yaml`。
+
+## Target 原入口证据
+
+- `node scripts/run-bun.mjs scripts/src/runtime-lane.test.mjs`
+  - 结果：通过。
+  - 覆盖：命名 lane 参数解析、YAML 覆盖、namespace/runtime path、public NodePort、FRP 本地与远端端点、缺字段失败、`v03` 默认。
+- 使用 Target 临时目录分别运行 `release@0d9747fd5b458459349d4efa9735d3f4e459f0f8` 原 renderer 与当前 renderer。
+  - `v02`：生成目录逐文件一致。
+  - `v03`：生成目录逐文件一致。
+- `git diff --check`
+  - 结果：通过。
+- 模块导入 smoke
+  - 结果：`runtime-lane.ts`、gitops-render core、runtime manifests 与 Tekton manifests 全部导入成功。
+
+## 执行边界
+
+- 未合并 PR。
+- 未触发 PipelineRun、git mirror、Argo、runtime patch 或 rollout。
+- 未操作 PK01。
+- 未修改 `/root/hwlab-v03/.worktree/2548-production-pac-source`。
+
+## 结论
+
+`R9.8.2` 已完成以下收口：
+
+- runtime lane renderer 支持 YAML 显式声明的稳定 lane id。
+- `v02`、`v03` 既有生成结果保持不变。
+- 命名 lane 只有在 owning YAML 完整声明时才能进入现有 GitOps renderer。
@@ -11,14 +11,54 @@
 - [PJ2026-010604 公开入口](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-010604-public-entry.md)
 - [PJ2026-010605 运维监控](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md)

-目标 node/lane 的具体实现、PipelineRun 观察和运行命令仍按本仓 `AGENTS.md` 与受控 CLI 执行；需求边界、node/lane 规则和运维职责只更新 UniDesk OA。
+职责边界：
+
+- 目标 node/lane 的具体实现、PipelineRun 观察和运行命令按本仓 `AGENTS.md` 与受控 CLI 执行。
+- 需求边界、node/lane 规则和运维职责只更新 UniDesk OA。

 ## 运行参考

-node/lane rollout 的 120 秒阈值是性能告警和诊断分界，不是继续盲等的理由。`trigger-current --wait` 超过阈值或返回 pending 时，先用定点 `hwlab nodes control-plane status --node <node> --lane <lane> --pipeline-run <name>`、`git-mirror status` 和 runtime workload 摘要确认卡在哪一层：PipelineRun task、Argo sync、runtime-ready、public probe 或 git mirror flush。
+`scripts/gitops-render.mjs` 只保留一条 runtime lane 渲染链：

-只需要给 branch-follower 或 control-plane closeout 提供一轮新的真实验证源时，优先使用文档、注释或等价的非运行面小 PR，避免把 timeout、runtime 策略或 CI/CD 逻辑改动混入验证样本。
+- `vNN` lane：
+  - 继续使用既有版本号默认，包括 branch、catalog、namespace、runtime path、端口与 endpoint 推导。
+  - 修改 renderer 时必须用同一 source commit 对比生成目录，确认既有 lane 不漂移。
+- 命名 runtime lane：
+  - 必须先在 `deploy/deploy.yaml` 的 `lanes.<lane>` 中声明稳定小写 id 与 node。
+  - 必须显式声明 source/GitOps branch、Git read/write URL、artifact catalog、runtime path、namespace 与 image tag mode。
+  - 必须显式声明 public endpoints、服务声明与 FRP 端点。
+- 命名 lane 的 node：
+  - 必须在 `deploy.nodes` 中声明 `gitopsRoot` 和 `sourceRepo`。
+  - renderer 不从 lane 名称猜 branch、namespace、路径、端口或公开入口。
+- 命名 lane 缺失 owning YAML 字段时立即失败；不得增加按具体 lane 字符串、branch 名称或端口号分支的 fallback。
+- NodePort 服务只从 `lanes.<lane>.publicServices.nodes.<node>` 生成；名称、selector、service port、target port 与 node port 都由 YAML 声明。

-PR 合并后如果目标分支被并行 PR 推进，closeout 要同时记录本 PR merge commit、当前 source head 和 ancestry 证据；只要当前 head 包含本 PR merge commit，后续 rollout 应按当前 head 收敛，避免回滚到旧 source。定点 status 可证明某个旧 PipelineRun 是否 succeeded，但最终用户入口验收必须以当前 node/lane source、GitOps revision、Argo 和 runtime 状态为准。
+node/lane rollout 的 120 秒阈值是性能告警和诊断分界，不是继续盲等的理由：

-runtime-ready 卡住时先看 `STATUS` 输出里的 notReady workload，再按 workload 日志和事件定位；修复应回到 source truth、PR、GitOps 和受控 sync/refresh，不把手工 patch Deployment、裸删 Pod 或临时容器改动作为交付路径。若 runtime 已 ready 但 Argo 仍 OutOfSync/Progressing，先走受控 `hwlab nodes control-plane sync|refresh --node <node> --lane <lane> --confirm` 收敛控制面，再复查 bounded status。
+- `trigger-current --wait` 超过阈值或返回 pending 时，先执行定点 status。
+- 使用 `hwlab nodes control-plane status --node <node> --lane <lane> --pipeline-run <name>` 查看 PipelineRun。
+- 配合 `git-mirror status` 和 runtime workload 摘要判断卡点。
+- 卡点范围包括 PipelineRun task、Argo sync、runtime-ready、public probe 或 git mirror flush。
+
+只需要给 branch-follower 或 control-plane closeout 提供一轮新的真实验证源时：
+
+- 优先使用文档、注释或等价的非运行面小 PR。
+- 不把 timeout、runtime 策略或 CI/CD 逻辑改动混入验证样本。
+
+PR 合并后如果目标分支被并行 PR 推进：
+
+- closeout 同时记录本 PR merge commit、当前 source head 和 ancestry 证据。
+- 当前 head 包含本 PR merge commit 时，后续 rollout 按当前 head 收敛，避免回滚到旧 source。
+- 定点 status 只证明指定旧 PipelineRun 是否 succeeded。
+- 最终用户入口验收以当前 node/lane source、GitOps revision、Argo 和 runtime 状态为准。
+
+runtime-ready 卡住时：
+
+- 先查看 `STATUS` 输出里的 notReady workload，再按 workload 日志和事件定位。
+- 修复回到 source truth、PR、GitOps 和受控 sync/refresh。
+- 不把手工 patch Deployment、裸删 Pod 或临时容器改动作为交付路径。
+
+runtime 已 ready 但 Argo 仍 OutOfSync/Progressing 时：
+
+- 走受控 `hwlab nodes control-plane sync|refresh --node <node> --lane <lane> --confirm` 收敛控制面。
+- 再复查 bounded status。