# PJ2026-0106 平台运维 ## 修改历史 | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | | v0.3 | b5d8cee438a3bd66ca440a25bf5a16d9081d9efa | 2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 | | v0.2 | b0cbe9b721b50e9fff4d350ee50ed2af03cf0405 | 2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 | | v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从迁移来源 pikasTech/HWLAB#1208 迁移到 UniDesk 项目管理目录。 | 当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 ## 正文 ## PJ2026-0106 平台运维需求规格 ## 1. 文档控制 | 字段 | 内容 | | --- | --- | | 编号 | PJ2026-0106 | | 短名 | 平台运维 | | 层级 | L1 方向 | | 状态 | 已生效 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) | | 规格治理索引 | [规格治理](spec-governance.md) | 本文采用 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、额度、账本和租户策略归 [用户管理](PJ2026-0105-user-management.md)。 - Agent run、command、session、workspace 和 provider profile 语义归 [Agent编排](PJ2026-0102-agent-orchestration.md)。 - HWPOD 资源、硬件事实和 probe 能力归 [硬件池](PJ2026-0101-hardware-pool.md)。 - CaseRun 评价、回放、训练反馈和执行结果语义归 [HarnessRL](PJ2026-0103-harness-rl.md)。 - Web、CLI 和 HTTP API 的用户入口体验归 [客户端](PJ2026-0104-client.md)。 ## 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 发布流水](PJ2026-010601-controlled-release.md) | CI/CD、PipelineRun、image、rollout、trigger-current 和发布状态 | Git commit、镜像配置、各 L1 发布需求 | 全部 L1 | | PJ2026-010602 | 源码同步 | [PJ2026-010602 源码同步](PJ2026-010602-source-sync.md) | Git mirror、source commit authority、bundle/mirror URL 和 lane source truth | Git remote、运行 lane、Agent 资源装配需求 | Agent编排、HarnessRL、客户端 | | PJ2026-010603 | YAML-first运维 | [PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md) | YAML-first 自动化分布式运维；SecretRef、targetKey、fingerprint 是其密钥分发子项 | 各 L1 配置需求、密钥来源 | 全部 L1 | | PJ2026-010604 | 公开入口 | [PJ2026-010604 公开入口](PJ2026-010604-public-entry.md) | FRP、Caddy、domain、TLS、public health 和入口漂移处理 | 客户端/API 服务、运行 lane | 客户端、用户管理、Agent编排 | | PJ2026-010605 | 运维监控 | [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) | Prometheus metrics、scrape target、alert rule、服务健康指标和资源指标 | 运行面 metrics endpoint、各 L1 服务健康指标 | 全部 L1 | ## 6. 原子需求 ### 6.1 OPS-L1-REQ-001 受控发布 | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | | OPS-L1-REQ-001 | 受控发布 | [PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | 平台运维应提供受控发布能力，使 HWLAB 服务变更能够通过标准 CI/CD、镜像构建、rollout、trigger-current 和状态查询进入目标运行面。 受控发布只保证变更以可追踪、可回滚、可观察的方式交付到目标运行面。具体业务能力是否满足需求，仍由对应 L1 规格定义，不能用 PipelineRun 成功替代业务完成。 ### 6.2 OPS-L1-REQ-002 源码同步与运行真相 | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | | OPS-L1-REQ-002 | 源码同步 | [PJ2026-010602 源码同步](PJ2026-010602-source-sync.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) | 平台运维应提供源码同步与运行真相能力，使目标 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运维](PJ2026-010603-yaml-first-ops.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md)、[硬件池](PJ2026-0101-hardware-pool.md) | 平台运维应提供 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 公开入口](PJ2026-010604-public-entry.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) | 平台运维应提供公开入口支撑能力，使 HWLAB 的 Web、API 和管理入口能够通过正确的 FRP、Caddy、域名、TLS 和 health 目标暴露到外部。 公开入口负责外部流量到目标 runtime 的正确连通和漂移收敛。页面行为、API 契约、用户登录和 Agent 任务语义分别由客户端、用户管理和 Agent编排定义。 ### 6.5 OPS-L1-REQ-005 Prometheus 运维监控 | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | | OPS-L1-REQ-005 | 运维监控 | [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) | 平台运维应提供基于 Prometheus 的运维监控能力，使 HWLAB 运行面能够通过 metrics endpoint、scrape target、alert rule 和服务健康指标表达服务状态与资源状态。 Prometheus 运维监控只负责运维指标、采集目标、告警规则和监控口径。各 L1 提供自身服务健康指标和运行需求；平台运维负责把这些指标接入 Prometheus 并维护可查询、可告警的监控面。 Prometheus 监控不能替代业务功能实现、CaseRun 评价、Agent 状态模型、硬件事实或用户账本。业务成功仍由对应 L1 定义，监控只用于运行面健康和资源状态判断。