# 告警与值班 Runbook

更新日期：2026-03-24

## 目标

- 统一用户管理系统的告警分级、响应时限、升级路径与恢复验证动作
- 让“有告警规则”转变为“有处理流程、可追责、可复盘”

## 当前边界

- 仓库内已存在 Prometheus 告警规则与 Alertmanager 路由配置
- 仓库内已补齐本地结构校验材料
- 仓库内已补齐 Alertmanager 模板渲染路径：
  - [`deployment/alertmanager/alertmanager.yml`](/D:/project/deployment/alertmanager/alertmanager.yml)
  - [`deployment/alertmanager/alertmanager.env.example`](/D:/project/deployment/alertmanager/alertmanager.env.example)
  - [`scripts/ops/render-alertmanager-config.ps1`](/D:/project/scripts/ops/render-alertmanager-config.ps1)
- 仓库内已补齐严格的 live-delivery drill 入口：
  - [`scripts/ops/drill-alertmanager-live-delivery.ps1`](/D:/project/scripts/ops/drill-alertmanager-live-delivery.ps1)
  - the script fails closed on unresolved placeholders, `example.*` values, and placeholder secrets
  - the script stores only redacted config output and masked recipient information in evidence artifacts
- 当前仍未闭环的是外部通知通道真实接入证据；需要把模板变量渲染为真实联系人、真实 SMTP/通知通道和真实密钥来源

## 严重级别

- `critical`
  - 典型场景：高错误率、数据库连接池耗尽、高内存
  - 目标响应：5 分钟内确认，15 分钟内给出处置方向
- `warning`
  - 典型场景：高响应时间、高登录失败率、低缓存命中率
  - 目标响应：15 分钟内确认，60 分钟内恢复或降级
- `info`
  - 典型场景：在线用户数偏低、请求量异常
  - 目标响应：工作时间内确认，纳入趋势分析

## 标准处理流程

1. 接警后确认 `alertname`、`severity`、`service`、开始时间和当前值。
2. 检查基础健康：
   - `GET /health`
   - `GET /health/ready`
   - `GET /api/v1/auth/capabilities`
3. 如涉及登录/后台主链路，执行：
   - `cd frontend/admin && npm.cmd run e2e:full:win`
4. 对照指标判断是瞬时抖动、配置错误、发布回归还是依赖故障。
5. 若为发布回归，直接进入回滚流程：
   - [`ROLLBACK_RUNBOOK.md`](/D:/project/docs/guides/ROLLBACK_RUNBOOK.md)
6. 故障恢复后记录根因、影响范围、恢复时间、后续永久修复项。

## 升级路径

1. 一线值班先确认告警是否真实、是否影响核心用户路径。
2. `critical` 未在 15 分钟内止血，升级到应用负责人和平台负责人。
3. 涉及数据一致性、备份恢复、跨版本回滚时，升级到 DBA/平台发布负责人。
4. 需要对外沟通时，由服务 owner 输出统一事故通报。

## 发布前检查

- 告警规则结构校验通过
- Alertmanager 路由接收者已替换为真实联系人与真实 SMTP/通知通道
- Alertmanager 模板已完成渲染，且渲染产物不再包含 `${ALERTMANAGER_*}` 未解析变量
- live-delivery drill 已使用真实 env 注入执行成功，并形成红acted evidence
- 最新基线低于阈值，不存在“发布即告警”
- 回滚脚本和备份恢复脚本可执行

## 本地校验

- 告警包校验脚本：
  - [`scripts/ops/validate-alerting-package.ps1`](/D:/project/scripts/ops/validate-alerting-package.ps1)
- 告警渲染演练脚本：
  - [`scripts/ops/drill-alertmanager-render.ps1`](/D:/project/scripts/ops/drill-alertmanager-render.ps1)
- 告警真实投递演练脚本：
  - [`scripts/ops/drill-alertmanager-live-delivery.ps1`](/D:/project/scripts/ops/drill-alertmanager-live-delivery.ps1)
  - use a real env file or process environment; `alertmanager.env.example` is expected to fail closed and cannot be used as closure evidence
- 最新校验证据：
  - 校验执行后会生成 `docs/evidence/ops/<date>/alerting/ALERTING_PACKAGE_<timestamp>.md`
  - 渲染演练执行后会生成 `docs/evidence/ops/<date>/alerting/<timestamp>/ALERTMANAGER_RENDER_DRILL.md`
  - live-delivery drill 执行后会生成 `docs/evidence/ops/<date>/alerting/<timestamp>/ALERTMANAGER_LIVE_DELIVERY_DRILL.md`

## 关联材料

- 本地观测基线：
  - [`docs/evidence/ops/2026-03-24/observability/LOCAL_BASELINE_20260324-090637.md`](/D:/project/docs/evidence/ops/2026-03-24/observability/LOCAL_BASELINE_20260324-090637.md)
- 回滚 runbook：
  - [`ROLLBACK_RUNBOOK.md`](/D:/project/docs/guides/ROLLBACK_RUNBOOK.md)
- 项目当前真实状态：
  - [`REAL_PROJECT_STATUS.md`](/D:/project/docs/status/REAL_PROJECT_STATUS.md)