opsx-vpn/docs/specs/SDD-006-traffic-alert-notifications.md

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 与签名密钥	阻塞真实送达验收	管理员在设置页填写，不交给代码或日志