# SDD-006：流量阈值与飞书群告警

| 字段 | 内容 |
|---|---|
| 版本 / 变更级别 | 0.1 / S3 |
| 设计状态 | Implementing |
| 实现状态 | Implemented locally; remote verification pending |
| 负责人 / 日期 | Codex / 2026-10-23 |
| 关联需求 | 流量告警可配置阈值，设置内配置飞书群机器人 |
| 批准状态 | 用户要求实施；配置具体值待管理员填写 |

## 1. 背景、目标与范围
- **当前行为与证据**：`trafficmgr.CheckRateAbnormal` 固定 15 秒 90 MiB 阈值，`monitor` 每 15 秒检查；`/traffic/alerts` 查询 `rate_alert` 和 `quota_exceed`；每条隧道的配额仍由 `/tunnels/:id/policy` 管理。
- **目标**：管理员可设置突发速率阈值并启用飞书群机器人通知；日志页展示当前阈值和设置入口。
- **非目标**：改变配额策略的停止/限速动作、飞书通讯录身份认证、实时可靠消息队列。
- **保留**：旧数据库默认约 50 Mbps，通知默认关闭，已有日志查询保持可用。

## 2. 需求与约束
- FR-01：管理员可设置正整数 Mbps 速率阈值；低于阈值不生成突发告警，禁用通知仍保留站内日志。
- FR-02：管理员可填写官方飞书/Lark 群机器人 HTTPS Webhook、可选签名密钥、开关；读接口只返回配置状态，不回显密钥；可手动试发。
- FR-03：突发或配额事件发生时，在通知启用状态向群推送简要隧道事件，失败不影响隧道与监控；相同隧道事件在冷却期内避免重复发送。
- NFR-01：仅管理员可写/试发；密钥使用已有 `store.EncryptSecret` 存储；仅允许官方域名和固定路径，禁止重定向，限制超时并验证飞书业务响应。
- 边界：没有机器人地址时不能启用；没有外部群机器人凭据时只做模拟和配置验证，不声称真实送达。

## 3. 架构与方案
- `model`/`store` 增加单例告警设置，迁移只加表；`trafficmgr` 读取阈值，既有监控链路记录事件后异步交给通知模块；`api` 管理员路由暴露配置和试发。
- 前端设置增加“飞书告警”标签，日志流量告警页显示阈值和设置入口。参考 opsx-sec 的机器人地址校验、加密不回显与试发体验。
- 数据面避免同步等待外部网络；通知失败写服务日志，冷却期为 5 分钟（内存状态，重启后重新开始）。

## 4. 接口、数据与配置契约
- 新增 `GET/PUT/DELETE /api/system/alerts` 和 `POST /api/system/alerts/test`（admin）。GET 返回 `rate_threshold_mbps`、`enabled`、`configured`、`signed`；PUT 中空密钥保留已存值；DELETE 禁用并清除机器人凭据。默认阈值 50 Mbps、通知禁用。
- 新增 SQLite 单例设置表；Webhook 与签名密钥加密存储。旧 `/traffic/alerts` 及逐专线 policy 无改动。

## 5. 风险与验收
| 风险或失败场景 | 防护 / 降级 / 恢复 | 可观察信号 |
|---|---|---|
| 无效 URL 导致内网访问 | 主机名、协议、路径白名单和不跟随重定向 | PUT 400 |
| 群机器人故障 | 超时；不阻塞监控 | 日志记录失败代码 |
| 密钥泄漏 | AES-GCM 加密、不回显、不记请求体 | GET 只有 configured/signed |
| 告警风暴 | 隧道+事件 5 分钟冷却 | 同类事件不重复推送 |

| AC | 对应需求 | 操作 | 预期 | 验证方式 | 结果 |
|---|---|---|---|---|---|
| AC-01 | FR-01 | 设置阈值并以低于/高于阈值增量检查 | 只对超阈值记录 | Go 测试 | Pass |
| AC-02 | FR-02/NFR-01 | 保存、读取、无效地址试发 | 不回显密钥；无效地址拒绝 | Go 测试/API | Pass（单元测试；线上 API 待验证） |
| AC-03 | FR-03 | 模拟飞书成功/失败及冷却 | 监控无阻塞且无重复发送 | Go 测试 | Partial（业务响应模拟通过；冷却由代码检查，真实送达未测） |
| AC-04 | FR-01/02 | 设置与日志页面 | 可配置、可查询 | 前端构建/页面 | Partial（构建通过；页面待验证） |

## 6. 发布与恢复
- 先备份远程数据库及旧二进制，再构建前端并编入 Go 二进制；启动后核对健康、设置接口、静态资源及 VPN 进程。
- 新通知默认禁用，无群机器人配置时无外发；管理员自行填写并试发后才启用。回滚旧二进制可忽略新增表，保留数据库与密钥。失败时切回备份二进制并验证健康。

## 7. 待决问题
| 问题 | 是否阻塞 | 推荐方案 |
|---|---|---|
| 真实机器人 Webhook 与签名密钥 | 阻塞真实送达验收 | 管理员在设置页填写，不交给代码或日志 |