# ADR-024：先定义服务承诺，再实现监控规则

- 状态：教学沙箱接受，生产待决
- 日期：2026-07-29
- 作用域：`pg36_shop` / `pg36-l2-vagrant/pg-test`

## 背景

PostgreSQL、PgBouncer、HAProxy、Patroni、主机和备份系统能产生大量指标，
Pigsty 也能把这些指标、日志与告警规则汇集起来。但是组件“看起来健康”不能
证明用户完成了下单，也不能证明确认成功的订单正确、可见且可恢复。若先从
现成指标挑阈值，团队会得到一组容易触发却无法回答用户影响的告警。

## 决策

1. 服务目录项先记录用户旅程、数据边界、依赖、责任职能和升级路径；
2. 可用性、延迟和新鲜度使用用户事件比例 SLO；
3. 正确性与恢复就绪使用控制目标，不允许用平均比例淡化数据错误；
4. 计划维护默认计入用户 SLO，排除必须事先批准、精确计数且不可追溯篡改；
5. page 从症状或完整性风险出发，原因指标进入诊断面板；容量进入 ticket；
6. 每个告警必须绑定所有者、用户影响、首个安全动作、验证和 runbook；
7. Pigsty v4.4 的 VictoriaMetrics、VictoriaLogs、VMAlert、Alertmanager 和
   Grafana 是实现与关联层，不是服务承诺本身；
8. L2/L3 变更要求目标、影响半径、独立批准、停止线、回退或前滚与证据；
9. 证据只保存最小必要的非秘密事实和完整性哈希；
10. 当前所有 owner、SLO 数值和升级目标都是教学合同，不能标记为生产批准。

## 被拒绝的方案

### 用 `postgres_up` 作为可用性

一个实例可以运行但入口、认证、事务或应用失败；也可以一个实例下线而服务
仍然正常。它适合诊断，不适合代表用户事件。

### 为所有组件故障直接 page

这种做法重复通知同一故障，也会在没有用户影响且没有动作时打扰值班人员。
原因指标保留在诊断路径；只有明确的完整性或迫近耐久性风险可以越过这一
默认边界。

### 把计划维护从 SLO 全部排除

用户并不会因为中断有变更单就获得服务。若产品明确提供维护窗口，那应当在
服务合同中单独定义，而不是事后删除失败事件。

### 以备份任务成功替代恢复证明

备份存在不等于 WAL 完整、目标可选、程序能启动、数据正确或应用可用。恢复
就绪必须来自隔离恢复与应用验收。

## 后果

好处是告警数量更少、权责与动作更清晰，并能用错误预算讨论发布速度。代价
是应用必须补充用户事件和 commit-correlated probe；组织也必须维护 owner、
值班、审批与证据系统。第 25 章将实现这里约定的指标与规则，但不能擅自改变
语义。

## 生产开放条件

- 真实服务与数据所有者共同签署 SLO 和排除政策；
- 生产流量的 eligible/good 分类经过抽样复核；
- owner route 与值班时段真实可达，并完成通知链路演练；
- 恢复、切换、安全和发布 SOP 在生产等价环境重复通过；
- 风险分级、双人控制、break-glass 和证据保留得到组织授权；
- 生产级故障域、容量、RTO/RPO 和隐私边界另行验收。