mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(web-probe): add multi-sentinel registry

Browse Source
This commit is contained in:
Codex
2026-06-26 12:42:04 +00:00
parent 7b3df965cc
commit 4e0f1cba21
25 changed files with 1038 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files
project-management/PJ2026-01/specs/PJ2026-01060508-web-probe-sentinel.md
+45 -14
View File
@@ -21,6 +21,7 @@
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-probe-sentinel |
| Dashboard 实现引用版本 | draft-2026-06-26-p8-web-probe-sentinel-recovery |
| 多实例实现引用版本 | draft-2026-06-26-p9-multi-web-probe-sentinel |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) |
| 关联规格 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md)、[PJ2026-010602 源码同步](PJ2026-010602-source-sync.md)、[PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md)、[PJ2026-010604 公开入口](PJ2026-010604-public-entry.md)、[PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) |
@@ -41,12 +42,13 @@ Web哨兵必须遵循 UniDesk YAML-first ops。目标 node/lane、public origin
### 2.2 范围内
- `web-probe observe` CLI 的 wrapper/adapter 边界，使常驻服务能够稳定调用 start/status/command/collect/analyze。
- YAML `observability.webProbe.sentinel.enabled/configRefs` 与 runtime、scenario、promptSet、reportView、publicExposure、Secret、CI/CD owning YAML 的引用图。
- YAML `observability.webProbe.sentinel.enabled/configRefs` 的 legacy 单实例入口，以及 `observability.webProbe.sentinels[]` 多实例 registry 与每个 sentinel 管理 YAML 的引用图。
- 常驻 TypeScript 单 Pod wrapper 服务、scheduler、scenario runner、PVC/SQLite index、health、metrics、maintenance API 和 dashboard。
- `sentinel plan|apply|status|validate|report|maintenance` 与 `sentinel image|control-plane` 等受控 CLI 入口。
- 发布流水 maintenance start/stop、quick verify、targetValidation、GitOps/Argo/git-mirror closeout 和 public exposure 验证。
- Dashboard 信息架构、规范化 API、前端组件分层、自动刷新、筛选、深链和 trace/turn 两层阅读视图。
- `workbench-dsflash-go-tool-call-10x` 生产 canary 和 24 小时 dry-run 收口。
- `workbench-auth-session-switch-2users` 账号切换链路哨兵，覆盖账号 A/B 登录、登出、session 列表和 session 切换命令链。
- Secret、prompt、provider payload、artifact 和 dashboard 的脱敏边界。
### 2.3 范围外
@@ -56,6 +58,7 @@ Web哨兵必须遵循 UniDesk YAML-first ops。目标 node/lane、public origin
- API path、错误 envelope、route policy 和用户身份语义归 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)。
- 第一阶段不交付分布式压测；loadtest 只保留同镜像、同 wrapper 的配置和命令扩展点。
- in-cluster 哨兵不是外部公网监控节点。若后续需要真正外网用户路径监控，应另行定义外部或边缘哨兵，不把当前服务伪装成外部观测点。
- 多实例 Web 哨兵不得用一个 Pod、一个 PVC 或一个 SQLite index 伪装隔离。共享 dashboard domain 可以按 route prefix 暴露，但 runtime Deployment、Service、PVC、SQLite、GitOps path、Argo Application、metrics label 和 report index 必须按 sentinel id 独立。
- SQLite index、dashboard、metrics 和 maintenance 状态不得替代 `samples.jsonl`、`control.jsonl`、network/artifact JSONL 或 `analysis/report.json` 成为探针事实源。
- Dashboard 不负责修复 Workbench projection、trace timing、runner/envreuse 或 git mirror 慢路径；它只把 observe/analyze 已采集事实组织成可读的值守和分析入口。
@@ -64,6 +67,10 @@ Web哨兵必须遵循 UniDesk YAML-first ops。目标 node/lane、public origin
| 术语 | 定义 |
| --- | --- |
| Web哨兵 | 常驻 wrapper/orchestrator，按 YAML 调度现有 `web-probe observe` CLI，对 HWLAB Web public origin 做持续 canary、分析、展示和发布联动。 |
| sentinel registry | node/lane root YAML 下的 `observability.webProbe.sentinels[]`，只声明 sentinel id、enabled 和管理 configRef。 |
| sentinel 管理 YAML | registry 项指向的 owning YAML，声明单个 sentinel 的 id、enabled、mode 和 runtime/workflow/promptSet/reportViews/publicExposure/cicd/secrets configRefs。 |
| sentinel id | 多实例哨兵的稳定小写标识，必须进入 CLI `--sentinel`、Kubernetes/GitOps label、metrics label、report index 和 dashboard route。 |
| 账号切换哨兵 | `workbench-auth-session-switch-2users`，使用两组 YAML Secret sourceRef 驱动登录、登出、session 列表和 session 切换链路。 |
| observe runner | 现有 `web-probe observe start` 启动的浏览器采样器；它写入 DOM、network、control、screenshot、artifact 等 JSONL。 |
| observe artifact | `web-probe observe` 产生的 stateDir、JSONL、截图、analysis/report.md 和 analysis/report.json，是哨兵报告的事实来源。 |
| CLI wrapper adapter | 服务与 CLI 共享的命令适配层，把 start/status/command/collect/analyze 表达为稳定调用，不复制 runner/analyzer 实现。 |
@@ -106,25 +113,28 @@ Web哨兵必须遵循 UniDesk YAML-first ops。目标 node/lane、public origin
| PJ2026-0106050807 | 安全隔离 | 本规格 6.7 | Secret/prompt/provider redaction、NetworkPolicy、public dashboard auth | 用户管理、平台运维 | 安全 closeout |
| PJ2026-0106050808 | 代码引用 | 本规格 6.8 | SPEC 头部标注和生成/配置追溯 | 规格治理 | 后续 PR 审计 |
| PJ2026-0106050809 | Dashboard工作台 | 本规格 6.9 | overview、runs、findings、run detail、trace-frame viewer、前端分层 | 报告视图、常驻服务、Workbench性能 | 平台值守和问题分析 |
| PJ2026-0106050810 | 多实例与账号切换 | 本规格 6.10 | sentinel registry、实例隔离、账号切换 command、route prefix 和 report label | YAML配置、Wrapper边界、安全隔离 | 多哨兵巡检、账号链路值守 |
### 5.1 目标架构图
```mermaid
flowchart LR
subgraph Config[UniDesk YAML source of truth]
Lane[hwlab-node-lanes.yaml<br/>sentinel enabled/configRefs]
Lane[hwlab-node-lanes.yaml<br/>sentinels registry]
Mgmt[sentinel management YAML]
Runtime[runtime owning YAML]
Scenario[scenario owning YAML]
Prompts[synthetic prompt YAML]
Report[report view YAML]
Exposure[publicExposure YAML]
Secrets[Secret sourceRef YAML]
Lane --> Runtime
Lane --> Scenario
Lane --> Prompts
Lane --> Report
Lane --> Exposure
Lane --> Secrets
Lane --> Mgmt
Mgmt --> Runtime
Mgmt --> Scenario
Mgmt --> Prompts
Mgmt --> Report
Mgmt --> Exposure
Mgmt --> Secrets
end
subgraph Sentinel[Web哨兵 Pod]
@@ -171,8 +181,9 @@ flowchart LR
```mermaid
flowchart TD
Root[config/hwlab-node-lanes.yaml<br/>lanes.v03.targets.D601.observability.webProbe.sentinel] --> Enabled[enabled]
Root --> Refs[configRefs]
Root[config/hwlab-node-lanes.yaml<br/>lanes.v03.targets.D601.observability.webProbe.sentinels[]] --> Entry[id/enabled/configRef]
Entry --> Mgmt[sentinel management YAML#sentinel]
Mgmt --> Refs[configRefs]
Refs --> Runtime[runtime.d601-v03.yaml#sentinel.runtime]
Refs --> Scenarios[scenarios.workbench.yaml#sentinel.scenarios]
Refs --> PromptSets[prompt-set.dsflash-go.yaml#sentinel.promptSet]
@@ -440,11 +451,11 @@ Web哨兵必须只编排现有顶层 `web-probe observe start/status/command/col
| --- | --- | --- | --- |
| OPS-SENTINEL-REQ-002 | YAML配置 | PJ2026-0106050802 YAML配置 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[公开入口](PJ2026-010604-public-entry.md)、[源码同步](PJ2026-010602-source-sync.md) |
Web哨兵配置必须通过 node/lane root YAML 的 `observability.webProbe.sentinel.enabled/configRefs` 进入，再引用 runtime、scenario、promptSet、reportView、publicExposure、CI/CD 和 Secret owning YAML。root YAML 不得承载所有 runtime/scenario/report/Secret 数值，也不得生成合并后的超级配置作为第二 source of truth。
Web哨兵 legacy 单实例配置可通过 node/lane root YAML 的 `observability.webProbe.sentinel.enabled/configRefs` 进入；多实例配置必须通过 `observability.webProbe.sentinels[]` registry 进入。registry 项只能声明 `id`、`enabled` 和 `configRef`，再由 sentinel 管理 YAML 引用 runtime、workflow/scenario、promptSet、reportView、publicExposure、CI/CD 和 Secret owning YAML。root YAML 不得承载所有 runtime/scenario/report/Secret 数值，也不得生成合并后的超级配置作为第二 source of truth。
parser 只负责解析 `path/to/file.yaml#object.path` 或规格确认的等价引用，校验文件存在、路径存在、字段形状、类型、枚举键名、必填字段和重复事实冲突。缺失字段应报告 YAML path 和下一步 drill-down；不得用代码默认值补 namespace、image、cadence、timeout、threshold、profile、Secret、public URL、report view 或 retention。
parser 只负责解析 `path/to/file.yaml#object.path` 或规格确认的等价引用，校验文件存在、路径存在、字段形状、类型、枚举键名、必填字段和重复事实冲突。registry id 与 sentinel 管理 YAML 内的 id 必须一致；多实例 registry 下的非 config 操作必须显式选择 `--sentinel <id>`，避免误操作默认实例。缺失字段应报告 YAML path 和下一步 drill-down；不得用代码默认值补 namespace、image、cadence、timeout、threshold、profile、Secret、public URL、report view 或 retention。
`sentinel plan/status` 必须输出 redacted 配置引用图：每个 ref 的文件、path、presence、摘要 hash、缺失字段、冲突字段和下一步命令。默认输出不得 dump 完整展开 YAML、Secret 值、prompt 原文或 provider payload。
`sentinel plan/status` 必须输出 redacted 配置引用图：无 `--sentinel` 且存在多个实例时输出 registry 表和逐实例 drill-down；指定实例时输出该实例每个 ref 的文件、path、presence、摘要 hash、缺失字段、冲突字段和下一步命令。默认输出不得 dump 完整展开 YAML、Secret 值、prompt 原文或 provider payload。
### 6.3 OPS-SENTINEL-REQ-003 常驻服务和 artifact 索引
@@ -494,7 +505,7 @@ HWLAB runtime 发布 Pipeline 应在 Argo sync 前调用当前哨兵 `maintenanc
哨兵服务不可用、首次安装未完成或配置未就绪时，CI/CD 必须结构化失败并输出缺失项、恢复建议和可重试命令；不得自动回退到原纯客户端 CLI、裸 Playwright、私有 API、read-side repair、reload 循环或 session repair 形成第二执行路径。人工排障可以显式运行原 `web-probe observe start/status/command/collect/analyze`，但不能被 targetValidation 当作自动通过证据。
`sentinel validate --quick-verify --confirm --wait`、maintenance stop quick verify 和 control-plane targetValidation 的确认等待总耗时超过 120s 时，必须输出 warning，并在 quick verify run 摘要中记录可见警告。warning 文案必须指向严重超时和下一步调查方向：env-reuse、git mirror、source build path、运行路径和当前 wait 阶段；不得通过调大 timeout、减少业务轮次或 fallback 到第二执行路径来消除红灯。
`sentinel validate --quick-verify --confirm --wait`、maintenance stop quick verify 和 control-plane targetValidation 的确认等待总耗时超过 120s 时，必须输出 warning，并在 quick verify run 摘要中记录可见警告。计时超限本身只作为非阻塞告警；只有真正影响 Code Agent 多轮业务链路、submit/command 执行、trace/final 可见性或 session 连续性的失败才构成 targetValidation blocker。control-plane publish/build 等非业务等待可通过 YAML 将确认等待预算放宽到 300s；不得通过减少业务轮次、吞掉 submit 失败、fallback 到第二执行路径或读侧 repair 来消除红灯。
### 6.6 OPS-SENTINEL-REQ-006 dsflash-go 十轮 canary
@@ -564,6 +575,24 @@ Dashboard 自动刷新只能读取 bounded API，不得发送 `observe command`
P8 中文运维页面必须以中文为默认用户可见语言：主标题、状态、筛选、运行历史、finding 分组、run detail、trace-frame、Final Response、空态、错误态、自动刷新和下一步动作均使用中文。原始英文 code、status 枚举、CLI 命令和 report SHA 可作为机器对照保留，但不得要求用户阅读英文 finding 才能判断 HWLAB 是否可用、卡在哪一层、下一步运行什么命令。
### 6.10 OPS-SENTINEL-REQ-010 多实例巡检与账号切换链路
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-SENTINEL-REQ-010 | 多实例与账号切换 | PJ2026-0106050810 多实例与账号切换 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[用户管理](PJ2026-0105-user-management.md)、[公开入口](PJ2026-010604-public-entry.md) |
Web 哨兵多实例必须以 node/lane root YAML 的 `observability.webProbe.sentinels[]` 为唯一 registry。每个 registry 项必须通过 `configRef` 指向独立 sentinel 管理 YAML，管理 YAML 再声明 runtime、workflow/scenario、promptSet、reportViews、publicExposure、cicd 和 secrets configRefs。legacy `observability.webProbe.sentinel` 只能作为单实例兼容入口；当同一 node/lane 存在多个 sentinel 时，除 `plan/status` registry 总览外，image、control-plane、validate、maintenance、report 和服务启动都必须显式携带 `--sentinel <id>`。
每个 sentinel 必须拥有独立的 Deployment、ServiceAccount、Service、PVC、SQLite path、GitOps path、Argo Application、FRP Secret/Deployment、metrics label、report index namespace 和 dashboard/report route label。不同 sentinel 可以共享同一 public hostname，但必须通过 YAML `routePrefix` 或等价 publicExposure 声明区分路径；不得共享同一个 PVC/SQLite 后再用 scenario id 伪装实例隔离。
`workbench-dsflash-go-tool-call-10x` 是保留的生产 canary，迁移到多实例 registry 后其 observe/analyze、report view、dashboard root 和 targetValidation 语义不得回退。迁移 closeout 必须证明旧实例 `sentinel plan --sentinel workbench-dsflash-go-tool-call-10x` 仍能解析原 runtime/scenario/prompt/report/publicExposure/cicd/secrets 引用。
`workbench-auth-session-switch-2users` 是账号切换链路哨兵。账号 A/B 的用户名、密码或 token 只能来自 Secret sourceRef 和 targetKey；CLI、服务日志、dashboard、report 和 issue evidence 只能展示 account id、sourcePurpose、presence、fingerprint 或 redacted 摘要。workflow 必须通过同一 `web-probe observe command` 控制队列支持 `loginAccount`、`logout`、`listSessions` 和 `switchSessions` 命令；submit 或命令失败必须作为结构化失败解决和上报，不能只写到备注里。
账号切换 report view 至少要给出账号 A/B login/logout 成败、session 列表可见性、切换前后 active session/account id、trace/final 可见性、blocked finding 和同一 observer/run/report SHA。`auth-session-switch-summary` 视图只读取已有 artifact/report/index，不重新访问 Workbench、不保存第二套截图、不打印账号凭据。
多实例 public exposure 复测必须通过受控 `web-probe screenshot` 或沉淀后的 command 远程截图能力完成，并把 PNG 保存到调用者 `/tmp` 下用于人工布局分析。修复 dashboard 布局问题后，复测截图必须覆盖 root dashboard 和至少一个 sentinel route prefix。
## 7. 过程控制
Web哨兵架构执行 issue 为 [#883](https://github.com/pikasTech/unidesk/issues/883)。阶段跟踪 issue 为 P0 [#885](https://github.com/pikasTech/unidesk/issues/885)、P1 [#886](https://github.com/pikasTech/unidesk/issues/886)、P2 [#887](https://github.com/pikasTech/unidesk/issues/887)、P3 [#888](https://github.com/pikasTech/unidesk/issues/888)、P4 [#889](https://github.com/pikasTech/unidesk/issues/889)、P5 [#890](https://github.com/pikasTech/unidesk/issues/890) 和 P6 [#891](https://github.com/pikasTech/unidesk/issues/891)。
@@ -577,3 +606,5 @@ P7 P6 收口必须区分 public dashboard validation 与 targetValidation quick
P8 哨兵恢复执行 issue 为 [#971](https://github.com/pikasTech/unidesk/issues/971)。P8 closeout 必须回写：SPEC P8 引用、120s warning 证据、`quick-verify-no-business-turn` 或等价业务触达证据、`browser-timeout` 分类修正、中文运维页面验证、`monitor.pikapython.com` 公网入口验证、k3s 内部 Service DNS quick verify 路径、D601/v03 用户入口 smoke 结果，以及仍未解除的真实业务 blocker 是否已单独拆出。
P8-P8 起，targetValidation 的 availability blocker 与 Workbench timing 架构治理必须分层。若同一 trace 在 terminal 前最后一帧仍为 running，随后 terminal commit 的 sealed `durationMs` 把可见 `totalElapsed` 小幅校正到更短值，且 drop 不超过 YAML `turnTimingSampleSlackSeconds`、final response 与完成行均已可见，则该现象作为 terminal-boundary timing correction 证据保留，不生成 `turn-timing-total-elapsed-decrease` red blocker。归零、running/running 下降、terminal 后增长、完成耗时与卡片耗时超出 slack、trace 乱序和完成行非最后仍保持 red；根因治理继续归 [HWLAB #2055](https://github.com/pikasTech/HWLAB/issues/2055) 和 [HWLAB #2125](https://github.com/pikasTech/HWLAB/issues/2125)，不得在 UI、CLI renderer 或 analyzer 中做读侧 repair。
P9 多实例巡检与账号切换链路执行 issue 为 [#1017](https://github.com/pikasTech/unidesk/issues/1017)。P9 closeout 必须回写：SPEC P9 引用、registry 和两条 sentinel drill-down、旧 dsflash canary 迁移验证、账号切换 workflow/Secret sourceRef 验证、独立 Deployment/PVC/Service/SQLite/GitOps/Argo/public route prefix 证据、submit/command 失败处理、非阻塞计时告警证据、远程 PNG 截图布局复测，以及未完成阶段是否已拆出后续 issue。