Metapi 告警系统深入：告警冷却、每日总结与通知节流的完整设计原理

Metapi 告警系统深入：告警冷却、每日总结与通知节流的完整设计原理

【免费下载链接】metapi把你在各处注册的 New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等站点， 汇聚成 一个 API Key、一个入口，自动发现模型、智能路由、成本最优项目地址: https://gitcode.com/gh_mirrors/meta/metapi

🔔Metapi是一款把 New API、One API、OneHub、DoneHub、Veloera、AnyRouter、Sub2API 等上游站点汇聚成一个 API Key、一个入口的 API 聚合与智能路由工具。它的告警系统由三件套组成：告警冷却机制（防止重复轰炸）、通知节流（同内容合并计数）、每日总结通知（一天一次的运营报表）。本文带你读懂这套"少打扰、高信噪比"的通知设计。

一、三层结构：事件源 → 节流器 → 渠道分发

Metapi 的告警不是一条直线，而是三层管道：

所有事件（如Token 已失效、代理全部失败）都会先落库到事件表并更新账号健康状态，再调用统一的sendNotification出口——节流只拦"外发通知"，不拦"记录与状态"，这是它的关键取舍：记录永远完整，打扰按需收敛。

二、告警冷却机制：如何用 300 秒挡住"告警风暴"

💢 想象一下：某个站点的 Token 过期后，每秒一次的代理请求都会失败。如果每次都推一条"Token 已失效"，你的 Telegram 会在几分钟内收到几百条一模一样的消息。Metapi 的解法就是告警冷静期（cooldown）。

2.1 三步判定：签名 → 比对 → 合并

1. 生成签名：把级别 + 标题 + 正文三段用||拼接成唯一签名，见 notificationThrottle.ts。内容稍有不同（比如账号名变了）就是新告警，会重新发送。
2. 冷却比对：evaluateNotificationThrottle 检查该签名最近一次发送时间——在冷静期内？直接拦截并让suppressedCount计数 +1；超过冷静期？放行。
3. 合并播报：放行时若mergedCount > 0，正文会自动追加一行[通知合并] 冷静期内已合并 N 条重复告警（见 notifyService.ts），让你知道"这 5 分钟里其实失败了 200 次"，而不是只看到 1 条。

2.2 冷静期在哪里调？

默认300 秒（由 config.ts 读取NOTIFY_COOLDOWN_SEC），也可以直接在后台「系统 → 通知设置」页面修改，保存后立即生效，持久化到notify_cooldown_sec配置项（见 settings.ts）。页面顶部就是这块"告警去噪与冷静期"卡片：

2.3 状态回收：不泄漏内存

节流状态是一个 Map，Metapi 会定期清理"超过 6 倍冷静期（至少 10 分钟）没再出现"的签名（pruneNotificationThrottleState），避免长时间运行后状态表无限膨胀。

三、每日总结通知：一天一条的"运营日报"

📊 除了"出事才喊"的即时告警，Metapi 还有一条每日总结——把当天的运营数据打包成一条日报推给你。

3.1 日报里有什么？

collectDailySummaryMetrics 按本地时区的自然日聚合四类指标：

• 账号概览：总数 / 活跃数 / 低余额（<$1）数量
• 签到统计：总计 / 成功 / 跳过 / 失败
• 代理统计：总请求 / 成功 / 失败 / 消耗 Tokens
• 费用统计：当日支出、签到奖励与净值（奖励 − 支出）

最终由 buildDailySummaryNotification 拼成每日总结 YYYY-MM-DD的多行文本推送。

3.2 定时与"豁免节流"

日报任务由 cron 调度，默认每天 23:58 触发（checkinScheduler.ts），表达式可通过daily_summary_cron自定义。注意它调用sendNotification时带了bypassThrottle: true——日报永远绕过冷却机制，同时requireChannel + throwOnFailure保证"没配渠道就报错"，不会静默丢失。这个设计说明了冷却机制的边界：它只约束高频重复告警，不约束刻意安排的关键通知。

四、告警从哪来：健康探测与代理失败判定

🩺 告警的"原材料"来自多处运行时检测：

• Token 失效告警：reportTokenExpired 同时做四件事——写事件、把账号状态置为expired、更新运行时健康状态、外发通知；失效判定由 alertRules.ts 完成，会识别 401、jwt expired、令牌过期等中英文线索，甚至自动附加"请到中转站重新生成令牌后重绑"的修复提示。
• 代理全失败告警：某模型所有通道都失败时触发代理全部失败事件，失败明细可在使用日志页面逐条排查（状态、耗时、计费一目了然）：

• 账号健康监控：账号级健康状态（active / unhealthy）驱动了可用性监控页的实时展示，是告警的可视化落点：

• 其他来源：站点公告首次发现、更新中心版本提醒、后台任务完成/失败，都走同一个sendNotification出口，因此同样享受冷却保护。

五、动手 3 步：选渠道 → 调冷静期 → 发测试通知

✅ 配置全部集中在「通知设置」页面，无需记环境变量：

1. 勾选渠道：Webhook（自动识别企业微信 / 飞书机器人并切换消息格式）、Bark、Server酱、Telegram、SMTP 邮件，可多选并行发送，任一路失败不影响其他路（notifyService.ts）。
2. 设置冷静期：默认 300 秒，上游频繁抖动的场景可以调大到 600~900 秒，进一步降噪。
3. 点"发送测试通知"：测试消息会绕过节流（bypassThrottle）并严格校验发送结果，确保渠道链路真正打通。

各环境变量速查见配置说明，notify failed等运行问题的排查思路见运维手册。

写在最后

Metapi 告警系统的哲学可以浓缩成一句话：该记住的全部记住，该闭嘴的全部闭嘴。冷却机制用"签名 + 冷静期 + 合并计数"三件套挡住了告警风暴；每日总结用一条日报替代了零散刷屏；而bypassThrottle的豁免通道则保证了关键通知绝不缺席。对同时管理几十上百个上游账号的用户来说，这套设计让"收到通知"这件事重新变得值得信任。

【免费下载链接】metapi把你在各处注册的 New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等站点， 汇聚成 一个 API Key、一个入口，自动发现模型、智能路由、成本最优项目地址: https://gitcode.com/gh_mirrors/meta/metapi