diff --git a/.agents/skills/unidesk-ymalops/SKILL.md b/.agents/skills/unidesk-ymalops/SKILL.md index 9e13762a..a36cb1c7 100644 --- a/.agents/skills/unidesk-ymalops/SKILL.md +++ b/.agents/skills/unidesk-ymalops/SKILL.md @@ -30,6 +30,7 @@ description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/ - 避免“超级配置”。当一个能力同时涉及 target/lane、runtime、scenario、prompt、report、publicExposure、Secret、CI/CD 等不同职责时,按职责拆分到 owning YAML;root YAML 只保存归属和 `configRefs`/path 引用,不承载全部细节。 - 跨 YAML 引用应使用稳定的 `path/to/file.yaml#object.path` 或当前 domain parser 明确支持的等价语法。parser 只解析引用、校验存在性/类型/形状和冲突,不生成隐藏默认值,也不把合并后的大对象写成新的 source of truth。 - 新 VPS 或裸节点 bootstrap 的出网必须优先走 YAML-first 声明的 0 依赖 host proxy client:通过 `trans` 分发零依赖客户端,先让 host route 能出网,再安装 k3s、containerd、Docker、包管理器依赖和 Git/gitrepo 同步;不得把 provider-gateway WebSocket egress 当作大二进制或依赖下载的数据面。 +- 新节点 node-local registry 必须支持从零部署:优先由 YAML 渲染为 k3s workload/PVC;host Docker registry 只能是 legacy/迁移前状态。需要证明从零能力时先停旧 registry,不从旧 registry seed,并在状态中披露 `seededFromOldRegistry`、`zeroSeeded`、PVC、workload、endpoint 与 runtime/tools image preload 结果。 - YAML 配置必须可复用、可继承、可组合;节点/lane 只能作为变量或 YAML value 参与渲染,禁止把具体 node/lane 写入 YAML 文件名、parser/renderer/helper 函数名或长期 schema 名。发现不同节点复制大段配置时,先抽 baseline/configRef/override,再继续扩展节点。 - CLI `plan/status` 应输出 redacted 配置引用图:每个 ref 的文件、path、presence、摘要 hash、缺失字段和下一步 drill-down 命令。不要默认 dump 展开后的完整 YAML 或 Secret。 - Secret 只能通过 YAML 的 `sourceRef`/`targetKey` 声明和受控 CLI 下发;禁止从运行面 Secret、pod env、日志或数据库状态反推、解码、回填本地凭据。 diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 71958644..de2ea8e9 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -12,6 +12,7 @@ - D518 的 HWLAB v0.3 固定主 workspace 是 `D518:/home/ubuntu/workspace/hwlab-v03`,固定跟踪 `github/v0.3`。D518 上的源码修改、PR 准备、运行面修复和 rollout 前 source truth 检查必须在该固定 workspace 下创建任务级 `.worktree/`;master server 本地 `/root/HWLAB`、一次性 clone 或未由 YAML 选中的路径只能做只读对照,不能承担 D518 source truth。 - JD01 的 HWLAB v0.3 固定主 workspace 是 `JD01:/root/workspace/hwlab-v03`,固定跟踪 `github/v0.3`。JD01 上的源码修改、PR 准备、运行面修复和 rollout 前 source truth 检查必须在该固定 workspace 下创建任务级 `.worktree/`;如果固定目录尚未初始化,先建立该目录的固定 repo,再继续当前任务。 - JD01 的出网、依赖拉取、k3s/bootstrap、git-mirror 和 web-probe 浏览器依赖都以 UniDesk YAML 中的 host-route/host-proxy 声明为准:`config/hwlab-node-control-plane.yaml` 的 `nodes.JD01.egressProxy`、`config/platform-infra/host-proxy.yaml#targets.JD01`,以及 `config/hwlab-node-lanes.yaml` 的 JD01 network/download/sourceWorkspace 配置。JD01 的 MDTODO、Cloud Web、web-probe 或 rollout 任务不是 Sub2API 任务;除非 issue/CLI 明确指向 Sub2API runtime、Codex pool 或 platform-infra sub2api target,不要把这类故障默认归因到 Sub2API,也不要把 JD01 egress 临时切到 Sub2API 路径。 +- JD01 的 node-local registry 是 k3s workload/PVC,不是 host Docker registry。`hwlab nodes control-plane infra status --node JD01 --lane v03` 应显示 registry workload ready、PVC bound、endpoint ready、`zeroSeeded=true` 和 `seededFromOldRegistry=false`;旧 host Docker `registry` 容器应保持停止。零种子 registry 迁移后,必须通过受控 `runtime-image preload` 和 `infra tools-image build/status` 补齐 BuildKit、runtime/base 和 tools image,再把 HWLAB/AgentRun status 与 web-probe smoke 作为可用性证据。 - HWLAB 项目内长期规则入口仍以目标 repo 的 `AGENTS.md` 为准。进入已解析的目标 workspace 后,必须重新读取该 workspace 的规则文件;不能只凭主 server 的压缩上下文继续操作。 - 每次开始 node/lane 工作前必须通过 UniDesk SSH 桥检查目标 workspace,例如 `trans : sh -- 'git fetch origin && git pull --ff-only origin && git status --short --branch && git remote -v'`;若不满足目标 lane 预期,先修正 workspace,不能继续开发、render、polling 或部署。 - k3s 操作必须使用 YAML 解析出的 route 语法,例如 `trans D601:k3s ...` 或 `trans G14:k3s ...`。第一个 route token 必须定位分布式目标,后续 token 才是 operation。 diff --git a/docs/reference/yaml-first-ops.md b/docs/reference/yaml-first-ops.md index 48a71915..f33233d2 100644 --- a/docs/reference/yaml-first-ops.md +++ b/docs/reference/yaml-first-ops.md @@ -92,6 +92,14 @@ For fresh VPS bring-up, do not use provider-gateway WebSocket egress as the bulk Host proxy use has a privacy boundary. A plain `http_proxy=http://...` proxy can observe destination hosts, request metadata and any proxy credential embedded in the URL or process environment; TLS protects encrypted request bodies from the proxy but does not hide the destination metadata from the proxy operator. Do not place private API keys in proxy URLs, logs or CLI output. `NO_PROXY`/`no_proxy` must preserve local, cluster, metadata and explicitly declared direct domains, including `hyueapi.com` and `.hyueapi.com` for Codex direct API access. +## K3s-First Local Registry + +Fresh node bootstrap must not require an already-populated host Docker registry in order to deploy the node-local registry itself. The durable path for a new k3s node is to render the registry from YAML as a k3s workload with declared namespace, Deployment, Service, PVC, endpoint and image source. Host-Docker registry containers are legacy or migration sources only; they must not be the source of truth for a new node's ability to come up from zero. + +When migrating from a host-Docker registry to a k3s registry, the control path must make the data provenance explicit. If the goal is to prove from-zero deployment, stop the old host registry first and do not seed from it. The status output should say whether the new registry was seeded from an old registry or zero-seeded, whether the PVC is bound, whether the endpoint is ready, and which workload owns the registry. After a zero-seeded migration, required runtime images, BuildKit images and tools images must be re-created or preloaded through YAML-first control commands before claiming the lane can build or roll out. + +The registry is not a general reason to keep host Docker as a long-running dependency. Host Docker may still appear as a temporary build or image-transfer tool while a lane is being migrated, but the owning issue should classify it as a remaining Docker dependency and move durable builds toward k3s/Tekton/BuildKit or an equivalent rootless builder. Runtime status should distinguish long-running host Docker services from one-shot controlled build/preload operations. + ## Cross-Repository Operational Truth When UniDesk prepares or supervises runtime data for another repository, the owning YAML still belongs in UniDesk if the data is part of node/lane operations rather than that repository's application source. Examples include HWLAB test/admin account inventories, operator-only API key source references, runtime DB sync inputs, public exposure targets and cross-node workbench preparation. The service repository may contain application code and app-native migrations, but it must not become a second desired-state truth for UniDesk-operated accounts, credentials, nodes, lanes, namespaces or sourceRef bindings. diff --git a/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md b/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md index da4d67b5..637005ca 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md +++ b/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md @@ -101,6 +101,7 @@ YAML运维负责 HWLAB/UniDesk 自有平台配置的真相源、解析、渲染 | PJ2026-01060310 | 真实依赖基准 | [PJ2026-01060310 Real K3s Dependency Proxy Benchmark](PJ2026-01060310-real-k3s-deps-proxy-benchmark.md) | 使用真实 k3s 镜像、apk、npm、Go 和 Git mirror 依赖验证代理路径 | 跨节点代理基准、platform-infra proxy | k3s 构建、git-mirror、节点引导 | | PJ2026-01060311 | Host引导代理 | 本规格 6.9 | 0 依赖 host proxy client、`trans` 分发、host route 注入和 k3s 安装前出网控制 | 代理基准、目标解析、密钥绑定 | 新节点纯净 k3s 部署、package manager、git-mirror | | PJ2026-01060312 | 配置组合 | 本规格 6.10 | baseline、configRef、继承、覆盖、变量渲染和重复块治理 | 配置真相、目标解析、公共原语 | 多节点 YAML 复用、长期维护 | +| PJ2026-01060313 | K3s本地Registry | 本规格 6.11 | node-local registry 的 k3s workload/PVC、零种子迁移、镜像预加载和 Docker 依赖分类 | Host引导代理、目标解析、发布流水 | 纯净 k3s bring-up、HWLAB/AgentRun 构建 | ## 6. 原子需求 @@ -225,3 +226,15 @@ YAML运维应支持可复用、可继承、可组合的配置结构,使多个 变量渲染只能把 node、lane、service 等作为数据变量传入模板。YAML 文件名、解析函数名、渲染函数名、helper 名和 schema 名不得带具体 node/lane 名;具体 node/lane 只能出现在 YAML value、CLI 参数、外部系统要求的运行对象名或已分类 legacy adapter 中。 当配置文件因重复 node/lane 块持续膨胀时,YAML运维应先拆出职责和公共 baseline,再继续新增目标。拆分边界包括 host bootstrap、proxy、k3s install、platform-infra、HWLAB lane、AgentRun lane、Secret sourceRefs、publicExposure、probes 和 sentinel schedules。超过 3000 行的代码、运维脚本或配置文件应先按职责拆分,再继续承载新能力。 + +### 6.11 OPS-YAML-REQ-011 K3s 本地 Registry + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-YAML-REQ-011 | K3s本地Registry | PJ2026-01060313 K3s本地Registry | [发布流水](PJ2026-010601-controlled-release.md)、[YAML目标治理](PJ2026-01060308-cicd-yaml-first-target-governance.md) | + +YAML运维应允许新节点在没有旧 registry 数据和没有长期 host Docker registry 容器的前提下建立 node-local registry。registry 的 namespace、Deployment、Service、PVC、endpoint、image source、hostNetwork/bind 策略和 readiness probe 必须来自 owning YAML 或显式参数;host Docker registry 只能作为 legacy 或迁移前状态,不能作为新平台从零部署 registry 的依赖。 + +当迁移目标是证明从零部署能力时,受控 CLI 应先停止旧 host Docker registry,并在状态中明确 `seededFromOldRegistry=false`、`zeroSeeded=true`、PVC bound、workload ready 和 endpoint ready。迁移后所需的 BuildKit、runtime/base、tools image 和 service build artifact 必须通过 YAML-first `runtime-image preload`、tools image build/status 或等价 k3s 构建入口补齐,不能通过旧 registry 拷贝伪装成从零成功。 + +YAML运维状态输出应区分三类依赖:必须保留的 host bootstrap 面(provider-gateway/trans、0 依赖 host proxy、k3s installer/systemd)、待迁移的 host Docker/one-shot build 面,以及已经进入 k3s 的长期服务。后续减少 Docker 依赖时,应优先把长期服务、registry、git-mirror cache、web-probe/哨兵和构建执行迁入 k3s;host proxy client 不属于迁移目标。