Pulse v6.4.0-rc.5 技术解析：API Token 原子化移除、确定性告警生命周期核心与通知投递可观测性

本文基于 RELEASE_NOTES_v6.4.0-rc.5.md 并结合仓库源码，深入剖析 Pulse v6.4.0-rc.5 候选版的三项核心改进：API Token 删除的持久化与回滚、覆盖多类告警的确定性转换核心（reducer）、以及通知投递状态与抑制原因的可观测化。读完本文，你将理解该候选版在告警生命周期与凭证管理上的架构性变化，掌握其实现原理、关键参数与升级前提。

v6.4.0-rc.5 是 Pulse 下一个 v6 minor 版本的发布候选（Release Candidate）。它使 API Token 的移除具备持久性（durable），让通知投递决策暴露得更加清晰，并将告警生命周期处理迁移到确定性转换核心之上。本文按该发布说明的骨架逐项展开，并用仓库源码印证每个结论。

一、版本定位与升级前提

作为候选发布版，v6.4.0-rc.5 面向有意验证下一 v6 minor 特性的操作者，而非默认升级目标：

• 稳定安装仍停留在 v6.3.2，除非操作者显式选择该候选版本；
• 现有配置保持有效，无需手动数据迁移；
• Pulse Mobile 不受影响：该版本改动的告警转换内部实现与浏览器投递证据不被 Mobile 消费，现有 Mobile、Relay、onboarding、pairing、push 与面向移动端的 API 契约均未变化，因此无需配套更新移动端；
• Windows Unified Agent 二进制已做校验和与分离签名校验，但未经 Authenticode 签名，Windows 可能显示 “Unknown Publisher” 警告。

升级路径上的关键限制（Windows Authenticode 签名不可用）也写入了 Known issues。

二、核心修复：API Token 删除的原子化持久化

发布说明中最重要的修复（对应 issue [#1783] 场景）是：

API-token deletion now persists the reduced inventory atomically and restores the complete prior live inventory if saving fails, instead of reporting success with inconsistent credentials.

也就是说，删除 Token 时若持久化失败，系统不再“谎报成功”，而是恢复完整的先前实时库存，避免出现**内存中已删、磁盘上未删（或相反）**的不一致凭证状态。

这一修复的工程含义可从 internal/config 包的测试印证：

• api_token_migration_atomic_test.go 中的 TestLoadAPITokensDurablyReducesRoleScopeExcess、TestSaveAPITokensRejectsNonCanonicalRoleAuthority 等用例，验证 Token 库存的每次缩减（迁移、删除）都要求先落到持久化层；
• TestLoadAPITokensRejectsUnpersistedCanonicalAuthorizationState 验证“未持久化的授权状态不得被采用”，失败时返回错误而非静默接受；
• 同文件中的 TestConfigWatcherPreservesLiveTokensWhenCanonicalMigrationCannotPersist 更加直接：当底层文件系统写入失败（writeError: errors.New("forced migration write failure")）时，watcher 必须保留完整的实时 Token 清单（require.Equal(t, []APITokenRecord{live}, cfg.APITokens)），且不得触发凭证变更回调（require.False(t, callbackCalled.Load(), "failed reload must not advertise a credential change")）——失败路径对上层完全透明，不会传播错误的凭证状态；
• persistence_save_errors_test.go 的 TestSaveComplexConfigs_ErrorPaths 覆盖保存失败、目录创建失败等错误路径。

从源码结构可以推断，该修复将“删除/缩减 Token 清单”实现为先持久化、后生效的提交语义：持久化失败即整体回滚到旧库存，从而杜绝“报告成功但凭证不一致”的后果。这属于凭证安全类修复，建议所有部署了多 Agent/多租户 Token 的实例重点回归验证。

三、确定性告警生命周期转换核心（reducer）

发布说明声称：Metric、availability、health、posture、backup、snapshot、storage、update 等告警共享一个确定性转换核心，并统一“钉住”（pinned）确认、恢复、确认（acknowledgement）与重新触发（re-fire）行为。这对应仓库中 internal/alerts/reducer 包——一个被 ALERT_ENGINE_EVOLUTION.md 称为“确定性告警转换核心”的纯函数层。

3.1 设计原则：纯函数 + 显式状态机

包注释（reducer.go 顶部）明确描述了设计契约：

reimplements the alert manager's transition semantics as a pure function over explicit state: no locks, no I/O, no wall clock — time enters only through the signal's ObservedAt.

即转换函数形如 next(state, signal, rules, clock) → (state', events)，无锁、无 I/O、无墙钟，时间只通过信号的 ObservedAt 进入。这正是它能与活跃 Manager 通过 parity harness 逐输入对拍的根本前提（internal/alerts/reducer_parity_*.go 系列测试）。

状态机只有三个显式状态：

• StatePending：值超过触发阈值但尚未满足持续/确认条件；
• StateFiring：告警已激活；
• 无状态即空闲（idle），不单独建模。

3.2 Metric 家族：迟滞、持续窗口与恢复延迟

对于度量阈值家族，MetricRule（reducer.go）中的关键参数包括：

参数	含义	默认/回退行为
Trigger	触发阈值，<= 0 表示规则禁用	禁用时清理所有 pending/firing 事件
Clear	迟滞释放阈值（hysteresis）	<= 0 时回退到 Trigger
Critical	显式 critical 阈值，用于升级严重级别	为空时采用派生升级（trigger+10，百分比类指标封顶 99）
DelaySeconds	超过触发阈值后需要持续多久才 fire	0 表示首次超阈值即 fire
CriticalBypassesDelay	critical 证据可跳过稳定窗口	仅影响无显式 Intent 的规则
RecoveryDelaySeconds	恢复前需连续处于 Clear 之下的时长	<= 0 表示立即迟滞恢复

实现上（ApplyMetric），低于触发阈值的观测若处于 pending 会整体重置持续计时（dip reset）；处于 firing 且落入 Clear..Trigger 迟滞带时保持 firing 但不刷新值；超过 Clear 且满足恢复延迟后才发出 EventResolved。

3.3 离散（确认）家族：确认数、恢复确认数与 Intent 门

对于 connectivity、powered-state、discrete-state 等“匹配/不匹配”类告警（discrete.go），核心参数为：

• DiscreteRule.Confirmations：连续匹配观测达到该数量才激活，<= 0 视为 1（Manager 侧 spec 默认：connectivity 为 3，powered-state 为 2）；
• DiscreteRule.RecoveryConfirmations：firing 后需要连续多少条非匹配观测才恢复，<= 1 表示首个非匹配观测即恢复（轮询驱动的离线路径默认 3，storage 为 2）；pending 状态始终在单条非匹配观测时清除；
• DiscreteRule.Intent：操作者意图门（见下）。

DiscreteIntent 只控制激活（已 firing 的告警永不被意图门抑制），支持 OperatorSuppressed（维护窗口、静默、预期离线等）、GraceSeconds（显式策略下的宽限期）、以及 backup-offline 延迟子策略（BackupEnabled/BackupActive/BackupPostGraceSeconds/BackupMaxDeferralSeconds）。

3.4 时间确定性与事件语义

• 普通路径下时间取自信号 ObservedAt；当提供单调进程时钟 RuntimeTick（RuntimeTickValid 置位）时，宽限期（grace）与恢复计时都按单调时钟累积，对挂起/NTP 跳变免疫；
• 事件类型枚举（EventType）：pending、pending_cleared、fired、refired、severity_changed、resolved；
• RefireRetention = 5 * time.Minute：已恢复事件在此窗口内被重新触发时，保留原事件的 StartedAt，下游按“同一事件”处理（不新增历史条目但照常通知）——这正是发布说明中“re-fire 行为被钉住”的实现；
• AckRetention = time.Hour：确认记录在事件恢复后保留一小时，窗口内的重新激活自动带确认状态，与 Manager 的 ack 记录保留策略对齐。

3.5 Manager 侧的接入：canonical 生命周期与 stateful 家族

internal/alerts/canonical_lifecycle.go 是 Manager 与 reducer 之间的接入层：

• evaluateCanonicalLifecycleAlert（离散/确认家族）：先解决意图上下文（evaluateIntentNoLock），将 DiscreteSignal/DiscreteRule 交给 m.core.ApplyDiscrete，再把 reducer 产出的事件合成为 evaluator 形状的 EvaluationResult 与 EvaluationTransition（pending/activated/recovered/severity_changed 等）。激活时从 incident.StartedAt 还原发生时间，并调用 preserveAlertState 保留已有确认/抑制等现场；
• evaluateCanonicalStatefulAlert（stateful 家族，如 backup 时间戳驱动类）：同样通过 ApplyDiscrete 驱动，并支持 StartTimeOverride、MessageBuilder，恢复仍处确认窗口内时保持原告警值与消息，不把健康读数投影到仍活跃的告警上；
• 两处都包含 SeedFiringIncident 的“收养”逻辑：当活跃告警存在而核心不知道时（guest 迁移、直接注入等），将其重建为 firing，保持 ack 现场（AckUser/AckTime）。

3.6 演进阶段与落地状态

ALERT_ENGINE_EVOLUTION.md 记录了该核心的落地过程：

• Phase 0（事件日志，纯增量）：不做生命周期语义变更；
• Phase 1（shadow mode）：reducer 与 Manager 并行运行，同一输入持续对拍差异；
• Phase 2（分家族切换，2026-08-27 完成）：四类 per-observation 转换家族——match-spec lifecycle（evaluateCanonicalLifecycleAlert）、legacy checkMetric、canonical metric threshold、stateful 家族——全部以 reducer core 为权威状态；旧的 offlineConfirmations、nodeOfflineCount、dockerOfflineCount 等跟踪 map 被删除，清理逻辑移入核心（如 PruneStalePending 清理失去观测的 pending 事件）；
• unified-incidents 批处理协调器被刻意排除在切换范围外（它是批对账家族而非单观测确认运行，firstSeen 记账本就身份正确）。

因此，v6.4.0-rc.5 中“多类告警共享确定性转换核心”是 Phase 1/2 演进的延续验证，而不是全新引入。相关行为的对拍保障见 reducer_parity_test.go、discrete_test.go。

四、通知投递可观测性：状态分类与抑制原因

发布说明的改进项之一是“更清晰的通知证据”：活跃告警展示投递状态，投递活动视图包含 held（被挂起）的通知及其抑制原因；另一修复项是“投递诊断区分 pending、sent、failed 与 suppressed 结果，操作者不再需要仅凭活跃告警推断投递结果”。

源码侧由 internal/alerts/notification_policy.go 提供支撑：

• 投递状态枚举（AlertDeliveryStatus*）：would_send、deferred、suppressed；
• 抑制原因枚举（AlertDeliveryReason*）覆盖 12 种：ready、acknowledged、snoozed、notifications_disabled、notifications_inactive、suppression_window、flapping、rate_limited、cooldown、quiet_hours、monitor_only、correlated_primary；
• AlertDeliveryDiagnosis 是只读投影（显式注明非变异：不派发回调、不推进 flapping/限流计数器），包含 status、reason、message、notificationsEnabled、cooldownMinutes、maxAlertsHour、recentAlertsInHour、flappingActive、nextEligibleAt、quietHoursReplayAt、suppressedUntil 等字段——操作者据此可以直接回答“这条告警为什么没通知我”；
• quiet-hours 相关元数据（quietHoursSuppressed、quietHoursSuppressionReason、quietHoursReplayAt）用于标记被推迟的通知并让通知队列按最早可重试时间回放。

测试对拍可见于 quiet_hours_test.go（断言 deferred + AlertDeliveryReasonQuietHours 与 replayAt 的一致性）、callback_config_coverage_test.go（AlertDeliveryStatusSuppressed + AlertDeliveryReasonMonitorOnly）与 incident_synthesis_test.go（AlertDeliveryReasonCorrelatedPrimary）。可以推断，浏览器“投递活动视图”中每条 held 通知的抑制原因即来自该诊断投影，前端不再需要从活跃告警反推。

五、更安全的 Agent 安装流程：Token 独立展示

改进项“更安全的 Agent 安装”指：Agent 安装命令会单独展示新生成的 Token，便于直接复制凭证，避免与整条 shell 命令混在一起误复制。

从测试可印证其行为：agent_install_command_shared_test.go 断言安装命令响应“只铸造一个 Token”（install command did not mint one token: response=%+v tokens=%d），且调用一次只产生一个 Token。这意味着安装命令的响应结构中，凭证与命令文本被分隔为独立字段，界面层可以分别渲染，从而减少凭证泄露与误操作风险。

六、其余修复点逐一说明

1. 基于确认的告警保留首个匹配观测作为发生起点：转换核心中 incident.StartedAt = incident.PendingSince，即首次匹配进入 pending 的时间即事件发生时间；新的确认运行不再继承过期的旧时间戳（reducer 重建 incident 时重新取 ObservedAt）。
2. Canonical 键控的 Metric 告警使用创建时的同一身份解析：canonicalTrackingKeyForSpec 将 spec ID 与资源 ID 组合为稳定键，恢复后不再因键漂移而残留陈旧状态。
3. 有状态告警的手动清除保留确认与近期恢复现场：preserveAlertState + consumeRecentlyResolvedForRefireWithPrimaryLock 保证手动清除后若快速重新触发，不会产生重复历史条目（对应 reducer 的 Forget/consumeRefire 路径）。
4. Guest 与 Host 内存百分比在面向操作者的解释中使用同一缓存感知口径：消除了同类指标在两类视图（guest/host）中因缓存基准不同而出现百分比口径不一致的问题。
5. 文件系统历史抽屉在拉取较长区间时重新显示加载进度：恢复前端加载反馈，避免长区间请求期间界面无响应提示。

七、升级注意事项与已知问题

• 这是候选版：稳定安装默认停留在 v6.3.2，只有显式选择该版本才升级；
• 无数据迁移：现有配置继续有效，无需手工迁移；
• 移动端无需配套更新：Mobile 不消费改动的告警转换内部实现与浏览器投递证据，相关契约不变；
• 已知问题——Windows Authenticode 签名仍不可用：请使用官方发布的校验和（checksum）与分离签名（detached signature）校验 Windows Agent 下载，并以“Unknown Publisher”警告为预期现象而非异常。

总体而言，v6.4.0-rc.5 的可观测性与确定性改进延续了 ALERT_ENGINE_EVOLUTION.md 的 Phase 1–2 路线：告警生命周期收敛到纯函数核心（reducer、discrete.go），投递决策通过 notification_policy.go 的只读诊断暴露给操作者，而 API Token 管理的持久化语义则由 api_token_migration_atomic_test.go 等用例钉住。对于在验证窗口内评估该候选版的运维团队，建议重点回归：Token 删除/迁移失败回滚、告警恢复与快速重触发（re-fire）的确认现场保留，以及投递活动视图中各抑制原因（尤其 quiet_hours、flapping、cooldown）的展示正确性。