Codex
11 KiB
PJ2026-0106 平台运维
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|---|---|---|
| v0.3 | b5d8cee438 |
2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 |
| v0.2 | b0cbe9b721 |
2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 |
| v0.1 | 37de91c653 |
2026-06-14 | 从迁移来源 pikasTech/HWLAB#1208 迁移到 UniDesk 项目管理目录。 |
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-0106 平台运维需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-0106 |
| 短名 | 平台运维 |
| 层级 | L1 方向 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-01 HWLAB 总规格 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留平台运维的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
平台运维负责为 HWLAB 各业务方向提供受控发布、源码同步、YAML-first 自动化分布式运维、公开入口和 Prometheus 运维监控支撑。它是 HWLAB 的后勤保障方向，不把运维动作包装成对外产品能力，也不替代业务 L1 定义功能需求。
2.2 范围内
- CI/CD、PipelineRun、image、rollout、trigger-current 和发布状态。
- Git mirror、source commit authority、bundle/mirror URL、lane source truth 和 GitOps 源同步。
- YAML-first 自动化分布式运维，包括 target、lane、node、service 声明、render、validate、受控下发和配置可见性。
- YAML-first 运维下的 SecretRef 子项，包括 sourceRef、targetKey、fingerprint、presence、轮换和敏感输出约束。
- FRP、Caddy、domain、TLS、public health 和公开入口漂移处理。
- Prometheus metrics、scrape target、alert rule、服务健康指标、资源指标和运行面监控口径。
2.3 范围外
- HWLAB 对外产品能力、用户目标和业务行为定义归对应 L0/L1 规格。
- 用户身份、API key、额度、账本和租户策略归 用户管理。
- Agent run、command、session、workspace 和 provider profile 语义归 Agent编排。
- HWPOD 资源、硬件事实和 probe 能力归 硬件池。
- CaseRun 评价、回放、训练反馈和执行结果语义归 HarnessRL。
- Web、CLI 和 HTTP API 的用户入口体验归 客户端。
3. 术语表
| 术语 | 定义 |
|---|---|
| 受控发布 | 通过标准 CI/CD、镜像、rollout 和状态查询入口完成的服务交付过程。 |
| Git mirror | 为目标运行面提供源码同步和 source commit authority 的镜像机制。 |
| YAML-first | UniDesk 自有配置以 YAML 为真相源，运行面和 CLI 从 YAML 渲染、校验并受控下发。 |
| SecretRef | YAML-first 运维中的密钥声明子项，指向密钥来源和目标 key，运行输出只披露摘要和存在性。 |
| 公开入口 | FRP、Caddy、域名、TLS 和健康检查共同形成的外部访问面。 |
| Prometheus 运维监控 | 通过 Prometheus 采集 metrics、维护 scrape target、alert rule 和服务健康指标的运维监控能力。 |
4. 系统边界和接口
本规格把平台运维作为 HWLAB 内部的运行支撑子系统看待；本章只描述该子系统的输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | HWLAB 各 L1 模块、平台管理员、发布操作人员和需要运行状态的自动化任务。 |
| 外部输入 | Git commit、PR merge、镜像产物、YAML 配置、SecretRef 子项、公开入口声明、metrics endpoint、服务健康指标和运行状态查询。 |
| 受控资源 | CI/CD pipeline、Git mirror、运行 lane、Kubernetes 资源、YAML-first 运维配置、SecretRef 下发、FRP/Caddy、Prometheus scrape target、metrics 和 alert rule。 |
| 外部输出 | 发布状态、source commit、配置渲染结果、Secret 摘要、public URL health、Prometheus target 状态、metrics 查询结果、alert 状态和运行支撑记录。 |
| 用户接口 | UniDesk CLI、HWLAB 控制面命令、受控 Secret 命令、平台基础设施命令、Prometheus 查询和告警入口。 |
| 系统边界 | 平台运维负责交付、YAML-first 自动化分布式运维、入口和 Prometheus 运维监控可控；不定义硬件、Agent、Harness、客户端或用户管理的业务成功标准。 |
5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-010601 | 发布流水 | PJ2026-010601 发布流水 | CI/CD、PipelineRun、image、rollout、trigger-current 和发布状态 | Git commit、镜像配置、各 L1 发布需求 | 全部 L1 |
| PJ2026-010602 | 源码同步 | PJ2026-010602 源码同步 | Git mirror、source commit authority、bundle/mirror URL 和 lane source truth | Git remote、运行 lane、Agent 资源装配需求 | Agent编排、HarnessRL、客户端 |
| PJ2026-010603 | YAML-first运维 | PJ2026-010603 YAML运维 | YAML-first 自动化分布式运维；SecretRef、targetKey、fingerprint 是其密钥分发子项 | 各 L1 配置需求、密钥来源 | 全部 L1 |
| PJ2026-010604 | 公开入口 | PJ2026-010604 公开入口 | FRP、Caddy、domain、TLS、public health 和入口漂移处理 | 客户端/API 服务、运行 lane | 客户端、用户管理、Agent编排 |
| PJ2026-010605 | 运维监控 | PJ2026-010605 运维监控 | Prometheus metrics、scrape target、alert rule、服务健康指标和资源指标 | 运行面 metrics endpoint、各 L1 服务健康指标 | 全部 L1 |
6. 原子需求
6.1 OPS-L1-REQ-001 受控发布
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-L1-REQ-001 | 受控发布 | PJ2026-010601 发布流水 | 客户端、Agent编排、用户管理、硬件池、HarnessRL |
平台运维应提供受控发布能力，使 HWLAB 服务变更能够通过标准 CI/CD、镜像构建、rollout、trigger-current 和状态查询进入目标运行面。
受控发布只保证变更以可追踪、可回滚、可观察的方式交付到目标运行面。具体业务能力是否满足需求，仍由对应 L1 规格定义，不能用 PipelineRun 成功替代业务完成。
6.2 OPS-L1-REQ-002 源码同步与运行真相
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-L1-REQ-002 | 源码同步 | PJ2026-010602 源码同步 | Agent编排、HarnessRL、客户端 |
平台运维应提供源码同步与运行真相能力，使目标 lane 使用明确的 Git mirror、source commit、bundle/mirror URL 和 GitOps 来源。
源码同步必须让运行面能够说明自己来自哪个 commit 和哪条受控来源。Agent编排可以消费 source truth 装配 workspace，HarnessRL 可以引用源码上下文执行 CaseRun，但它们不接管 mirror 和 lane source authority。
6.3 OPS-L1-REQ-003 YAML-first 自动化分布式运维
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-L1-REQ-003 | YAML-first运维 | PJ2026-010603 YAML运维 | 用户管理、Agent编排、客户端、硬件池 |
平台运维应提供 YAML-first 自动化分布式运维能力，使 HWLAB 自有配置、target、lane、node、service 声明、render、validate 和受控下发通过 YAML 真相源进入运行面。
SecretRef、targetKey、fingerprint 和 presence 是 YAML-first 运维下的密钥分发子项，不单独作为 L2 边界。业务模块负责定义自身配置需求和密钥来源，平台运维负责把这些 YAML 声明和 SecretRef 子项安全地渲染、校验并下发到运行面。
YAML-first 运维的命令输出只能披露摘要、对象名、key 名、sourceRef、fingerprint 和存在性，不得泄漏敏感值，也不得用运行面反推本地配置真相。
6.4 OPS-L1-REQ-004 公开入口
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-L1-REQ-004 | 公开入口 | PJ2026-010604 公开入口 | 客户端、用户管理、Agent编排 |
平台运维应提供公开入口支撑能力，使 HWLAB 的 Web、API 和管理入口能够通过正确的 FRP、Caddy、域名、TLS 和 health 目标暴露到外部。
公开入口负责外部流量到目标 runtime 的正确连通和漂移收敛。页面行为、API 契约、用户登录和 Agent 任务语义分别由客户端、用户管理和 Agent编排定义。
6.5 OPS-L1-REQ-005 Prometheus 运维监控
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-L1-REQ-005 | 运维监控 | PJ2026-010605 运维监控 | Agent编排、HarnessRL、硬件池、客户端、用户管理 |
平台运维应提供基于 Prometheus 的运维监控能力，使 HWLAB 运行面能够通过 metrics endpoint、scrape target、alert rule 和服务健康指标表达服务状态与资源状态。
Prometheus 运维监控只负责运维指标、采集目标、告警规则和监控口径。各 L1 提供自身服务健康指标和运行需求；平台运维负责把这些指标接入 Prometheus 并维护可查询、可告警的监控面。
Prometheus 监控不能替代业务功能实现、CaseRun 评价、Agent 状态模型、硬件事实或用户账本。业务成功仍由对应 L1 定义，监控只用于运行面健康和资源状态判断。