Lyon
14 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 运维监控和 GitHub 受控入口支撑。它是 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、OpenTelemetry tracing、scrape target、alert rule、服务健康指标、资源指标、trace backend 查询和运行面监控口径。
- GitHub issue/PR、正文 patch、board、attachment、scan、preflight 和 merge 的受控 CLI 入口。
2.3 范围外
- HWLAB 对外产品能力、用户目标和业务行为定义归对应 L0/L1 规格。
- 用户身份、API key、额度、账本和租户策略归 用户管理。
- Agent run、command、session、workspace 和 provider profile 语义归 Agent编排。
- HWPOD 资源、硬件事实和 probe 能力归 硬件池。
- CaseRun 评价、回放、训练反馈和执行结果语义归 HarnessRL。
- Web、CLI 和 HTTP API 的用户入口体验归 客户端。
- GitHub issue/PR 中承载的业务需求、执行证据和讨论内容归对应业务规格或执行 issue；平台运维只负责 GitHub 受控入口本身。
3. 术语表
| 术语 | 定义 |
|---|---|
| 受控发布 | 通过标准 CI/CD、镜像、rollout 和状态查询入口完成的服务交付过程。 |
| Git mirror | 为目标运行面提供源码同步和 source commit authority 的镜像机制。 |
| YAML-first | UniDesk 自有配置以 YAML 为真相源，运行面和 CLI 从 YAML 渲染、校验并受控下发。 |
| SecretRef | YAML-first 运维中的密钥声明子项，指向密钥来源和目标 key，运行输出只披露摘要和存在性。 |
| 公开入口 | FRP、Caddy、域名、TLS 和健康检查共同形成的外部访问面。 |
| 运维监控 | 通过 Prometheus 采集 metrics、通过 OpenTelemetry 关联 trace/span，并维护 scrape target、trace backend、alert rule 和服务健康指标的运维监控能力。 |
| Trace Explorer URL 模板 | YAML-first 运维配置中声明的 trace backend 打开链接模板，只允许静态 URL 与 {trace_id} 占位符，用于客户端展示“打开 Trace”。 |
| GitHub 受控入口 | 通过 UniDesk gh CLI 统一执行 issue/PR 读写、正文 patch、board mutation、attachment、preflight 和 merge guard 的操作面。 |
4. 系统边界和接口
本规格把平台运维作为 HWLAB 内部的运行支撑子系统看待；本章只描述该子系统的输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | HWLAB 各 L1 模块、平台管理员、发布操作人员和需要运行状态的自动化任务。 |
| 外部输入 | Git commit、PR merge、镜像产物、YAML 配置、SecretRef 子项、公开入口声明、metrics endpoint、OTLP endpoint、Trace Explorer URL 模板、服务健康指标和运行状态查询。 |
| 受控资源 | CI/CD pipeline、Git mirror、运行 lane、Kubernetes 资源、YAML-first 运维配置、SecretRef 下发、FRP/Caddy、Prometheus scrape target、OTel Collector、trace backend、metrics、alert rule 和 GitHub 受控入口。 |
| 外部输出 | 发布状态、source commit、配置渲染结果、Secret 摘要、public URL health、Prometheus target 状态、metrics 查询结果、trace 查询摘要、Trace Explorer URL 模板摘要、alert 状态、GitHub 写入摘要和运行支撑记录。 |
| 用户接口 | UniDesk CLI、HWLAB 控制面命令、受控 Secret 命令、平台基础设施命令、Prometheus 查询、OpenTelemetry trace 查询、告警入口和 GitHub 受控 CLI。 |
| 系统边界 | 平台运维负责交付、YAML-first 自动化分布式运维、入口、Prometheus metrics、OpenTelemetry tracing 和 GitHub 操作入口可控；不定义硬件、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、OpenTelemetry tracing、scrape target、trace backend、alert rule、服务健康指标和资源指标 | 运行面 metrics endpoint、OTLP endpoint、各 L1 服务健康指标和关键请求 span | 全部 L1 |
| PJ2026-010606 | GitHub入口 | PJ2026-010606 GitHub入口 | issue/PR 读写、正文 guard、board mutation、attachment、scan、preflight 和 merge guard | GitHub API、源码同步、发布流水 | 项目治理、PR closeout、agent 执行 |
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 和 OpenTelemetry 的运维监控能力，使 HWLAB 运行面能够通过 metrics endpoint、scrape target、OTLP endpoint、trace backend、alert rule 和服务健康指标表达服务状态、资源状态和单次请求因果链。
运维监控只负责运维指标、采集目标、trace backend、告警规则和监控口径。各 L1 提供自身服务健康指标、关键请求 span 语义和运行需求；平台运维负责把 metrics 接入 Prometheus，把 trace/span 接入 OpenTelemetry，并维护可查询、可告警、可回溯的监控面。
运维监控不能替代业务功能实现、CaseRun 评价、Agent 状态模型、硬件事实或用户账本。业务成功仍由对应 L1 定义，监控只用于运行面健康、资源状态和单次请求因果链排障。
Trace Explorer URL 模板、OTLP endpoint、采样/导出开关、trace backend endpoint、Collector/Tempo/Jaeger/Grafana 等组件镜像和保留策略必须归属 YAML-first 运维配置；SPEC 只定义能力和脱敏边界，不硬编码具体 URL、token、namespace、采样率或保留周期。运行面对象和 trace 查询结果只能作为观测证据，不能反推为配置真相。
6.6 OPS-L1-REQ-006 GitHub 受控入口
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| OPS-L1-REQ-006 | GitHub入口 | PJ2026-010606 GitHub入口 | 源码同步、发布流水 |
平台运维应提供 GitHub 受控入口，使 issue/PR 读写、正文 patch、评论、board mutation、attachment、escape scan、PR preflight 和 merge 都通过 UniDesk CLI 的统一 guard 路径执行。
GitHub 受控入口只保证 GitHub 操作路径、保护策略和输出契约可控。issue/PR 正文承载的业务需求、运行证据和收口结论仍归对应业务规格与执行 issue；不能用 GitHub 写入成功替代业务能力验收，也不能绕过受控 CLI 使用原生 gh、raw curl 或手写 GitHub API 作为正式写入路径。