81 lines
5.9 KiB
Markdown
81 lines
5.9 KiB
Markdown
# 真实告警接收器、值班组映射与正式演练一致性证据
|
||
|
||
## 1. 目标与边界
|
||
|
||
本工具把云端当前活动告警路由、联通测试投递状态、接收网关唯一验签回执、逻辑值班组映射和一次受控正式告警演练绑定到同一候选版本与构建摘要，生成可进入阶段8候选证据包的结构化报告。它解决以下问题：页面显示`DELIVERED`但接收端没有收到、同一`test_ref`重复通知、逻辑组没有映射到真实值班目标、只验证主接收组而遗漏升级组，以及用本地模拟接收器冒充生产告警网关。
|
||
|
||
`cmd/alert-receiver-conformance`输出`alert-receiver-conformance-report-v1`。本地Compose接收器固定产生`MOCK_RECEIVER`报告并保留`external_validation_required=true`；只有真实网关证据、全部活动路由、主/升级组映射和正式演练同时通过时，报告才是`REAL_RECEIVER`且`external_validation_required=false`。报告仍不等于业务发布批准，联合签署继续由`BUSINESS_APPROVAL`管理。
|
||
|
||
## 2. 四类输入
|
||
|
||
| 输入 | 获取方式 | 必需内容 |
|
||
|---|---|---|
|
||
| 活动路由 | 下载`GET /api/v1/ops/alert-routing-policies`完整响应 | 当前租户全部`ACTIVE`路由、主接收组、升级接收组和运行手册 |
|
||
| 联通测试 | 下载`GET /api/v1/ops/alert-delivery-tests`完整响应 | 每条活动路由最近一次`DELIVERED`测试、`test_ref`、尝试和完成时间 |
|
||
| 正式演练告警 | 下载`GET /api/v1/ops/alerts/{id}`详情 | 已解决的受控正式告警、接收组、确认动作和时间线 |
|
||
| 接收端采集 | 告警网关按`alert-receiver-capture-v1`导出 | 值班组映射、唯一测试回执、HMAC验签结果和正式演练接收/确认记录 |
|
||
|
||
接口返回可以是完整API响应或其中的`data`正文。接收端采集严格拒绝未知字段；不得包含Webhook密钥、Token、手机号、个人邮箱或完整值班人姓名。`receiver_system_ref`、`mapped_target_refs`和`acknowledgement_ref`只能使用脱敏稳定引用，例如`pager-service:platform-primary`或`incident-ticket:masked-001`。
|
||
|
||
## 3. 接收端证据格式
|
||
|
||
`alert-receiver-capture-v1`包含：
|
||
|
||
- `evidence_source`：真实网关填`REAL`，本地或测试接收器填`MOCK`；
|
||
- `candidate_version/build_digest`：必须与候选证据包完全一致；
|
||
- `group_mappings`：每个逻辑接收组对应一个或多个脱敏目标引用及复核时间；
|
||
- `test_receipts`：按`test_ref`记录外部事件编号、接收组、唯一送达次数、签名校验结果和接收时间；
|
||
- `formal_drill`：正式受控告警编号、接收组、唯一送达、签名校验、接收时间、值班确认时间和脱敏确认引用；
|
||
- `collected_at`：不得早于任何映射、回执或确认时间。
|
||
|
||
接收端事件编号与云端Outbox任务编号是两个独立公开编号，不要求相等；两端使用同一个`test_ref`绑定。每个联通测试必须只形成一条接收端回执，重复Webhook应由网关按事件编号幂等处理。
|
||
|
||
## 4. 自动校验项
|
||
|
||
报告固定包含以下10项`PASS/FAIL`检查，任一失败使总结果为`FAIL`：
|
||
|
||
1. `CAPTURE_SCHEMA`：接收证据版本正确；
|
||
2. `EVIDENCE_SOURCE`：来源明确为真实或模拟；
|
||
3. `CANDIDATE_IDENTITY`：候选版本和SHA-256构建摘要合法；
|
||
4. `CAPTURE_CANDIDATE_BINDING`：接收证据与命令参数绑定同一候选；
|
||
5. `RECEIVER_IDENTITY`：接收系统使用非秘密稳定引用；
|
||
6. `ACTIVE_ROUTES`：至少一条活动路由且全部属于同一租户；
|
||
7. `RECEIVER_GROUP_MAPPING`：每条活动路由的主接收组和升级接收组均有非空脱敏映射；
|
||
8. `DELIVERY_TEST_COVERAGE`：每条活动路由都有最近一次云端`DELIVERED`测试和唯一验签回执；
|
||
9. `DELIVERY_TIME_CORRELATION`：云端完成时间与接收时间差不超过10分钟；
|
||
10. `FORMAL_ALERT_DRILL`：一条已解决且包含确认动作的正式受控告警，与接收端唯一验签送达和确认引用一致。
|
||
|
||
联通测试不会创建正式告警，所以不能单独满足第10项。真实网关联通测试全部通过但尚未完成正式演练时，证据索引仍必须保持`REAL_ALERT_RECEIVER/PENDING`。
|
||
|
||
## 5. 命令用法
|
||
|
||
```powershell
|
||
go run ./cmd/alert-receiver-conformance `
|
||
-routes E:\evidence\alert-routes.json `
|
||
-tests E:\evidence\alert-delivery-tests.json `
|
||
-incident E:\evidence\formal-drill-incident.json `
|
||
-receiver E:\evidence\receiver-capture.json `
|
||
-candidate-version 0.63.0-rc.1 `
|
||
-build-digest sha256:<64位摘要> `
|
||
-output E:\evidence\alert-receiver-report.json
|
||
```
|
||
|
||
输出路径必须是绝对路径。通过返回0，不一致时仍写完整报告并返回1，参数、文件和JSON格式错误返回2。报告保存四份输入的SHA-256，不复制接收地址或通知正文。
|
||
|
||
## 6. 阶段8证据包门禁
|
||
|
||
`release-evidence-index-v2`中的`REAL_ALERT_RECEIVER`不可豁免：
|
||
|
||
- 无真实报告时保持`PENDING`，v3清单写入`REAL_RECEIVER_REPORT:0/1`和`FORMAL_ALERT_DRILL:0/1`；
|
||
- `files`的第一个文件必须是候选一致、所有检查通过、范围为`REAL_RECEIVER`且外部验证已完成的官方报告；后续文件可附真实网关导出、演练工单和签署材料；
|
||
- `MOCK_RECEIVER`、失败报告、跨候选报告、缺活动路由、缺升级组映射、重复回执或缺正式演练均不能标记`VERIFIED`；
|
||
- 通过后清单记录活动路由数、映射组数、测试回执数和正式演练结论，最终业务批准仍由独立门禁完成。
|
||
|
||
## 7. 本地轻量验证
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-alert-delivery-test.ps1
|
||
```
|
||
|
||
脚本只创建一条临时活动路由和一条联通测试，真实经过Worker、HMAC签名和本地验签接收器，核对唯一回执后生成`MOCK_RECEIVER`报告。它使用合成正式演练输入验证报告结构，但必须继续声明外部验证未完成。脚本结束清理临时路由、Outbox、幂等、审计和磁盘报告，不会改变`REAL_ALERT_RECEIVER`门禁。
|