Pulse Operational Trust:让告警、Patrol 与受治理动作共享同一套证据与生命周期模型

原创2026-10-09 12:34:491,943 阅读
文章标签:可观测性运维后端

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 的所有运营视图回答同一组问题,而不是各自维护一套"真相":

  1. 现在什么需要关注(What needs attention now)?
  2. 什么证据支撑这个结论(What evidence supports that conclusion)?
  3. 受影响资源是否受可用的恢复历史保护(Is the affected resource protected by usable recovery history)?
  4. 问题生命周期发生了什么变化(What changed in the issue lifecycle)?
  5. 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 天选项。

这些规则在代码层面有对应的实现与测试:

  1. 30 天抑制上限:internal/api/attention_mutations.go 中定义了 maxAttentionSuppressionDuration = 30 * 24 * time.Hour,抑制请求在超出该窗口时返回 invalid_attention_suppression 错误,错误消息即为"Suppression requires a reason and an expiry within 30 days."。
  2. 状态与附属结构的一致性: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,防止"假解决"。
  3. 状态迁移矩阵: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)上:

  1. 显式链接(explicit link)可以解析;或
  2. 身份关联(identity correlation)恰好产生一个候选。

附着关系携带一个稳定的 relationship ID 与支持它的证据 ID。文档明确了三层身份边界:

  • 每个配置的检查,包括已附着的检查,仍然是 source 拥有的清单资源(source-owned inventory resource);
  • 关联投影只是把有界的 facet 投射到匹配的平台行与详情上,永远不会替换检查自身的身份,也不会把检查的事故/服务身份复制进机器(machine);
  • 有歧义(ambiguous)和未解析(unresolved)的检查保持可见,并带有类型化的关联状态。

时间维度上:可用性成功是有时间界限的——一条过期的成功观测是 stale,而不是 healthy。可用性失败则与其余检测器一样,进入同一套告警生命周期和 Patrol 关注队列。也就是说,可用性检查没有"特权通道",它的失败走的是与所有检测器相同的 canonical 生命周期。

六、Patrol 工作流与受治理动作

标准运维路径

文档给出的正常操作员路径是:

  1. 从 monitor shell 打开 Patrol;
  2. 审阅按紧急度排序的活跃队列(urgency-ordered active queue);
  3. 选择一个条目,查看影响(impact)、下一步(next step)、资源、证据、保护姿态与生命周期详情;
  4. 确认(acknowledge)它,或携带原因与过期时间临时抑制(suppress)它;
  5. 如果提供了合格的 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_autofix entitlement。

动作框架负责:计划哈希(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),不再是可写的真相来源。

升级前检查清单

  1. 备份 Pulse 数据目录;
  2. 确认 v6 进程能够写入其告警、通知、恢复与动作数据库目录;
  3. 确认受支持的客户端能够读取增量式(additive)JSON 字段;
  4. 如果推广期遥测是必需的,将 metrics 监听器暴露给受保护的 scraper;
  5. 在依赖动作提供(action offers)之前,验证 Pulse Pro entitlement 的连通性。

升级后检查清单

  1. 确认 Patrol 导航计数与活跃队列一致;
  2. 通过最深一层的证据与保护详情检查一个活跃条目;
  3. 对一个测试条目做 acknowledge 与 unacknowledge;
  4. 验证一个有界抑制在过期后回到活跃关注;
  5. 确认 stale 的采集保持可见,而不是被当作已解决;
  6. 演练通知的重试/死信监控;
  7. 如果使用 Pulse Pro 动作,完成一次 review / approve / run / verify 旅程。

迁移失败的回滚原则

如果迁移失败:停止升级后的进程,保留数据目录与日志,用升级前的数据备份恢复先前版本。不要删除生命周期、证据、通知、恢复或动作记录来强制启动——这与全文"缺失证据不等于恢复"的哲学一致:记录是审计与恢复的基础,宁可回滚版本,也不销毁证据。

十、小结与延伸阅读

Operational Trust 的价值在于把"告警"从一份列表升级为一条可审计的证据链:状态迁移必须声明 cause 与证据(LifecycleTransition),证据封包必须显式表示不完整与不确定(EvidenceEnvelope),恢复必须由新鲜检测器证据确认(recovery_evidence / detector_decision),动作结果必须由独立验证判定(action_verification_total)。对运维者,它给出了 Patrol 队列中每个条目可验证的下一步;对集成者,它给出了封闭的 API、scope、ID 语义与低基数指标契约。

延伸阅读路径:

登录后查看全文
Pulse