Pulse Operational Trust:让告警、Patrol 与受治理动作共享同一套证据与生命周期模型
Pulse Operational Trust:让告警、Patrol 与受治理动作共享同一套证据与生命周期模型
Operational Trust 是 Pulse v6 中统一回答运维信任问题的共享模型:它定义了哪些问题需要现在处理、支撑结论的证据是什么、受影响资源是否有可用的恢复保护、生命周期发生了什么变化,以及 Pulse 提供的窄范围动作是否通过了新鲜证据的验证。本文基于 docs/OPERATIONAL_TRUST.md(其镜像副本位于 frontend-modern/public/docs/OPERATIONAL_TRUST.md)逐章展开,并结合 internal/operationaltrust/ 包中的契约定义与 internal/api/ 中的路由实现,说明这套模型的状态机规则、证据封包结构、保护姿态评估、Patrol 工作流、API 授权边界与升级迁移流程,帮助你在部署、排障和集成时准确理解 Pulse 的运营信任边界。
一、五个运维问题与"单一可写生命周期"
Operational Trust 的设计目标是让 Pulse 的所有运营视图回答同一组问题,而不是各自维护一套"真相":
- 现在什么需要关注(What needs attention now)?
- 什么证据支撑这个结论(What evidence supports that conclusion)?
- 受影响资源是否受可用的恢复历史保护(Is the affected resource protected by usable recovery history)?
- 问题生命周期发生了什么变化(What changed in the issue lifecycle)?
- Pulse 是否能提供一个窄范围动作,并且新鲜证据是否验证了其结果(Can Pulse offer a narrow action, and did fresh evidence verify its result)?
文档给出的核心约束是:告警(Alerts)、Patrol 关注队列(attention queue)、导航计数、附着的可用性检查、通知、保护姿态(protection posture)和受治理动作(governed actions),全部是对同一批 canonical 记录的投影(projection)。任何一个视图都不拥有第二套可写的生命周期——也就是说,你不可能在"告警列表"里改一个状态、却在"Patrol 队列"里看到另一个状态。
这一点在源码结构上得到印证:internal/operationaltrust/contracts.go 的包注释明确写着"Package operationaltrust defines the shared evidence, lifecycle, and notification-link contracts used by Pulse's operational read models",即整个包只定义共享契约,而不承载任何单一视图的私有状态。
二、生命周期状态:八个状态的语义与硬规则
Operational Trust 定义了八个生命周期状态,每个状态都有明确的运维含义:
| 状态 | 运维含义 |
|---|---|
observing |
证据正在被确认。这还不是活跃工作项。 |
open |
当前证据支持存在一个运维问题。 |
acknowledged |
有运维人员已经看到该问题。问题并未解决。 |
suppressed |
该问题被临时移出活跃关注范围,必须携带操作者(actor)、原因(reason)和有界的过期时间(expiry)。 |
resolving |
存在恢复证据,但检测器尚未确认健康已恢复。 |
resolved |
新鲜(fresh)的检测器证据确认问题不再成立。 |
stale |
先前问题仍然相关,但其采集证据已不再新鲜。 |
unknown |
权限、完整性、provider 状态或身份阻止了更强的结论。 |
这八个状态在源码中由 OperationalState 类型与 valid() 校验封闭枚举(见 contracts.go#L303-L330),任何不在该集合内的状态值都会被 OperationalRecord.Validate() 拒绝。
关键硬规则
文档强调了几条容易被违反的语义,它们同样是系统的不变式:
- 缺失的观测永远不会解决一个 open 记录。 采集器断连会把现有工作项移入
stale;权限或 provider 不确定性会把它移入unknown。一个成功的动作结果也不会关闭记录——只有新鲜的检测器证据才能确认恢复。 - 确认(acknowledgement)是可逆的,且不会降低"活跃问题"的事实地位。
- 抑制(suppression)必须携带非空原因,且过期时间不得超过未来 30 天。Patrol UI 默认提供更短的 1 小时、24 小时、7 天选项。
这些规则在代码层面有对应的实现与测试:
- 30 天抑制上限:internal/api/attention_mutations.go 中定义了
maxAttentionSuppressionDuration = 30 * 24 * time.Hour,抑制请求在超出该窗口时返回invalid_attention_suppression错误,错误消息即为"Suppression requires a reason and an expiry within 30 days."。 - 状态与附属结构的一致性:
OperationalRecord.Validate()要求acknowledged状态必须携带Acknowledgement结构(含at、by操作者),suppressed必须携带Suppression结构(含at、by、非空reason、且expiresAt晚于抑制时间),resolved必须携带resolvedAt且evidenceIds非空——"resolved state requires decisive evidence"(见 contracts.go#L431-L485)。非 resolved 状态反过来不允许携带resolvedAt,防止"假解决"。 - 状态迁移矩阵:
LifecycleTransition通过TransitionCause封闭了合法迁移路径(见 contracts.go#L487-L649):
| 迁移原因(cause) | 允许的迁移约束 |
|---|---|
detector_decision |
必须进入 open,且必须携带证据 ID |
acknowledgement |
必须进入 acknowledged |
unacknowledgement |
必须从 acknowledged 回到 open |
suppression |
必须进入 suppressed |
suppression_expired |
必须从 suppressed 回到 open |
recovery_evidence |
必须进入 resolving 或 resolved,且必须携带证据 |
ownership_transferred |
必须进入 resolved 且携带证据;语义上表示该条件已被另一条记录接管(例如节点指标被关联的 Pulse agent 接管),并非观测到问题清除 |
collection_stale |
必须进入 stale |
collection_unknown |
必须进入 unknown |
注意 ownership_transferred 这条迁移的注释:它明确说明"条件并未被观测到清除,因此不算恢复"——这与"只有新鲜检测器证据才能确认恢复"的硬规则一致,避免把"别的组件接管了监控"误报为"问题解决了"。
三、证据封包(Evidence Envelope):每条结论都必须可追溯
封包字段
文档要求每个证据封包(evidence envelope)记录:
- 一个稳定的不透明证据 ID(stable opaque evidence ID);
- provider、collector 以及可选的 provider instance;
- 要么一个 canonical 资源 ID,要么一个未解析的 provider 作用域引用(二选一);
- 观测时间(observation)、摄取时间(ingestion)和可选的有效期(validity)时间;
- 完整性(completeness)、置信度(confidence)与权限(permission)状态;
- 一个可选的有界载荷引用(bounded payload reference)和身份关联证明(identity-correlation proof)。
对应的 Go 结构是 EvidenceEnvelope:
type EvidenceEnvelope struct {
ID string `json:"id"`
Source EvidenceSource `json:"source"` // provider + collector + 可选 instance
Subject EvidenceSubject `json:"subject"` // resourceId 与 providerRef 二选一
ObservedAt time.Time `json:"observedAt"`
IngestedAt time.Time `json:"ingestedAt"`
ValidUntil *time.Time `json:"validUntil,omitempty"`
Completeness EvidenceCompleteness `json:"completeness"` // complete | partial | unavailable
Confidence EvidenceConfidence `json:"confidence"` // confirmed | inferred | unknown
Reason *EvidenceReason `json:"reason,omitempty"`
Permissions EvidencePermissions `json:"permissions"` // sufficient | partial | denied | unknown
PayloadRef *EvidencePayloadRef `json:"payloadRef,omitempty"`
Correlation *IdentityCorrelation `json:"correlation,omitempty"`
}
EvidenceSubject.Validate() 强制"恰好一个 resourceId 或 providerRef"的互斥约束;若使用 providerRef,则必须提供 providerScope。
稳定 ID 的生成方式
NewEvidenceID()(contracts.go#L204-L233)以 provider、collector、instance、资源/provider 引用、UTC 观测时间与源观测 ID 为输入,经长度前缀编码后取 SHA-256 的前 16 字节,生成形如 evidence_<32位hex> 的确定性 ID。同样的 stableID 机制也被迁移记录(transition_...)和通知(notification_...)的 ID 复用,保证同一事实重复计算时得到同一 ID——这是"多个视图投影同一记录"能够成立的底层基础。
fresh / complete / confirmed 是三个独立维度
文档特别强调 fresh、complete、confirmed 是相互独立的维度:partial、denied、unavailable、stale、inferred、ambiguous、unknown 的证据都被显式表示,且永远不会被客户端升级为 healthy。
源码中的验证规则进一步强化了这一点(见 contracts.go#L235-L301):
- 只要 completeness 不是
complete、confidence 不是confirmed、或 permissions 不是sufficient三者中任一,封包就必须携带一个带 code 的EvidenceReason("limited evidence requires a typed reason"); inferred(推断的)证据必须携带IdentityCorrelation证明,且IdentityCorrelation.Validate()强制CandidateCount == 1——身份关联必须恰好命中一个候选,多候选即视为非法;- 未解析(仅有 providerRef)的证据不允许声称存在已解析的身份关联;
- 新鲜度由
FreshnessAt(at)判定:ValidUntil之前为fresh,之后为stale,缺少ValidUntil时返回unknown而不是默认fresh。
证据明细端点的 410 语义
Patrol 关注详情响应包含正常运维旅程所需的保留封包;授权客户端可以通过证据端点请求某一个精确的封包明细。如果记录仍然链接该证据 ID,但其有界明细已过期,端点返回 410 attention_evidence_detail_expired——它不假装证据从未存在过。这是一个典型的"保留身份、释放载荷"的有界保留策略:链接与 ID 永久可读,而受 TTL 保护的明细过期后以 410 Gone 显式告知,而不是 404 或静默空值。
四、保护姿态(Protection Posture)
保护姿态在服务端按 canonical subject 资源逐条评估,只有四个取值:
| 姿态 | 含义 |
|---|---|
protected |
当前可用的保护满足策略。 |
attention |
保护存在,但新鲜度、验证结果或 provider 结果需要关注。 |
unprotected |
足够证据确认所需的保护缺失。 |
unknown |
身份、历史、权限或采集覆盖不足以支持更强的主张。 |
响应会解释结论、保留 provider 特定的状态,并链接涉及的恢复(recovery)与仓库(repository)资源。文档还给出了一条明确的客户端行为约束:平台表格按最多 200 个资源 ID 一批拉取姿态,不允许逐行发起一次网络请求——这既约束了前端实现,也防止了大规模舰队场景下的 N+1 请求风暴。
从 internal/operationaltrust/metrics.go 可以看到,姿态评估本身也是可观测的:ObserveProtectionEvaluation 的标签闭集恰好是 {protected, attention, unprotected, unknown},评估失败则由 protection_posture_evaluation_failures_total 按 {invalid_policy, invalid_posture, store, provider} 归因——这与上文"评估失败不会假装成功"的语义呼应。
五、可用性检查的附着与身份边界
可用性检查(availability check)只有满足以下两种情况之一才会附着到一个已存在的统一资源(unified resource)上:
- 显式链接(explicit link)可以解析;或
- 身份关联(identity correlation)恰好产生一个候选。
附着关系携带一个稳定的 relationship ID 与支持它的证据 ID。文档明确了三层身份边界:
- 每个配置的检查,包括已附着的检查,仍然是 source 拥有的清单资源(source-owned inventory resource);
- 关联投影只是把有界的 facet 投射到匹配的平台行与详情上,永远不会替换检查自身的身份,也不会把检查的事故/服务身份复制进机器(machine);
- 有歧义(ambiguous)和未解析(unresolved)的检查保持可见,并带有类型化的关联状态。
时间维度上:可用性成功是有时间界限的——一条过期的成功观测是 stale,而不是 healthy。可用性失败则与其余检测器一样,进入同一套告警生命周期和 Patrol 关注队列。也就是说,可用性检查没有"特权通道",它的失败走的是与所有检测器相同的 canonical 生命周期。
六、Patrol 工作流与受治理动作
标准运维路径
文档给出的正常操作员路径是:
- 从 monitor shell 打开 Patrol;
- 审阅按紧急度排序的活跃队列(urgency-ordered active queue);
- 选择一个条目,查看影响(impact)、下一步(next step)、资源、证据、保护姿态与生命周期详情;
- 确认(acknowledge)它,或携带原因与过期时间临时抑制(suppress)它;
- 如果提供了合格的 Pulse Pro 动作,审阅服务端拥有的计划(server-owned plan)、批准、执行,并分别检查执行(execution)与验证(verification)。
第 5 步中"分别检查执行与验证"是关键设计:动作执行成功不等于问题解决,验证是独立的证据链。
Calm 状态的严格条件
"Calm(平静)"状态只在三个条件同时满足时出现:生命周期评估成功、覆盖(coverage)是最新的、且不存在任何活跃条目。读取失败或部分覆盖永远不能变成 calm 主张——这与证据模型中"unknown 不是 healthy"的原则一脉相承。
第一个受治理动作:Docker 容器重启
文档明确了首个受治理动作的资格门槛:
- 只对唯一标识(uniquely identified)的容器提供;
- 必须有新鲜且已确认的不健康证据(fresh confirmed unhealthy evidence);
- 必须有声明的执行器就绪状态(declared executor readiness);
- 必须持有所需的授权 scope;
- 必须持有活跃的
ai_autofixentitlement。
动作框架负责:计划哈希(plan hashing)、批准、幂等执行、持久审计、重启对账(restart reconciliation)与验证。ai_autofix 能力键的归属在 docs/PULSE_PRO.md 与 docs/AI_AUTONOMY.md 中有配套说明:ai_autofix 由 Pro 及以上层级提供,未获得该能力时,Patrol 自治行为在运行时会被钳制到 monitor 模式。执行与验证的实际代码落在 internal/api/docker_container_action_executor.go 与 internal/api/attention_actions.go 等文件中,动作的决策、执行、详情与审计统一走 /api/actions。
七、API 与授权
读路由(要求 monitoring:read)
GET /api/ai/patrol/attention
GET /api/ai/patrol/attention/summary
GET /api/ai/patrol/attention/{id}
GET /api/ai/patrol/attention/{id}/evidence/{evidenceId}
生命周期变更(要求 monitoring:write)
POST /api/ai/patrol/attention/{id}/acknowledge
POST /api/ai/patrol/attention/{id}/unacknowledge
POST /api/ai/patrol/attention/{id}/suppress
POST /api/ai/patrol/attention/{id}/unsuppress
抑制(suppress)的请求体:
{
"reason": "Planned host maintenance",
"expiresAt": "2026-07-20T08:00:00Z"
}
服务端校验(见 internal/api/attention_mutations.go):reason 非空、expiresAt 必须在 30 天窗口内,否则返回 invalid_attention_suppression。
动作规划
为已提供的重启动作做规划(planning),要求 canonical 动作 API 强制的动作 scope 加上活跃的 ai_autofix entitlement:
POST /api/ai/patrol/attention/{id}/actions/restart/plan
动作的决策、执行、详情与审计使用 /api/actions。路由的注册与鉴权入口在 internal/api/attention_handlers.go、internal/api/attention_mutations.go 中;更完整的接口契约另见 docs/API.md。
不透明 ID 与路径转义
文档强调一个容易被集成方踩坑的细节:所有 ID 都是不透明的,客户端必须对运营记录 ID 与证据 ID 做路径转义,因为 canonical ID 可能包含 /、: 以及 provider 特定的片段。换言之,ID 是"看起来像 token 的字符串",不能按路径段或命名空间做解析假设。
八、Metrics:低基数、闭集标签
/metrics 监听器在 pulse_operational_trust_* 前缀下暴露 Operational Trust 的计数器与直方图。标签使用封闭的低基数词表;资源 ID、证据 ID、provider instance 名、操作者、目标 ID 永远不出现在标签中。这一点在 internal/operationaltrust/metrics.go#L11-L13 的注释中被再次声明为设计原则。
从源码可以列出完整的指标清单:
| 指标 | 类型 | 标签(闭集) |
|---|---|---|
pulse_operational_trust_observation_to_open_seconds |
Histogram | 首次 canonical 观测到 open 记录的耗时(桶:0.01s–60s) |
pulse_operational_trust_open_to_notification_enqueue_seconds |
Histogram | open 迁移到通知入队的耗时 |
pulse_operational_trust_evidence_observations_total |
Counter | source(agent/docker/pbs/pve/truenas/... 闭集)、state(current/partial/stale/denied/... 闭集) |
pulse_operational_trust_identity_correlations_total |
Counter | outcome:attached / standalone / ambiguous / unresolved |
pulse_operational_trust_protection_posture_evaluations_total |
Counter | state:protected / attention / unprotected / unknown |
pulse_operational_trust_protection_posture_evaluation_failures_total |
Counter | reason:invalid_policy / invalid_posture / store / provider |
pulse_operational_trust_notification_delivery_total |
Counter | outcome:queued / retry / sent / failed / dead_letter / cancelled |
pulse_operational_trust_active_count_mismatch_total |
Counter | 无标签 |
pulse_operational_trust_action_offers_total |
Counter | eligibility:eligible / ineligible / unknown |
pulse_operational_trust_action_verification_total |
Counter | outcome:pending / confirmed / contradicted / inconclusive / timed_out / not_attempted |
实现上的兜底机制是 boundedMetricLabel():任何不在闭集内的标签值一律归一为 other,从机制上杜绝了高基数标签泄漏。
文档建议关注以下告警信号:
active_count_mismatch_total持续增长(canonical 活跃计数与活跃关注投影之间出现漂移);- 通知的
failed或dead_letter结果; - stale、unavailable、denied 或 partial 证据观测增长;
- 身份关联出现
ambiguous或unresolved结果; - 动作验证出现
contradicted、inconclusive或timed_out结果。
九、升级与兼容性
Operational Trust 的迁移是增量式(additive)的:既有的告警、通知、恢复、关系、可用性与动作记录,要么在读取时归一化,要么在其所属存储中迁移。为兼容旧客户端,读侧的兼容字段在需要处仍然受支持;但新写入只走 canonical 的生命周期、恢复、统一资源、通知与动作所有者,不再有旁路。
Pulse Mobile 的主待办(primary backlog)使用 /api/ai/patrol/attention,并保留运营记录、证据与动作验证的身份;旧的 finding 形态如今只是一个本地显示适配器(local display adapter),不再是可写的真相来源。
升级前检查清单
- 备份 Pulse 数据目录;
- 确认 v6 进程能够写入其告警、通知、恢复与动作数据库目录;
- 确认受支持的客户端能够读取增量式(additive)JSON 字段;
- 如果推广期遥测是必需的,将 metrics 监听器暴露给受保护的 scraper;
- 在依赖动作提供(action offers)之前,验证 Pulse Pro entitlement 的连通性。
升级后检查清单
- 确认 Patrol 导航计数与活跃队列一致;
- 通过最深一层的证据与保护详情检查一个活跃条目;
- 对一个测试条目做 acknowledge 与 unacknowledge;
- 验证一个有界抑制在过期后回到活跃关注;
- 确认 stale 的采集保持可见,而不是被当作已解决;
- 演练通知的重试/死信监控;
- 如果使用 Pulse Pro 动作,完成一次 review / approve / run / verify 旅程。
迁移失败的回滚原则
如果迁移失败:停止升级后的进程,保留数据目录与日志,用升级前的数据备份恢复先前版本。不要删除生命周期、证据、通知、恢复或动作记录来强制启动——这与全文"缺失证据不等于恢复"的哲学一致:记录是审计与恢复的基础,宁可回滚版本,也不销毁证据。
十、小结与延伸阅读
Operational Trust 的价值在于把"告警"从一份列表升级为一条可审计的证据链:状态迁移必须声明 cause 与证据(LifecycleTransition),证据封包必须显式表示不完整与不确定(EvidenceEnvelope),恢复必须由新鲜检测器证据确认(recovery_evidence / detector_decision),动作结果必须由独立验证判定(action_verification_total)。对运维者,它给出了 Patrol 队列中每个条目可验证的下一步;对集成者,它给出了封闭的 API、scope、ID 语义与低基数指标契约。
延伸阅读路径:
- 契约文档本体:docs/OPERATIONAL_TRUST.md、frontend-modern/public/docs/OPERATIONAL_TRUST.md
- 契约与验证实现:internal/operationaltrust/contracts.go、internal/operationaltrust/metrics.go
- 契约行为测试:internal/operationaltrust/contracts_test.go
- API 处理与变更校验:internal/api/attention_handlers.go、internal/api/attention_mutations.go、internal/api/attention_evidence.go
- 接口与能力门控:docs/API.md、docs/PULSE_PRO.md、docs/AI_AUTONOMY.md