diff --git a/AGENTS.md b/AGENTS.md index 0785f423..bdfdbb52 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 ## P0 G14 原生 k8s/GitOps 运行面归一 - G14 是当前 HWLAB DEV/PROD 原生 k8s 与 GitOps 运行面真相；`hwlab-dev` 与 `hwlab-prod` 均由 G14 k3s、Tekton、`G14-gitops` 和 Argo CD 管理，详见 [docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)。 +- `v0.2` 是 G14 上的加法扩容线：固定分支 `v0.2`、固定 workspace `G14:/root/hwlab-v02`、固定 namespace `hwlab-v02`、FRP 入口 `74.48.78.17:19666/19667`；创建和集成 `v0.2` 不得删除、重命名、复用或改义现有 `G14`/`G14-gitops` 分支、`hwlab-dev`/`hwlab-prod` namespace 或 17666/17667、18666/18667 入口。 - G14 GitOps render 若改变 Argo Application、AppProject、runtime path 或 DEV/PROD 拆分目录，必须同步应用 `deploy/gitops/g14/argocd/project.yaml`、`application-dev.yaml` 和 `application-prod.yaml`；只推 `G14-gitops` 分支不等于 Argo 已切到新 path。 - D601 HWLAB DEV、D601 `dev-cd-apply`、`ci-publish` 和旧 `main` JS 脚本式 CI/CD 已退出 G14 发布入口；G14 Tekton 只能通过 `scripts/g14-artifact-publish.mjs` 作为集群内 build/push helper，再由 GitOps/Argo CD rollout，新开发、发布、验收、文档和运行面实验不得把 D601 或 legacy 脚本 CD 当作当前 HWLAB runtime source-of-truth。 - G14 k3s 操作必须通过 UniDesk route `G14:k3s` 执行；不得用 D601 kubeconfig、Docker Desktop Kubernetes、master server 本地 check/build 或旧 JS CD 结果作为 G14 DEV/PROD 通过证据。 @@ -32,6 +33,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 ## 工作区 - G14 分支固定 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。在 G14 上进行代码、文档、GitOps render、Tekton/poller/Argo CD 修复或 CI/CD 验证前，必须先确认 `pwd` 为 `/root/hwlab` 且 `git status --short --branch` 为 `G14...origin/G14`；不满足时先停止并修正 workspace。 +- `v0.2` 固定 source workspace 是 G14 节点上的 `/root/hwlab-v02`，固定使用 `v0.2` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。`/root/hwlab-v02` 只能作为 `v0.2` 长期工作区，不得作为 `G14` scratch 区或 DEV/PROD 热修目录。 - G14 开发默认先以 `/root/hwlab` 做固定 repo 预检，再在 `/root/hwlab/.worktree/` 从最新 `origin/G14` 创建独立 worktree 修改和提交；固定 repo 不作为并行任务 scratch 区，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。 - G14 k3s 操作必须通过 UniDesk SSH route `G14:k3s` 执行，例如 `bun scripts/cli.ts ssh G14:k3s kubectl get pods -n hwlab-ci`；禁止使用 `ssh G14 k3s ...`。不要把 `/workspace/hwlab`、`/root/HWLAB`、D601 workspace、master-server checkout 或临时 clone 当作 G14 分支 source truth。 - Runner 和指挥常用工作区是 `/workspace/hwlab`；进入仓库先检查分支与工作树状态，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。 @@ -46,6 +48,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 - G14 DEV Cloud Web：`http://74.48.78.17:17666/`，规则见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。 - G14 DEV API/edge/live：`http://74.48.78.17:17667/health/live`，规则见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。 - G14 PROD 预留入口：`http://74.48.78.17:18666/` 与 `http://74.48.78.17:18667/health/live`，规则见 [docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)。 +- G14 `v0.2` 规划入口：`http://74.48.78.17:19666/` 与 `http://74.48.78.17:19667/health/live`，只能指向 `hwlab-v02` namespace，规则见 [docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)。 - Cloud Workbench 默认首页与 UX 约束见 [docs/reference/cloud-workbench.md](docs/reference/cloud-workbench.md)。 ## 长期参考 diff --git a/docs/reference/commander-collaboration.md b/docs/reference/commander-collaboration.md index f853e9ab..fe044c66 100644 --- a/docs/reference/commander-collaboration.md +++ b/docs/reference/commander-collaboration.md @@ -17,6 +17,7 @@ - 常规 runner 和指挥官工作区是 `/workspace/hwlab`。 - 进入仓库先检查分支和工作树状态。 - G14 人工/指挥官开发必须先在固定 repo `/root/hwlab` 做 `pwd`、`git status --short --branch`、`git remote -v` 和 `fetch` 预检，再在 `/root/hwlab/.worktree/` 从最新 `origin/G14` 创建任务专属 worktree；代码、文档、测试补丁、提交和 PR 准备都在该独立 worktree 中完成。 +- G14 `v0.2` 固定 workspace 是 `/root/hwlab-v02`，固定跟踪 `origin/v0.2`。所有 `v0.2` 文档、计划、CI/CD lane 和 namespace 设计必须在该 workspace 或其明确创建的 `v0.2` worktree 中完成；不得使用 `/root/hwlab` 根目录或现有 `hwlab-dev`/`hwlab-prod` 运行面作为 `v0.2` scratch 区。 - 固定 repo `/root/hwlab` 是 source truth 和 worktree 管理入口，不是并行任务 scratch 区；不要在固定 repo 根目录堆叠未提交改动，也不要复用其他任务遗留 `.worktree/`。 - D601 发布和 rollout 工作区是 `/home/ubuntu/workspace/hwlab`。 - 不要清理、reset 或复用无关 runner worktree 作为发布真相。 @@ -24,6 +25,7 @@ ## 分支和交付工作流 - 单纯文档、CLI/helper 轻量变更默认直接提交并 push 到 `origin/G14`，不开 PR；这类变更仍要先从最新 `origin/G14` 创建独立 worktree，提交前审查 diff，只提交当前任务相关文件。 +- `v0.2` 线的单纯文档和计划可以直接提交并 push 到 `origin/v0.2`，不开 PR；涉及 namespace 创建、Argo CD Application、Tekton poller/reconciler、FRP、Secret、DB、权限或 runtime rollout 的变更必须先有 `docs/plan/` 计划和 GitHub issue，再按计划分步执行。 - 业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD、重启服务、CI/CD 控制面高风险变更或其他影响 runtime truth 的变更默认走 PR 工作流。 - 用户或指挥官给出最新交付纠偏时，以最新要求为准，删除旧断言或旧门禁，不用 feature flag、legacy mode 或双路径长期并存绕开最新要求。 diff --git a/docs/reference/dev-runtime-boundary.md b/docs/reference/dev-runtime-boundary.md index 1385200d..4a50e0c9 100644 --- a/docs/reference/dev-runtime-boundary.md +++ b/docs/reference/dev-runtime-boundary.md @@ -5,11 +5,11 @@ substitution rules. ## Public G14 Runtime Ports -| Surface | DEV URL | PROD URL | -| --- | --- | --- | -| Cloud Web browser entry | `http://74.48.78.17:17666/` | `http://74.48.78.17:18666/` | -| API/edge entry | `http://74.48.78.17:17667/` | `http://74.48.78.17:18667/` | -| API/live health | `http://74.48.78.17:17667/health/live` | `http://74.48.78.17:18667/health/live` | +| Surface | DEV URL | PROD URL | v0.2 URL | +| --- | --- | --- | --- | +| Cloud Web browser entry | `http://74.48.78.17:17666/` | `http://74.48.78.17:18666/` | `http://74.48.78.17:19666/` | +| API/edge entry | `http://74.48.78.17:17667/` | `http://74.48.78.17:18667/` | `http://74.48.78.17:19667/` | +| API/live health | `http://74.48.78.17:17667/health/live` | `http://74.48.78.17:18667/health/live` | `http://74.48.78.17:19667/health/live` | Public `:16666` and `:16667` are D601 legacy DEV endpoints. They can be used only for migration comparison or incident replay, not as the current HWLAB runtime acceptance target. Internal k3s services may still listen on `6667`; do not rewrite that as a public endpoint. @@ -27,10 +27,17 @@ master hwlab-frps-dev :18666/:18667 -> G14 hwlab-g14-prod-frpc in namespace hwlab-prod -> hwlab-cloud-web on internal :8080 for browser traffic -> hwlab-edge-proxy / hwlab-cloud-api on internal :6667 for API and health + +master hwlab-frps-dev :19666/:19667 +-> G14 v0.2 frpc in namespace hwlab-v02 +-> hwlab-cloud-web on internal :8080 for browser traffic +-> hwlab-edge-proxy / hwlab-cloud-api on internal :6667 for API and health ``` G14 PROD is rendered by GitOps as namespace `hwlab-prod` and Argo CD application `hwlab-g14-prod`; it uses the `:18666/:18667` public endpoints when enabled. G14 desired state is generated into `deploy/gitops/g14/runtime-dev` and `deploy/gitops/g14/runtime-prod` and promoted through the `G14-gitops` branch. +G14 `v0.2` is an additive lane, not a replacement for DEV or PROD. It uses source branch `v0.2`, fixed workspace `G14:/root/hwlab-v02`, namespace `hwlab-v02`, and public ports `19666/19667`. The `v0.2` GitOps branch, runtime path and Argo Application must be distinct from DEV/PROD before any automated rollout is enabled. + ## G14 k3s Source Of Truth G14 native k3s is the HWLAB DEV/PROD runtime source of truth. Commands that observe or mutate current HWLAB runtime must go through UniDesk route `G14:k3s`, for example: @@ -38,13 +45,14 @@ G14 native k3s is the HWLAB DEV/PROD runtime source of truth. Commands that obse ```sh tran G14:k3s kubectl -n hwlab-dev get deploy,svc,pod -o wide tran G14:k3s kubectl -n argocd get application hwlab-g14-dev hwlab-g14-prod +tran G14:k3s kubectl -n hwlab-v02 get deploy,svc,pod -o wide ``` Do not use D601 kubeconfig, D601 `dev-cd-apply`, old JS `ci-publish`, Docker Desktop Kubernetes, or master-server local checks as G14 runtime acceptance evidence. D601 remains a legacy migration/reference surface until the branch-role migration is complete. ## Branch Role Migration -The target branch model is: G14 becomes the `main` runtime source branch, and the former D601-oriented `main` behavior moves to a D601 legacy/maintenance line. Until that branch governance operation is explicitly completed and verified, `/root/hwlab` on G14 continues to use the `G14` branch and must merge the latest `origin/main` business updates before G14-specific runtime work. +The target branch model is: G14 becomes the `main` runtime source branch, and the former D601-oriented `main` behavior moves to a D601 legacy/maintenance line. Until that branch governance operation is explicitly completed and verified, `/root/hwlab` on G14 continues to use the `G14` branch and must merge the latest `origin/main` business updates before G14-specific runtime work. The `v0.2` expansion does not complete or replace that governance operation; it adds a separate `v0.2` branch and `hwlab-v02` runtime lane beside the existing G14 DEV/PROD lanes. ## Distributed Passthrough Hygiene diff --git a/docs/reference/g14-gitops-cicd.md b/docs/reference/g14-gitops-cicd.md index 93723c43..205bfc6c 100644 --- a/docs/reference/g14-gitops-cicd.md +++ b/docs/reference/g14-gitops-cicd.md @@ -8,8 +8,9 @@ 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`。 - 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`；master frps 的 `deploy/frp/frps.dev.toml` 与实际 `/etc/frp/frps.toml` 必须同时放行这四个 G14 端口。 +- 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 决定。 ## 生成入口 @@ -26,6 +27,7 @@ G14 是 HWLAB 当前 DEV/PROD 原生 k8s 与 GitOps 运行面目标。G14 CI/CD - 生成 `hwlab-g14-control-plane-reconciler` CronJob：它使用同一个 Git SSH Secret 轮询 `G14`，运行 repo 内 `scripts/g14-gitops-render.mjs`，并 server-side apply 生成的 Tekton RBAC、Pipeline、Poller 和 Reconciler manifests；因此 CI 控制面变化应自动进入 G14 k3s，不需要人工长期执行 render/apply。 - 默认输出到 `deploy/gitops/g14/`。 - 默认 GitOps 生成分支是 `G14-gitops`；Pipeline 成功后把本次 source commit 对应的 `deploy/artifact-catalog.dev.json` 与 `deploy/gitops/g14/**` 推送到该分支，避免把生成提交继续写回 `G14`。 +- `v0.2` GitOps lane 必须使用独立生成身份，例如 `v0.2-gitops`、`deploy/artifact-catalog.v02.json` 和 `deploy/gitops/g14/runtime-v02`，并由独立 Argo CD Application 指向 `hwlab-v02`。若后续实现选择复用某个脚本入口，也必须通过显式参数区分 source branch、catalog、runtime path、Application 和 namespace，不能靠修改默认值让 `G14` DEV/PROD 行为漂移。 - 默认 registry prefix 是 `127.0.0.1:5000/hwlab`，用于 G14 单节点 k3s 的 node-local registry。 - 默认 CI/CD proxy 是 G14 本机 `http://127.0.0.1:10808` / `socks5h://127.0.0.1:10808`。Tekton CI step、BuildKit sidecar 和 publish step 都注入 proxy/no_proxy；服务镜像构建只允许通过 Pod 内 BuildKit Unix socket 直接 push 到 G14 本地 registry，不能回退到 Docker daemon、DIND 或 host Docker。 - `prepare-source` 和最小原语校验 task 不允许每次运行时重新 `apk add`、`apt-get install` 或临时下载 browser/runtime 依赖。当前固定工具镜像是 `127.0.0.1:5000/hwlab/hwlab-ci-node-tools:node22-alpine-v1`，包含 Node 22、npm、Git、OpenSSH、curl 和 Python3。脚本启动时必须输出工具与 proxy preflight 结构化日志；缺少工具时应先重建并推送工具镜像，再修改 `HWLAB_G14_CI_TOOLS_IMAGE`/render 默认值，不能回退到 runtime 安装。 @@ -120,6 +122,8 @@ DeepSeek proxy manifest 是 GitOps desired state 的一部分，DEV/PROD 分别 G14 不要求 GitHub webhook 或 GitHub Actions 配置。`hwlab-ci/hwlab-g14-branch-poller` CronJob 每 1 分钟通过 Git SSH 拉取 `G14` HEAD，并用 source commit 的前 12 位生成 PipelineRun 名称 `hwlab-g14-ci-poll-`。 +`v0.2` 接入时应新增独立 poller/reconciler 或显式参数化同一控制面，监控 `v0.2` HEAD，并使用可区分的 PipelineRun 名称前缀，例如 `hwlab-v02-ci-poll-`。该 lane 的 GitOps promotion 只允许写入 `v0.2` 专属 catalog、runtime path 和 GitOps branch；不得向 `G14` 或现有 DEV/PROD runtime path 写入生成物。 + 如果同名 PipelineRun 已存在，poller 直接跳过；如果不存在，则创建新的 PipelineRun。这样可以用 Kubernetes 原生 CronJob、ServiceAccount、RBAC 和 Tekton API 实现无 GitHub webhook 的分支监控，同时避免同一个 commit 被反复派单。历史上的 `chore: promote G14 GitOps source ...` source 分支生成提交已经废弃；poller 只应该看到人写 source commit。 Pipeline 的标准路径是：`G14` source commit -> Tekton 原语校验 task -> commit-tagged image push 到 G14 registry -> refresh artifact catalog -> render `deploy/gitops/g14/**` -> push catalog 与 GitOps desired state 到 `G14-gitops` -> Argo CD 同步 runtime。CD 只消费已经构建好的镜像和 Git desired state，不在 Argo CD 内构建镜像。 @@ -148,6 +152,7 @@ KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-ci logs pod/