pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md

# PJ2026-010605 运维监控

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。

## 正文

## PJ2026-010605 运维监控需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010605 |
| 短名 | 运维监控 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-26-p8-egress-job-friction |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB 运维监控的稳定使命、范围、术语、系统边界、内部分工和原子需求。Prometheus 继续承载 metrics、dashboard、alert 和 Workbench 用户可感知性能指标；OpenTelemetry 首期只承载 tracing、span、trace id 关联和跨服务因果链路。Workbench 用户可感知性能监控的架构图、数据流图、时序图和实现引用要求由 [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) 细化。

## 2. 目的和范围

### 2.1 目的

运维监控负责通过 Prometheus 和 OpenTelemetry 的分工协作采集 HWLAB 运行面 metrics、scrape target、alert rule、服务健康指标、资源指标和关键请求 trace，使平台运维能够发现服务不可用、入口漂移、资源异常、发布后运行状态退化，以及单个 Workbench/AgentRun 请求在 admission、billing、dispatch、projection 或 replay 阶段的失败位置。

本课题的目标状态是：各业务 L1 提供自己的服务健康、业务状态指标和关键链路 trace 语义，平台运维统一接入 Prometheus metrics 面和 OpenTelemetry tracing 面并输出可查询、可告警、可回溯的运维状态；监控只判断运行面健康、资源状态和单次请求因果链，不替代业务成功标准。

运维监控接入必须遵循 UniDesk YAML-first ops：scrape target、alert rule、recording rule、summary query、OTel Collector、trace backend、target/node/lane、namespace、endpoint、采样/保留/阈值等 UniDesk 自有运维事实必须归属 YAML；受控 CLI 负责读取、校验、渲染、apply/status/summary/trace。运行面对象、Prometheus 查询结果和 trace backend 查询结果只作为观测证据，不反推为配置真相。

### 2.2 范围内

- Prometheus scrape target、metrics endpoint、alert rule 和服务健康指标接入。
- OpenTelemetry Collector、trace backend、span 语义、trace context 传播和 trace 查询入口。
- Web/API/AgentRun/HWPOD/Harness/用户管理等服务的运行面健康、资源状态、公开入口健康和用户可感知性能观测。
- 发布后 runtime readiness、resource usage、error rate、queue depth、target availability 和 alert 状态摘要。
- AgentRun rolling recovery 与 cancel lifecycle 的 active runner、stale lease、cancel request、cancel delivery、terminal report retry、reconciler backlog、projection lag、late-write fencing 和 Job TTL cleanup 观测。
- provider-gateway egress TCP tunnel、backend-core egress bridge、受控 relay、异步 job 和 server lifecycle 命令的阶段化可见性。
- 监控和 trace 数据的受控查询、低噪声摘要、失败归因和敏感输出约束。

### 2.3 范围外

- Agent command、CaseRun、HWPOD operation 或用户账本的业务成功标准由对应 L1 定义。
- 完整 prompt、assistant 正文、tool 参数、命令输出、原始日志、测试报告、截图、CaseRun registry 和用户反馈正文不进入本规格或默认 trace attribute。
- Prometheus 具体阈值、保留周期、告警路由、采样间隔和容量数值以 YAML/config 为准，不在本规格硬编码。
- OpenTelemetry Collector image、trace backend image、存储模式、retention、采样率、endpoint 和服务接入关系以 YAML/config 为准，不在业务代码硬编码。
- 监控告警不能代替发布流水、业务验证、CaseRun 评价或用户反馈分流。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| Prometheus 运维监控 | 通过 Prometheus 采集、查询和告警 HWLAB 运行面 metrics 的运维能力。 |
| OpenTelemetry tracing | 通过 OTel Collector、trace backend、span 和 W3C trace context 关联单次请求跨服务因果链路的运维能力。 |
| trace backend | 保存并查询 trace/span 的平台组件，首期可由 Tempo 或 Jaeger 承担，部署事实由 YAML 控制。 |
| Trace Explorer URL 模板 | 由 YAML 声明的 trace backend 打开链接模板，例如包含 `{trace_id}` 占位符的 Tempo、Jaeger 或 Grafana Explore URL；前端只替换合法 OTel trace id，不拼接其他用户输入。 |
| span | 一次请求在 admission、billing、AgentRun dispatch、projection、read/replay 等阶段中的一个可观察工作单元。 |
| trace context | W3C `traceparent`/`baggage` 等跨进程传播上下文；业务 `traceId/sessionId/runId/turnId` 只能作为 span attribute，不能替代标准 trace context。 |
| provider egress TCP tunnel | target node 上 provider-gateway egress proxy 通过 backend-core WebSocket 控制通道请求 master 侧打开 TCP 连接，并在两端转发字节流的出站链路。 |
| async job 摘要 | `server start|stop|rebuild|restart` 等长操作创建 `.state/jobs` 后默认返回的低噪声身份、状态、日志路径和后续查询命令，不默认展开完整命令或 stdout/stderr。 |
| 用户可感知性能 | 用户在 Web、CLI 或 API 入口中直接感受到的等待时间、加载时间、首个可读内容出现时间和完整可用状态。 |
| YAML-first 运维监控 | Prometheus scrape、rule、summary 和 target 归属先进入 UniDesk YAML，再通过受控 CLI 渲染和验证的运维形态。 |
| rolling recovery signal | 用于判断 manager/cloud-api rolling 后同一 run/command/runnerJob 是否恢复控制权的低基数 metrics、span attribute 和 CLI 摘要字段。 |
| scrape target | Prometheus 抓取 metrics 的目标服务、path 和 label 集合。 |
| metrics endpoint | 服务暴露运行状态、资源状态和业务健康指标的 HTTP 端点。 |
| alert rule | 对 metrics 表达告警条件的规则，具体阈值来自配置。 |
| 运行健康 | 服务 ready、live、依赖可达、资源可用和错误率处于可接受状态的运维判断。 |
| 业务通过 | 由业务 L1 原入口定义的功能成功，例如 Agent turn completed、HWPOD operation 成功或 CaseRun 通过。 |

## 4. 系统边界和接口

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 平台管理员、发布操作人员、值守自动化、需要运行状态的各 L1 owner。 |
| 外部输入 | 服务 metrics endpoint、health/readiness、runtime resource 指标、scrape 配置、alert rule 配置、OTLP trace/span、trace context、trace 查询请求和 metrics 查询请求。 |
| 受控资源 | Prometheus target、metrics、alert rule、OTel Collector、trace backend、运行面状态摘要、服务健康指标、资源指标和 redacted trace 摘要。 |
| 外部输出 | target 状态、metrics 查询结果、alert 状态、trace 查询结果、Trace Explorer URL 模板摘要、运行健康摘要、入口健康摘要和 redacted 失败阶段。 |
| 用户接口 | Prometheus 查询、OpenTelemetry trace 查询、受控平台运维 CLI、发布状态摘要和各 L1 health/status 页面或命令。 |
| 系统边界 | 运维监控负责运行面可观察、告警和单次请求因果链；不定义业务完成标准，不保存默认长证据，不把监控 green 或 trace 可查当作业务通过。 |

## 5. 内部分工与规格索引

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-01060501 | OTel追踪 | 本规格 6.1 | OTel Collector、trace backend、span 语义、trace context 和受控 trace 查询 | HWLAB v0.3、AgentRun、用户账本、Web工作台 | 平台排障、Prometheus 关联 |
| PJ2026-01060502 | 告警规则 | 本规格 6.2 | alert rule、状态分类和配置来源 | Metrics接入、YAML运维 | 平台值守、发布判定 |
| PJ2026-01060503 | 运行摘要 | 本规格 6.3 | health、readiness、resource、error rate 和入口健康摘要 | 公开入口、发布流水 | 管理员和各 L1 owner |
| PJ2026-01060504 | 边界约束 | 本规格 6.4 | 监控与业务通过、长证据、敏感输出的边界 | 全部 L1 | 用户反馈和排障 |
| PJ2026-01060505 | Workbench性能 | [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) | Web 工作台用户可感知性能、RUM、AgentRun event visible latency 和 Prometheus 指标口径 | Web工作台、Agent编排、API契约 | 平台运维、客户端和性能回归调查 |
| PJ2026-01060506 | Metrics接入 | 本规格 6.6 | metrics endpoint、scrape target 和 label 口径 | 各 L1 服务健康指标 | Prometheus 查询 |
| PJ2026-01060507 | Rolling恢复观测 | 本规格 6.7 | active runner、reconciler backlog、terminal retry、projection lag 和不可恢复 blocker 的查询口径 | AgentRun核心、HWLAB接入、Workbench实时权威、发布Lane | rolling 发布判定、故障收口 |
| PJ2026-01060508 | Web哨兵 | [PJ2026-01060508 Web哨兵](PJ2026-01060508-web-probe-sentinel.md) | `web-probe observe` 的 YAML-first 生产哨兵、独立 runner、中心 Monitor/Host PG、报告视图、dashboard 分析工作台和发布恢复验证 | Web工作台、Workbench实时权威、YAML运维、公开入口、发布流水 | 平台值守、CI/CD targetValidation、用户入口恢复判定 |
| PJ2026-01060509 | 出站诊断 | 本规格 6.9 | provider egress TCP tunnel、受控 relay、async job/server lifecycle 的阶段化日志、低噪声摘要和诊断入口 | provider-gateway、backend-core、YAML运维、发布流水 | D601/G14 runtime 出站排障、OpenFGA/Postgres/OA Event Flow 链路验收 |

## 6. 原子需求

### 6.1 OPS-MON-REQ-001 OTel 追踪

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-001 | OTel追踪 | PJ2026-01060501 OTel追踪 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |

运维监控应在 `platform-infra` 提供 YAML-first OpenTelemetry tracing 能力，使一次 Workbench submit 或等价 API 请求可以沿 Cloud API admission、billing preflight、AgentRun dispatch、projection write、trace events read 和 Web replay 等阶段保留可查询 span。

OpenTelemetry 不替代 Prometheus。Prometheus 继续承载 metrics、dashboard、alert 和用户可感知性能指标；OTel tracing 只回答单个 `traceId/sessionId/runId/turnId` 跨服务断在哪个阶段。业务 ID 可以作为 span attribute 用于排查，但不能成为 Prometheus label，也不能替代 W3C trace context。

#### 6.1.1 目标架构图

```mermaid
flowchart LR
  W[Workbench Web] --> API[HWLAB cloud-api]
  API --> Billing[user-billing]
  API --> AR[AgentRun manager]
  AR --> Runner[AgentRun runner]
  API --> Projection[projection/read model]
  API --> Metrics[Prometheus metrics endpoint]
  Billing --> Metrics
  AR --> Metrics
  API -- OTLP spans --> Collector[OTel Collector<br/>platform-infra]
  Billing -- OTLP spans --> Collector
  AR -- OTLP spans --> Collector
  Runner -- OTLP spans --> Collector
  Collector --> TraceBackend[Trace backend<br/>Tempo or Jaeger]
  Metrics --> Prometheus[Prometheus metrics面]
  CLI[UniDesk platform-infra observability CLI] --> Collector
  CLI --> TraceBackend
  CLI --> Prometheus
```

#### 6.1.2 数据流图

```mermaid
flowchart TD
  Span[应用关键 span] --> Collector[OTel Collector]
  Collector --> Backend[trace backend]
  Metric[低基数 metrics] --> Prometheus[Prometheus]
  Backend --> TraceQuery[CLI trace query]
  Prometheus --> MetricQuery[CLI metrics/status query]
  TraceQuery --> Diagnose[按 traceId/sessionId/runId 定位失败阶段]
  MetricQuery --> Health[运行健康、趋势和告警判断]
  Diagnose -.关联.-> Health
```

数据流必须保持职责分离：trace backend 保存高基数字段和跨服务因果链；Prometheus 只保存低基数指标、alert 和趋势。CLI 可以把 metrics 摘要与 trace 查询结果放到同一排障报告中，但不能把两套存储合并为一个第二真相。

#### 6.1.3 关键时序图

```mermaid
sequenceDiagram
  participant W as Workbench
  participant API as cloud-api
  participant B as user-billing
  participant AR as AgentRun
  participant P as projection
  participant OTel as OTel Collector
  participant TB as trace backend

  W->>API: POST /v1/agent/chat
  API->>OTel: span admission
  API->>B: billing_preflight with trace context
  B->>OTel: span billing_preflight
  API->>AR: dispatch command with trace context
  AR->>OTel: span agentrun_dispatch
  AR-->>API: runId/commandId
  API->>P: projection_write
  P->>OTel: span projection_write
  W->>API: replay/read trace events
  API->>OTel: span trace_events_read
  OTel->>TB: export spans
```

#### 6.1.4 YAML 与 CLI 归属

OTel Collector、trace backend、target route、namespace、image、storage、retention、sampling、export 开关、OTLP endpoint、Trace Explorer URL 模板、probe 和应用接入关系必须进入 `config/platform-infra/observability.yaml` 或后续确认的 owning YAML。正式入口必须是 `bun scripts/cli.ts platform-infra observability plan|apply|status|validate|trace` 或等价受控 CLI；`trans <target>:k3s` 只能作为有界诊断底座，不能成为长期 mutate path。

Trace Explorer URL 模板必须作为 YAML 配置下发到需要展示“打开 Trace”的客户端运行配置中。模板只能包含 `{trace_id}` 占位符和运维确认的静态 URL 片段；前端替换前必须校验 trace id 为 32 位十六进制字符串。配置缺失、模板禁用或 trace id 非法时，客户端只显示复制入口。任何实现都不得把 trace backend 内部地址、Grafana token、cookie、API key、`tracestate`、`baggage`、prompt、assistant 正文或 raw upstream payload 放入模板或用户可见 URL。

首期应用侧手工 span 至少覆盖：

- `POST /v1/agent/chat`
- `durable_admission`
- `billing_preflight`
- `agentrun_dispatch`
- `projection_write`
- `trace_events_read`
- `turn_status_read`

统一 resource attributes 至少包含 `service.name`、`deployment.environment`、`unidesk.node`、`hwlab.lane`、`k8s.namespace.name` 和 `git.commit`。统一传播使用 W3C `traceparent`/`baggage`；`traceId`、`sessionId`、`turnId`、`runId`、`commandId` 只能作为 span attribute。

用户可见错误只展示 OTel trace id、request id、route、serviceId、error code、layer 和 redacted observedAt。`traceparent` 可以作为 HTTP header 传播和返回，`tracestate` 与 `baggage` 只能用于受控传播，不得进入用户错误面板、issue closeout 可复制凭据、日志摘要或默认 trace explorer URL。

#### 6.1.5 代码引用规则

本需求范围内新增或修改的源码文件头部必须标注 `SPEC: PJ2026-01060501 OTel追踪 draft-2026-06-19-p0`，并用一句话说明文件职责。纯 YAML、生成 manifest、锁文件或第三方 CRD 如不能加头部，必须能从 owning YAML、渲染器或 CLI 命令追溯到本 SPEC。

### 6.2 OPS-MON-REQ-002 告警规则

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-002 | 告警规则 | PJ2026-01060502 告警规则 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[公开入口](PJ2026-010604-public-entry.md) |

运维监控应通过配置化 alert rule 表达服务不可达、目标缺失、入口漂移、资源耗尽、错误率异常和发布后健康退化等运维风险。

告警阈值、保留周期、通知路由和采样间隔由 YAML/config 承载；规格只定义告警能力和边界。告警输出应包含服务、target、rule、severity、状态和 redacted 摘要，不输出 Secret、token、DSN password 或完整日志。

### 6.3 OPS-MON-REQ-003 运行摘要

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-003 | 运行摘要 | PJ2026-01060503 运行摘要 | [发布流水](PJ2026-010601-controlled-release.md)、[公开入口](PJ2026-010604-public-entry.md) |

运维监控应提供低噪声运行摘要，使平台管理员能查看目标 node/lane 的服务健康、公开入口健康、资源使用、队列积压、错误分类和最近告警状态。

运行摘要用于判断运行面是否需要运维处理或发布回滚，不替代业务原入口。Web 可访问、API health 通过或 Prometheus green 只能证明运行面健康的一部分，不能证明 Agent、HWPOD、CaseRun、用户账本或内测业务用例通过。

### 6.4 OPS-MON-REQ-004 监控边界

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-004 | 边界约束 | PJ2026-01060504 边界约束 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

运维监控应明确区分运行健康、业务通过和长证据归属。监控只保存和展示运维指标、target 状态和告警摘要；长 trace、CaseRun registry、用户反馈原文、截图和执行日志仍保留在对应业务入口或 GitHub issue。

缺失业务能力时，监控只能报告 blocker 或 health 降级，不能通过新增告警、证据采样或诊断文案伪装成能力完成。

### 6.5 OPS-MON-REQ-005 Workbench 用户可感知性能

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-005 | Workbench性能 | [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) | [Web工作台](PJ2026-010401-web-workbench.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[API契约](PJ2026-010403-api-contract.md) |

运维监控应把 Web 工作台的用户可感知性能纳入 Prometheus 与 RUM 口径，使用户发消息到首个可见 Code Agent 输出、AgentRun backend event 到 Web 可见、session 切换加载和首屏打开等路径可以被持续观测。

Workbench 性能监控只记录低基数指标、阶段耗时、状态分类和脱敏 correlation；不得把 traceId、sessionId、runId、prompt、assistant 正文、tool 参数、stdout/stderr、Secret 或用户个人信息写入 Prometheus label。具体架构、数据流、时序和代码引用规则由 [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) 定义。

### 6.6 OPS-MON-REQ-006 Metrics 接入

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-006 | Metrics接入 | PJ2026-01060506 Metrics接入 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[发布流水](PJ2026-010601-controlled-release.md) |

运维监控应接入 HWLAB 各运行服务的 metrics endpoint 和 scrape target，使服务 live、ready、resource、queue、error、latency 和依赖健康可以被 Prometheus 查询。

各 L1 负责定义自身服务健康指标含义；平台运维负责通过 YAML-first UniDesk ops 统一接入、命名、label 和可查询状态。metrics 缺失应暴露为监控缺口，不得用日志 grep、一次性 curl、手工 `kubectl apply` 或人工截图替代长期监控。

### 6.7 OPS-MON-REQ-007 Rolling 恢复观测

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-007 | Rolling恢复 | PJ2026-01060507 Rolling恢复观测 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[Workbench实时权威](PJ2026-010401080313-workbench-realtime-authority.md)、[AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) |

运维监控应为 AgentRun/HWLAB rolling recovery 和 cancel lifecycle 提供可查询的低基数 metrics、trace span 和受控 CLI 摘要。最小观测对象包括 active runner 数、runner job observation phase、stale lease 数、cancel request accepted 数、cancel delivered 数、cancel terminalized 数、late-write-fenced 数、terminal report retry/outbox backlog、manager reconciler backlog、reconciler last success/error、projection lag、projection blocker 数、Job TTL cleanup 数和不可恢复 blocker 数。

rolling recovery 相关 span 应能用 OTel trace id/request id 关联 `sessionId`、`traceId`、`runId`、`commandId`、`runnerJobId` 和 `jobName` 的 redacted attribute。高基数业务 ID 只能作为 trace/span attribute 或 CLI 单次查询参数，不进入 Prometheus label；prompt、assistant 正文、tool 参数、stdout/stderr、Secret、完整 token、完整 DSN 和 provider payload 不得进入默认 metrics、span 或 issue closeout。

发布/rollout 前后的受控 CLI 摘要应能回答：仍在运行的 runner 数、已恢复控制权数量、cancel 当前阶段分布、terminal report retry 数、projection lag 最大值、不可恢复 blocker 数和最近一次 reconciler 错误。该摘要只用于定位和发布判定，不替代 P6 原入口 rolling/chaos 验收，也不能把可观测性 green 当作业务任务完成。

### 6.8 OPS-MON-REQ-008 Web 哨兵

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-008 | Web哨兵 | [PJ2026-01060508 Web哨兵](PJ2026-01060508-web-probe-sentinel.md) | [Web工作台](PJ2026-010401-web-workbench.md)、[Workbench实时权威](PJ2026-010401080313-workbench-realtime-authority.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、[公开入口](PJ2026-010604-public-entry.md)、[发布流水](PJ2026-010601-controlled-release.md) |

运维监控应提供 YAML-first Web 哨兵能力，把现有 `web-probe observe start/status/command/collect/analyze` 服务化为生产可用的持续 canary、报告视图和发布恢复验证入口。该能力只 wrap 现有 observe runner、control queue、artifact JSONL、`collect` 渲染和 `observe analyze` 报告，不新增第二套 Playwright runner、offline analyzer、finding classifier、dashboard 事实源或 Workbench 状态机。

Web 哨兵配置必须通过 node/lane root YAML 的 `observability.webProbe.sentinels[]` 引用各 runner owning YAML，并通过 `observability.webProbe.monitor.configRef` 引用中心 runtime、publicExposure、persistence、CI/CD 和 Secret owning YAML。parser 只校验引用、形状、类型和冲突；cadence、采样间隔、轮次、profile、prompt source、report view、retention、public exposure、maintenance 和 Secret 参数以 YAML 为准。

Web 哨兵多 runner 的结构化状态必须由中心 Monitor 服务写入 NC01 YAML-first Host PostgreSQL，并通过同一 bounded API 向 CLI 与 monitor-web 提供 global/scoped latest、history、finding 和 artifact locator。runner 只负责 observe/analyze 与不可变 artifact；禁止跨 runner HTTP fan-out、永久 SQLite 双写/fallback、第二 scheduler 或由页面合并全局事实。artifact bytes 可以保留在独立 runner PVC，但 locator、hash、owner 和可达性必须进入中心索引。

Web 哨兵 dashboard 应作为平台值守和问题分析工作台展示同一 observe/analyze 事实：首屏健康摘要、scheduler/maintenance、latest run、finding severity、runs history、run detail、turn-summary 和 trace-frame。Dashboard 不得新增采样器、analyzer、截图保存源或 Workbench 状态仲裁；自动刷新只能读取 bounded/redacted API。

Web 哨兵的首条生产 canary 应覆盖 `workbench-dsflash-go-tool-call-10x`：同一 HWLAB Workbench session 内十轮需要工具调用的任务，使用 `dsflash-go` backend profile，报告每轮 traceId、terminal status、tool-call evidence、耗时、慢 API、trace 顺序、terminal-not-last、session mismatch 和 final-response finding。`dsflash-go` profile、SecretRef、config 和 model catalog 缺失时必须结构化失败，不允许 fallback 到其他 profile。

发布流水可调用 Web 哨兵 maintenance start/stop。maintenance start 暂停告警但继续采样；maintenance stop 触发同一 observe CLI quick verify 和 analyze。CI/CD targetValidation 对 HWLAB Web 恢复的判断必须包含 quick verify、analysis report SHA、finding 摘要、public origin、scenario id 和 observer/run id；Argo green 但哨兵 red/timeout 时不得判定发布恢复成功。

### 6.9 OPS-MON-REQ-009 Provider 出站与 Job 可见性

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-MON-REQ-009 | 出站诊断 | PJ2026-01060509 出站诊断 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[公开入口](PJ2026-010604-public-entry.md)、[发布流水](PJ2026-010601-controlled-release.md) |

运维监控应为 provider-gateway egress TCP tunnel、backend-core egress bridge、受控 relay 和 CLI async job 提供阶段化可见性，使 D601/G14 等节点的 PostgreSQL、OpenFGA、OA Event Flow、Git mirror 或外部下载问题可以被定位到 provider 本地 proxy、backend-core open、master 侧 TCP connect、relay ACL、目标服务或调用方读写阶段。

provider egress tunnel 生命周期至少应记录：provider proxy 收到 client 请求、发出 `egress_tcp_open`、core 确认 opened、core connect failed/timeout、remote close、本地 open timeout、client close、pending buffer 超限和 idle close。日志和受控摘要必须包含 `providerId`、`connectionId`、目标 `host`/`port`、`method`、`ageMs`、`pendingBytes` 和低基数 failureKind；不得记录 TCP payload、PostgreSQL DSN 密码、HTTP Authorization、Secret、token 或完整业务正文。

针对 GitHub release、k3s installer、dependency pull 等大二进制下载，egress tunnel 观测与控制面观测必须分离：provider labels 至少分别暴露 `host.ssh.tcp-pool` readiness 与 egress active/pending/opened/stale tunnel 数，CLI 必须提供独立的 egress drill-down。egress drill-down 只能展示目标 host/port、路径摘要和 query key 摘要，不得展示 URL credential、header、token 或 query value；同时必须保留最近关闭 tunnel 的有界生命周期摘要，用于确认中断下载后的自动回收。

backend-core 向 provider WebSocket 写入大流量 `egress_tcp_data` 时，必须避免单个下载流无界挤占 control/dispatch 消息；实现可以使用独立通道、优先级队列、节流/yield 或等价 backpressure 策略，但验收必须证明大文件下载期间 `trans <provider> argv true` 仍可在可接受时间内返回。下载中断、provider 断开或发送通道关闭时，core 侧必须有有界时间内的 read/write loop 退出日志与 active connection drain 证据。

`server start|stop|rebuild|restart` 等创建 `.state/jobs` 的命令默认必须返回 async job 摘要，而不是完整 JSON payload、完整 command、完整 runtime env 或 stdout/stderr。摘要至少包含 job id、目标 service、当前状态、stdout/stderr 路径、`job status` 查询命令和必要的 `server logs`/`server status` 后续命令。完整结构只能通过 `--full`/`--raw` 或 `job status <id>` 渐进展开。`job` 与常见自然输入 `jobs`、`status|get|read` 应指向同一受控状态入口，避免调用者因为别名缺失退回手工文件读取。

#### 6.9.1 目标架构图

```mermaid
flowchart LR
  Pod[目标 runtime Pod] --> Proxy[provider-gateway egress proxy]
  Proxy -- egress_tcp_open/data/close --> Core[backend-core provider WS]
  Core --> Relay[受控 relay 或目标 TCP 服务]
  Relay --> Target[Postgres / OA Event Flow / external endpoint]
  Core --> Logs[backend-core logs]
  Proxy --> ProviderLogs[provider-gateway logs]
  CLI[UniDesk CLI job/status/triage] --> Logs
  CLI --> ProviderLogs
```

#### 6.9.2 数据流图

```mermaid
flowchart TD
  Request[CONNECT 或 HTTP proxy 请求] --> LocalEvent[provider proxy stage event]
  LocalEvent --> OpenMsg[egress_tcp_open]
  OpenMsg --> CoreEvent[backend-core open/connect stage event]
  CoreEvent --> Outcome{connect outcome}
  Outcome -->|opened| DataFlow[egress_tcp_data 双向转发]
  Outcome -->|failed/timeout| CloseMsg[egress_tcp_close with failureKind]
  DataFlow --> CloseMsg
  CloseMsg --> Summary[provider triage / job status / logs 摘要]
```

#### 6.9.3 关键时序图

```mermaid
sequenceDiagram
  participant C as Runtime client
  participant P as provider egress proxy
  participant B as backend-core
  participant R as Relay/Target
  participant CLI as UniDesk CLI

  C->>P: CONNECT host:port
  P->>P: log egress_proxy_tunnel_open_request
  P->>B: egress_tcp_open(providerId, connectionId, host, port)
  B->>B: log egress_tcp_open_requested/connect_start
  B->>R: TCP connect
  alt connect ok
    B->>P: egress_tcp_opened
    P->>P: log egress_proxy_tunnel_opened
    P-->>C: 200 Connection Established
  else connect failed or timeout
    B->>P: egress_tcp_close(error, failureKind)
    P->>P: log remote close
    P-->>C: connection close
  end
  CLI->>CLI: job status / logs / triage show bounded stage summary
```

#### 6.9.4 代码引用规则

本需求范围内新增或修改的源码文件头部必须标注 `SPEC: PJ2026-01060509 出站诊断 draft-2026-06-26-p8-egress-job-friction`。纯配置、生成 manifest 或无法承载注释头的文件必须能从 owning CLI、渲染器或运行日志追溯到本 SPEC。

涉及 `src/components/provider-gateway` 的出站诊断行为、日志或能力标签变更必须在同一 source 变更中递增 `src/components/provider-gateway/package.json` 的 `version`。运行面验收必须通过 `debug health`、公网节点视图或 `provider.upgrade` 任务结果确认目标 provider 上报了新 `providerGatewayVersion`；只看到源码合并或 updater 日志不能视为 provider-gateway 诊断能力已经交付到 D601/G14。

## 7. 过程控制

本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。