From 0bbec628fcc855450c9237da36d4b56742b31131 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 28 May 2026 14:25:14 +0800 Subject: [PATCH] docs: plan hwlab v0.2 namespace lane --- docs/plan/hwlab-v02-namespace-cicd.md | 63 +++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/plan/hwlab-v02-namespace-cicd.md diff --git a/docs/plan/hwlab-v02-namespace-cicd.md b/docs/plan/hwlab-v02-namespace-cicd.md new file mode 100644 index 00000000..6e030806 --- /dev/null +++ b/docs/plan/hwlab-v02-namespace-cicd.md @@ -0,0 +1,63 @@ +# HWLAB v0.2 namespace 与 CI/CD 扩容计划 + +本文是 `v0.2` 分支上的执行计划，用于把 `hwlab-v02` 作为 G14 上的独立运行面接入当前 Tekton + GitOps + Argo CD 体系。目标是只做加法扩容，保持现有 G14 DEV/PROD 100% 稳定。 + +## 固定命名 + +- Source branch：`v0.2`，从当前 `G14` 分支 fork。 +- Source workspace：`G14:/root/hwlab-v02`，固定跟踪 `origin/v0.2`。 +- Runtime namespace：`hwlab-v02`。 +- GitOps branch：规划使用 `v0.2-gitops`，避免写入 `G14-gitops` 的 DEV/PROD desired state。 +- Artifact catalog：规划使用 `deploy/artifact-catalog.v02.json`。 +- Runtime path：规划使用 `deploy/gitops/g14/runtime-v02`。 +- Argo CD Application：规划使用 `hwlab-g14-v02`。 +- Public FRP entry：Cloud Web `http://74.48.78.17:19666/`，API/live `http://74.48.78.17:19667/health/live`。 + +## 不变边界 + +- 不删除、不重命名、不复用 `hwlab-dev` 或 `hwlab-prod` namespace。 +- 不改写现有 `G14` branch poller、`G14-gitops` DEV/PROD runtime path 或 `hwlab-g14-dev` / `hwlab-g14-prod` Argo Application。 +- 不复用 DEV/PROD 的 FRP 端口、Secret、DB 凭据、PVC 或运行态热修资源。 +- 不在 master server 上运行仓库级 check、browser smoke、镜像构建或集群写操作。 +- 在计划被 issue 追踪并人工确认前，不执行 namespace 创建、Argo sync、FRP 切流或 Tekton 控制面 apply。 + +## 实施阶段 + +1. 文档与 issue 基线 + - 确认 `origin/G14` 和 `origin/v0.2` 都包含 `v0.2` 加法扩容长期参考。 + - 创建 GitHub issue 引用本文，作为 `hwlab-v02` namespace 与 CI/CD 接入的跟踪入口。 + +2. Namespace 与基础 Secret 规划 + - 在 G14 k3s 中新增 `hwlab-v02` namespace。 + - 为 `hwlab-v02` 准备独立 SecretRef：数据库、Code Agent provider、FRP token 和必要 GitOps runtime Secret。 + - Secret 计划只记录对象名和 key，不在文档、issue、日志或 trace 中写入值。 + +3. GitOps desired state 扩容 + - 扩展 render 支持显式 lane 参数：source branch `v0.2`、catalog `deploy/artifact-catalog.v02.json`、runtime path `deploy/gitops/g14/runtime-v02`、namespace `hwlab-v02`。 + - 新增 `v0.2-gitops` 生成分支或等价隔离 GitOps 目标；不得把 v02 生成物写入 DEV/PROD runtime path。 + - 新增 frpc runtime manifest，只暴露 `19666/19667`，内部服务端口继续按现有 Cloud Web `8080`、edge/API `6667` 约定。 + +4. Tekton lane 扩容 + - 在 `hwlab-ci` 中新增 `v0.2` poller/reconciler，或把现有控制面改为显式多 lane 配置。 + - `v0.2` PipelineRun 前缀使用 `hwlab-v02-ci-poll-`，方便和 `hwlab-g14-ci-poll-` 区分。 + - build/publish helper 可复用现有工具镜像、registry 和 BuildKit 机制，但产物 catalog、GitOps branch、runtime path 必须隔离。 + +5. Argo CD 扩容 + - 新增 `hwlab-g14-v02` Application，source 指向 `v0.2` 专属 GitOps lane，destination 指向 `hwlab-v02`。 + - 不修改 `hwlab-g14-dev` 与 `hwlab-g14-prod` 的 source path、revision、namespace 或 sync policy。 + - 首次同步先 dry-run / diff / health 观察，再进入真实 sync。 + +6. `deploy.json` 扩容 + - 在 `v0.2` 分支上新增显式 v02 environment 或 lane 配置，服务清单以 `hwlab-v02` 为目标 namespace。 + - 不把现有 `dev` 或 `prod` 环境静默改义为 v02。 + - 如果 render 需要新增 schema 字段，字段必须向后兼容现有 DEV/PROD 配置，并在 v02 lane 中显式启用。 + +7. 验收 + - `tran G14:k3s kubectl -n hwlab-v02 get deploy,sts,svc,pod -o wide` 显示长驻 workload ready。 + - `tran G14:k3s kubectl -n argocd get application hwlab-g14-v02` 显示目标 revision、sync 和 health 与 v02 GitOps lane 对齐。 + - `http://74.48.78.17:19666/` 返回 v02 Cloud Web。 + - `http://74.48.78.17:19667/health/live` 返回 v02 runtime health，payload 的 namespace、revision 或 runtime identity 能和 `v0.2` lane 对齐。 + +## 回滚边界 + +`v0.2` 是新增运行面。若接入失败，回滚应只删除或暂停 `hwlab-v02` lane 的新增 Application、poller、reconciler、runtime path、FRP 入口或 namespace 资源；不得回滚、删除或重启现有 `hwlab-dev` / `hwlab-prod` 运行面。