fix: improve egress and job diagnostics (#969)
Co-authored-by: Codex <codex@noreply.local>
This commit is contained in:
Lyon
@@ -19,6 +19,7 @@
|
||||
| 短名 | 运维监控 |
|
||||
| 层级 | 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) |
|
||||
@@ -42,6 +43,7 @@
|
||||
- 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 范围外
|
||||
@@ -62,6 +64,8 @@
|
||||
| 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 摘要字段。 |
|
||||
@@ -94,6 +98,7 @@
|
||||
| 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 生产哨兵、持续 canary、报告视图、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. 原子需求
|
||||
|
||||
@@ -274,6 +279,77 @@ Web 哨兵的首条生产 canary 应覆盖 `workbench-dsflash-go-tool-call-10x`
|
||||
|
||||
发布流水可调用 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 或完整业务正文。
|
||||
|
||||
`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。
|
||||
|
||||
## 7. 过程控制
|
||||
|
||||
本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。
|
||||
|
||||
Reference in New Issue
Block a user