Codex
24 KiB
PJ2026-010603 YAML运维
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010603 YAML运维需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010603 |
| 短名 | YAML运维 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0106 平台运维 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 YAML运维的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
YAML运维负责 HWLAB/UniDesk 自有平台配置的真相源、解析、渲染和受控下发，使 target、lane、node、service、Secret 绑定、公开入口和执行策略从 YAML 进入运行面，而不是散落在代码常量、运行面手补或一次性脚本中。
当前实现已经将 Sub2API Codex pool 的 target、publicExposure、sentinelImageBuild 和 manualAccounts.bindingSources，以及 AgentRun controlPlane default、client.sessionPolicy、lane secret providerCredential profile 和部分 fingerprint/helper 收敛到 YAML 与公共 ops helper。后续能力应在该基线上扩展，保持 YAML 为可审查、可版本化、可解释的配置真相。
2.2 范围内
- UniDesk 自有平台配置的 YAML 真相源、字段读取、必填项校验和类型校验。
- target、lane、node、service、namespace、endpoint、publicExposure 和运行目标解析。
- Secret sourceRef、targetKey、providerCredential、manual binding source 和敏感输出约束。
- Sub2API、Codex pool、AgentRun control-plane、session policy 和平台基础设施配置的受控 CLI 读取、解释、计划和下发。
- AgentRun lane 的 runner retention、idle timeout、egress proxy 和 cancel lifecycle policy 等运行策略配置读取、解释和下发。
- FRP、Caddy、public URL、public health、Kubernetes Secret 和平台资源渲染所需的配置投递边界。
- 可复用 ops primitive，包括 YAML path 捕获、字段解析、fingerprint、摘要输出、Secret 引用、有界默认输出和命令输出约束。
- 新节点 host bootstrap 的 0 依赖出网代理、
trans分发、host route 注入和 k3s 安装前置控制。 - YAML 配置的基线继承、configRef 组合、变量渲染和节点覆盖治理，避免为不同 node/lane 重复复制大段配置。
2.3 范围外
- Code Agent、AgentRun run、command、workspace 和 session 的业务生命周期语义归 Agent编排。
- 用户身份、API key、额度、账本和租户策略归 用户管理。
- Web、CLI 和 HTTP API 的用户入口体验归 客户端。
- 具体容量、冷却时间、退避窗口、账号优先级、provider 选择和公开入口数值不写成代码常量或规格硬编码；这些数值由对应 YAML 配置承载。
- 从运行面 Secret、pod env、日志或数据库反推、解码、回填本地配置真相不属于本课题允许能力。
3. 术语表
| 术语 | 定义 |
|---|---|
| YAML 真相源 | UniDesk 自有平台配置的版本化 YAML 文件，代码只负责读取、校验结构、解释和下发。 |
| 受控 CLI | 通过 UniDesk CLI 暴露的配置读取、计划、同步、解释和状态入口，避免手写脚本直接操作运行面。 |
| target | YAML 中描述服务部署目标、运行节点、namespace、公开入口和相关渲染参数的对象。 |
| lane | YAML 中描述某条运行线的目标节点、namespace、source truth、Secret 和执行策略的对象。 |
| sourceRef | YAML 中指向密钥来源的声明，输出时只能显示来源标识和摘要，不显示密钥值。 |
| targetKey | YAML 中声明运行面 Secret 或配置对象接收某项密钥的 key 名。 |
| providerCredential | AgentRun lane 中声明 provider profile 与运行面 Secret 绑定关系的配置项。 |
| cancel lifecycle policy | AgentRun lane 中声明取消投递、runner abort、kill escalation、stale fencing 和事件阶段输出的配置块；具体数值以 YAML 为准。 |
| publicExposure | YAML 中描述 FRP、Caddy、domain、TLS、public URL 和 health 目标的公开入口声明。 |
| ops primitive | 平台运维 CLI 共享的底层能力，例如字段解析、fingerprint、Secret 引用、摘要输出和 YAML path 捕获。 |
| 配置解释输出 | CLI 将 YAML 解析后的默认值、来源和目标以非敏感摘要展示给操作人员的输出。 |
| 有界默认输出 | CLI 在未显式请求机器输出或完整输出时返回的短摘要、表格和 drill-down 命令集合。 |
| host proxy client | 新节点 k3s 安装前由 trans 分发的 0 依赖出网代理客户端，用于给 Docker、k3s、containerd、包管理器、Git 和 git-mirror 提供初始出网。 |
| 配置组合 | 通过 baseline、configRef、继承、覆盖和变量渲染生成有效计划的配置方式；组合结果是执行视图，不是第二份可编辑真相源。 |
4. 系统边界和接口
本规格把 YAML运维作为平台运维内的配置真相和受控下发课题看待；本章只描述输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | 平台管理员、发布操作人员、Agent编排维护者、Sub2API/Codex pool 维护者和自动化运维任务。 |
| 外部输入 | YAML 配置文件、target/lane/node/service 声明、Secret sourceRef、providerCredential、publicExposure、host proxy 声明、baseline/configRef、运行目标选择和配置解释请求。 |
| 受控资源 | 配置解析器、公共 ops helper、Sub2API/Codex pool 配置、AgentRun lane 配置、host proxy client 分发和 systemd 渲染、Kubernetes Secret 声明、FRP/Caddy 渲染、public health 和 CLI 输出摘要。 |
| 外部输出 | 配置解释结果、计划摘要、同步摘要、Secret presence/fingerprint、host proxy health、publicExposure 渲染结果、运行目标解析结果、有界默认输出和错误诊断。 |
| 用户接口 | bun scripts/cli.ts platform-infra ...、bun scripts/cli.ts agentrun ...、受控 Secret 同步命令、配置解释命令和平台状态查询命令。 |
| 系统边界 | YAML运维负责让配置从 YAML 可解释、可校验并受控进入运行面；不定义业务策略数值、不替代 Agent/用户/客户端语义，也不把运行面观测反向变成本地配置真相。 |
5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-01060301 | 配置真相 | 本规格 6.1 | YAML 文件、字段读取、必填项和类型校验 | 平台配置需求、服务 owner 输入 | 平台 CLI、运行面渲染 |
| PJ2026-01060302 | 目标解析 | 本规格 6.2 | target、lane、node、service、namespace 和默认目标解析 | 配置真相、运行 lane 约定 | Sub2API、AgentRun、公开入口 |
| PJ2026-01060303 | 密钥绑定 | 本规格 6.3 | sourceRef、targetKey、providerCredential、manual binding 和敏感输出约束 | 凭据来源、服务 Secret 需求 | 用户管理、Agent编排、Sub2API |
| PJ2026-01060304 | 暴露渲染 | 本规格 6.4 | publicExposure、FRP、Caddy、public URL 和 health 渲染 | 目标解析、服务入口需求 | 客户端、用户管理、Agent编排 |
| PJ2026-01060305 | 执行策略 | 本规格 6.5 | AgentRun control-plane default、session policy、provider profile 和 workspace 策略配置 | Agent编排语义、lane 配置 | Agent编排、平台发布 |
| PJ2026-01060306 | 公共原语 | 本规格 6.6 | 字段解析、fingerprint、摘要输出、Secret 引用和 YAML path 捕获复用 | 各平台 CLI 实现 | 全部平台运维 CLI |
| PJ2026-01060307 | 控制面模块化 | PJ2026-01060307 控制面模块化 | CI/CD、YAML-first 和平台运维 CLI 源码入口的职责拆分、兼容入口和模块边界 | 发布流水、源码同步、公共原语 | 全部平台运维 CLI |
| PJ2026-01060308 | YAML目标治理 | PJ2026-01060308 CI/CD YAML目标治理 | CI/CD、HWLAB lane、AgentRun、platform-infra、Secret 和 public exposure 的 target/configRef/sourceRef 解析治理 | 控制面模块化、发布流水、源码同步 | CI、deploy、artifact-registry、HWLAB、AgentRun、platform-infra、secrets |
| PJ2026-01060309 | 跨节点代理基准 | PJ2026-01060309 跨节点代理CI基准 | 通过基准验证代理方案和跨节点依赖拉取能力 | public egress、proxy source | host proxy、k3s deps、CI/CD |
| PJ2026-01060310 | 真实依赖基准 | PJ2026-01060310 Real K3s Dependency Proxy Benchmark | 使用真实 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. 原子需求
6.1 OPS-YAML-REQ-001 YAML 配置真相
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-YAML-REQ-001 | 配置真相 | PJ2026-01060301 配置真相 | 平台运维 |
YAML运维应将 UniDesk 自有平台配置维持为 YAML 真相源，使平台服务的 target、lane、node、service、Secret、公开入口和策略字段都能从版本化配置读取。
代码只负责解析、类型校验、必填项校验、路径定位和错误说明，不得把容量、冷却时间、endpoint、namespace、账号候选、provider 选择或公开入口数值固化为隐藏默认值。缺少配置时应暴露明确缺口，由 YAML 或上游密钥来源修正。
6.2 OPS-YAML-REQ-002 Target 与 lane 解析
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-YAML-REQ-002 | 目标解析 | PJ2026-01060302 目标解析 | Agent编排、客户端 |
YAML运维应提供 target、lane、node、service、namespace 和默认目标解析能力，使平台 CLI 在未显式传入目标时也能从 YAML 找到当前受控目标。
目标解析必须把默认值来源解释清楚，并允许操作人员显式指定 node 或 lane 覆盖默认选择。不同服务不得各自维护一套硬编码 G14、v0.1、namespace 或 service 名称；新增服务应复用同一类解析模式。
当 issue、PR 或 CLI 已经明确 node/lane 时，YAML 解析只负责校验和解释该目标，不得用全局默认覆盖用户选择。没有明确目标时，CLI 可以读取 YAML default，但输出必须说明 default 来源、目标 node/lane、namespace、source truth 和公开入口，避免把历史 G14/v0.2、D601 legacy 或旧 dev/prod 口径误用为当前运行面。
AgentRun send session、explain session-policy、resource primitives 和 AipodSpec render 都属于 node/lane 敏感入口。命令行或请求体已明确 node/lane 时，这些入口必须使用目标 lane 的 YAML 事实解析 backendProfile、providerId、workspaceRef、executionPolicy、provider credential SecretRef、tool credential SecretRef、namespace 和 source truth；不得在解释、dry-run、短命令或 JSON body 路径中回退到 control-plane default 或历史全局 sessionPolicy。
6.3 OPS-YAML-REQ-003 Secret 绑定与敏感输出
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-YAML-REQ-003 | 密钥绑定 | PJ2026-01060303 密钥绑定 | 用户管理、Agent编排 |
YAML运维应通过 sourceRef、targetKey、providerCredential 和 manual binding source 描述密钥来源与运行面目标，使 Sub2API、Codex pool、AgentRun 和后续平台服务可以按声明同步凭据。
密钥相关输出只能展示对象名、key 名、sourceRef、presence、fingerprint、字节数和执行摘要，不得打印 base64 payload、解码值、完整 DSN、API key 或可复制凭据。运行面只能作为 presence 和 health 观测对象，不能被用来反推本地配置真相。
目标 lane 缺少 providerCredential、tool credential、targetKey 或 sourceRef 时，应作为 YAML 配置或 AipodSpec binding 缺口暴露。受控 CLI 可以显示缺失对象名、key 名、YAML path、presence=false、fingerprint 缺失和 valuesPrinted=false，但不得用手工 Secret、复制其他 lane 凭据、读取运行面 Secret value 或 patch namespace 的方式修复配置缺口。
6.4 OPS-YAML-REQ-004 公开入口渲染
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-YAML-REQ-004 | 暴露渲染 | PJ2026-01060304 暴露渲染 | 客户端、用户管理、Agent编排 |
YAML运维应从 publicExposure 和 target 声明渲染 FRP、Caddy、public URL、TLS 和 public health 所需配置，使公开入口由 YAML 控制并能被 CLI 解释。
公开入口渲染负责入口目标、健康探针和运行面配置的一致性。页面行为、API 契约、用户登录和 Agent 任务语义由关联 L1 定义；YAML运维只保证这些入口被正确投递到声明的目标运行面。
每个 node/lane 的正式用户入口必须由 YAML 中的 public.webUrl、public.apiUrl 和 publicExposure 共同声明。FRP remote port、Caddy backend、本地 service DNS、旧 direct port、历史 nip.io 域名或仓库 generic deploy 默认值只能作为实现细节、诊断入口或 legacy 对照，不能反向覆盖 node/lane 的正式入口真相。
受控 CLI、文档生成和验收提示应优先输出正式 public URL，并把实现端口标注为诊断用途。缺少正式 public URL、DNS 与 expectedA 不一致、Caddy/FRP 渲染目标不一致或运行面 health 不匹配时，应暴露为 publicExposure 配置或投递缺口，而不是让调用方回退到旧端口继续验收。
6.5 OPS-YAML-REQ-005 AgentRun 执行策略配置
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-YAML-REQ-005 | 执行策略 | PJ2026-01060305 执行策略 | Agent编排、用户管理 |
YAML运维应为 AgentRun control-plane default、client sessionPolicy、lane secret providerCredential、workspace、execution policy 和 cancel lifecycle policy 提供配置读取与解释，使 AgentRun 运维入口不依赖代码内固定 profile、namespace、取消超时或执行策略。
cancel lifecycle policy 至少应能声明取消信号投递方式、runner graceful abort、kill escalation、stale heartbeat fencing window、late write fencing 和默认事件阶段输出开关。CLI 只校验字段结构、类型、必填项和可渲染性；具体窗口、超时和开关值由 YAML 承载，不在代码或 SPEC 中写成第二真相。
sessionPolicy 的解释、Session follow-up 的 run body、AipodSpec render 结果和 resource primitive 的 dry-run/JSON 形态必须来自同一套 YAML 目标解析。非默认 lane 的 backendProfile、providerId、workspaceRef、executionPolicy 和 provider credential SecretRef 不得被全局 default lane 覆盖；输出中应明确目标 lane 与 policy 来源，使操作者能在创建 run/command 前发现 lane 绑定错误。
本需求只约束执行策略如何作为平台配置进入运行面。Agent run、command、session 状态机、任务恢复、取消语义和 provider 业务语义由 Agent编排负责，用户身份和 API key 约束由用户管理负责。
6.6 OPS-YAML-REQ-006 公共 ops primitive
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-YAML-REQ-006 | 公共原语 | PJ2026-01060306 公共原语 | 平台运维 |
YAML运维应沉淀公共 ops primitive，使字段解析、YAML path 捕获、fingerprint、Secret 引用、摘要输出和配置错误说明在 Sub2API、AgentRun 和后续平台 CLI 中复用。
公共 ops primitive 的职责是减少重复硬编码和输出口径漂移。领域 CLI 仍负责自身命令形态和服务语义，但不得复制一套不同的敏感输出、fingerprint、字段解析或 YAML 缺失处理规则。
受控 CLI 的默认输出必须是有界摘要、关键字段表格和下一步 drill-down 命令；/tmp/unidesk-cli-output dump 只能作为异常兜底，不能成为正常交互路径。完整 JSON、raw payload、完整 task/result/log、长 plan 和机器消费输出只能在显式 --full、--raw、-o json 或等价机器消费参数下返回，并仍须遵守 Secret 脱敏规则。
6.7 OPS-YAML-REQ-007 控制面模块化
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-YAML-REQ-007 | 控制面模块化 | PJ2026-01060307 控制面模块化 | 发布流水、源码同步、平台运维 |
YAML运维应约束 CI/CD、YAML-first 和平台基础设施 CLI 的源码入口，使超过 3000 行的控制面文件先按职责拆入领域子目录，再继续沉淀公共 ops primitive。
原 scripts/src/*.ts 同名入口应只保留兼容 re-export、命令路由或极薄 adapter。配置解析、manifest 渲染、远端脚本、Secret/public exposure、git-mirror、Tekton/Argo、status summary 和 bounded output 等职责应进入领域模块或共享 helper。新增平台运维逻辑不得继续追加到已超限入口文件。
6.8 OPS-YAML-REQ-008 CI/CD YAML目标治理
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-YAML-REQ-008 | YAML目标治理 | PJ2026-01060308 CI/CD YAML目标治理 | 发布流水、源码同步、控制面模块化 |
YAML运维应约束 CI、deploy、artifact-registry、HWLAB node/lane、AgentRun、platform-infra、Secret 分发和 public exposure 的目标解析，使 node、lane、target、namespace、route、workspace、registry endpoint、public URL、SecretRef、gitops path 和 CI/CD 参数来自 owning YAML 或显式参数。
公共 option parser 不得内置 domain target 默认。未显式传入目标时，调用 domain 可以从自身 YAML default 解析，并必须输出默认来源路径；已显式传入 node/lane/target 时，解析器只校验和解释该目标，不得用全局 default 覆盖。
跨 YAML 的运行目标事实应使用 path/to/file.yaml#object.path configRef，CLI plan/status --full 应显示引用链、resolved target、presence、摘要 hash 和缺失字段，不打印 Secret 值。代码中保留的 G14、D601、v02、v03 等目标名必须被 hardcode inventory 分类为 legacy adapter、help example、test fixture 或真实领域特例；隐藏默认必须迁移到 YAML。
6.9 OPS-YAML-REQ-009 Host 引导代理
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-YAML-REQ-009 | Host引导代理 | PJ2026-01060311 Host引导代理 | 发布流水、源码同步、平台运维 |
YAML运维应为新节点提供 k3s 安装前可用的 host proxy client 能力。该 client 必须是 0 依赖分发对象，不能依赖 Docker、k3s、containerd、Node、Python、Bun、Go、Rust 或需要出网的包管理器安装步骤；它通过 trans 进入目标 host，并从 YAML 渲染本地监听、上游代理、Secret sourceRef、systemd 或等价 host 控制、健康探针和环境注入目标。
host proxy client 的职责是给 k3s installer、containerd image pull、包管理器、Git、git-mirror sync/flush 和受控 host 依赖安装提供初始出网。provider-gateway 和 trans 是控制通道，不应承载大二进制和大量依赖下载的长期数据通道。k3s 安装、Argo/git-mirror/web-probe/哨兵等后续运行面必须通过 YAML 声明是否使用 host proxy route、in-cluster proxy Service 或 direct egress。
host proxy 输出必须保持敏感信息边界。CLI 可以展示监听地址、端口、service 状态、sourceRef、fingerprint、probe 摘要和 NO_PROXY 覆盖状态；不得打印代理凭据、订阅内容、完整 URL credential、API key 或可复制密钥。NO_PROXY 必须保留本地、集群、metadata 和显式直连域，包括 hyueapi.com 与 .hyueapi.com。
6.10 OPS-YAML-REQ-010 YAML 配置组合
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-YAML-REQ-010 | 配置组合 | PJ2026-01060312 配置组合 | 控制面模块化、YAML目标治理 |
YAML运维应支持可复用、可继承、可组合的配置结构，使多个 node/lane 可以从公共 baseline、共享 configRef 和短 override 得到具体运行计划，而不是复制整段配置到每个节点文件。组合后的 effective plan 只作为执行和解释视图存在，不得写回为第二份可编辑真相源。
变量渲染只能把 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 | 发布流水、YAML目标治理 |
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 不属于迁移目标。