门户权限与通知受众
通知是一份事实,谁能看见由受众决定;已读状态按受众分开保存。这一页也说明配额告警的档位与去重。
8.3 软配额告警(用量阈值通知)
虚拟密钥的美元预算是两个硬限窗口(日限额 daily_budget_usd、月限额 monthly_budget_usd,任一窗口 used >= limit 时入口中间件直接返回 402);本节描述叠加在其上的软告警:跨过阈值时主动通知,让人在限额被撞满之前介入。已用金额只记当前窗口(daily_used_usd/monthly_used_usd + 窗口键),过期窗口在同一条入账更新里清零;历史消耗从 request_log 按密钥汇总。
核心取舍:当前档位不落库。 告警档位是 (日窗口 used/limit, 月窗口 used/limit, 生效阈值) 取更高一档的纯函数(store.AlertLevelOf),管理台每次读接口实时推导,不读任何缓存列。落库的只有「已通知到哪一档」:
-- virtual_key 的告警三列(避免动热路径上的其他列)
ALTER TABLE virtual_key ADD COLUMN warn_threshold_pct INTEGER NOT NULL DEFAULT 0; -- 0=继承全局
ALTER TABLE virtual_key ADD COLUMN notified_level INTEGER NOT NULL DEFAULT 0; -- 已通知过的最高档位
ALTER TABLE virtual_key ADD COLUMN notified_at INTEGER NOT NULL DEFAULT 0; -- 最近通知时间
-- 通知渠道(软告警的出站目标)
CREATE TABLE notify_channel (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
type TEXT NOT NULL DEFAULT 'webhook', -- webhook | feishu | dingtalk | wecom | slack
url TEXT NOT NULL,
secret TEXT NOT NULL DEFAULT '', -- 飞书/钉钉加签密钥
headers TEXT NOT NULL DEFAULT '', -- 自定义请求头 JSON 对象文本
enabled INTEGER NOT NULL, -- 刻意无 SQL 默认值:GORM 对带默认值的字段会跳过零值插入
last_status TEXT NOT NULL DEFAULT '', -- ok | error,最近一次投递结果
last_error TEXT NOT NULL DEFAULT '',
last_sent_at INTEGER NOT NULL DEFAULT 0,
created_at INTEGER, updated_at INTEGER
);
档位定义与判定口径(日、月两个窗口各自判定,取更高档):
| 档位 | 条件 | 含义 |
|---|---|---|
| 0 正常 | used < limit × warnPct% | — |
| 1 预警 | used/limit ≥ warnPct% | 接近上限 |
| 2 超限 | used >= limit | 硬限已生效,请求返回 402 |
超限用 used >= limit 直接比较而非按百分比判等:费用是浮点累加,9.999999999999998/10 这类值按百分比判 100% 会漏判;CheckVKBudget 的硬限判定用的就是 >=,两处口径必须一致,否则通知文案会与实际放行行为打架(有 TestAlertLevelMatchesBudgetGate 锁定)。额度 <= 0 表示该窗口不限额,两边都按无限制处理。
扫描与去重:internal/notify.Checker 常驻 goroutine,固定 30s 步长轮询、按 quota.check_interval_s 判断是否到点(不重建 ticker,故改配置即时生效)。每轮对每个有额度的密钥:派生档位 高于 notified_level 才宣告,低于则什么都不做(派生值本就实时正确,写库只会引入不一致);相等且 quota.repeat_interval_h > 0 时按间隔重复提醒。写库推进用 CAS(SetVKNotifiedLevelIf,WHERE notified_level=? AND notified_at=?):读到旧档位之后、回写之前,管理员提额触发的重新武装可能已把它归零,无条件覆盖会永久压住该密钥。
「宣告」= 写一条站内通知(见 §8.4),写成功才推进档位;写失败不推进、下轮重试,事件不会静默丢失。外发渠道只是尽力而为的旁路:
| 情形 | 旧行为 | 现行为 | 理由 |
|---|---|---|---|
| 无启用渠道 | 什么都不做,档位不推进(配好渠道后补发) | 照常写站内通知并推进档位 | 站内通知是「记录」;没有外发目标时更该留下事实,否则用户永远看不到配额事件 |
| 渠道全部失败 | 不推进档位,下轮重试 | 已写站内通知即推进;失败另记一条 quota.delivery_failed | 一元状态无法同时表达「站内已记」与「外发待重试」,且重试收益(5 分钟后再 ping 一次)小于新增一套待投递状态的成本。失败可观测性由渠道行的 last_status/last_error 与 delivery_failed 通知共同保证 |
重新武装(回答「预警发过之后用户提额,还会不会再通知」):窗口已用金额单调不减(结算只做加法,唯一归零路径是换桶/重置预算),所以占比回落只可能来自用户提额或重置预算——恰好就是该重新武装的动作。因此归零只发生在显式写路径:UpdateVirtualKey(仅当日限额、月限额或阈值实际变化时)与 ResetVirtualKeyBudget,另有 PUT /api/settings 全局阈值上调时清继承全局阈值的密钥(store.RearmInheritedQuotaAlerts)。只改名称/状态/路由授权不归零,避免无谓重发。由于走的是 API 写路径而非扫描,告警总开关关闭期间同样正常归零,不存在「关掉再打开后档位陈旧、该通知不通知」的坑。
投递:单次尝试不重试,10s 超时,非 2xx 记为失败;飞书/钉钉/企业微信在加签错误等情况下返回 HTTP 200 + 业务错误码,必须解析响应体判失败,否则「发送测试」按钮形同虚设。结果写回渠道行的 last_* 三列,让管理台一眼看出告警有没有真的发出去。
8.4 通知中心(站内系统通知)
管理台顶栏铃铛 + 未读角标,抽屉内查看系统事件,支持已读/未读/删除。事件类型是自由字符串,新增类型不用改表:
| type | 级别 | 触发 |
|---|---|---|
model.disabled | error | 某模型全部绑定密钥都被永久禁用 |
model.recovered | info | 该模型从「全禁用」回到可用 |
quota.warn | warning | 虚拟密钥用量跨过预警阈值(§8.3) |
quota.exceeded | error | 虚拟密钥用量用满额度(§8.3) |
quota.delivery_failed | warning | 配额告警的外发渠道投递失败 |
CREATE TABLE notification (
id INTEGER PRIMARY KEY AUTOINCREMENT,
type TEXT NOT NULL, -- 见上表
level TEXT NOT NULL DEFAULT 'info', -- info | warning | error
title TEXT NOT NULL,
body TEXT NOT NULL DEFAULT '',
subject TEXT NOT NULL DEFAULT '', -- "model:12" / "vk:3" / "channel:2",也是可见范围的依据
created_at INTEGER
);
CREATE INDEX idx_notification_type ON notification(type);
CREATE INDEX idx_notification_subject ON notification(subject);
CREATE INDEX idx_notification_created_at ON notification(created_at);
-- 已读按受众分开:同一条事实管理台与每把密钥各自已读,互不影响。没有行 = 未读。
CREATE TABLE notification_read (
notification_id INTEGER NOT NULL,
audience TEXT NOT NULL, -- "admin" 或 "vk:<id>"
read_at INTEGER NOT NULL,
PRIMARY KEY (notification_id, audience)
);
-- model 的通知去重列
ALTER TABLE model ADD COLUMN notified_status TEXT NOT NULL DEFAULT ''; -- '' 或 'disabled'
谁能看见。 事实只有一份,按 subject 决定受众:vk:<id> 只给这把密钥的门户和管理台;model:<id> 给管理台,以及白名单路由(含兜底模型)实际用得到该模型的密钥门户——不限路由的密钥等于全部路由;channel:* 等其余类型只给管理台(渠道投递失败是管理员的事)。门户不提供标记已读与删除。
核心不变量:告警去重状态不放在通知表里。 通知表是用户可删除的;若靠「查最近一条同 subject 的通知」判断是否需要再通知,用户删掉那条通知,下一轮扫描就会把它重新创建出来——删不干净。所以去重状态一律落在被监控实体自己的列上:
| 用户动作 | 去重状态 | 通知表 | 是否重发 |
|---|---|---|---|
| 读 / 未读 / 删除通知 | 不动 | 少一行 | 不重发 |
| 模型恢复可用 | model.notified_status 清空 | 新增「已恢复」一条 | 恢复后再次全禁用才发 |
| 密钥提额 / 改阈值 / 重置预算 | virtual_key.notified_level 归零(§8.3) | 新增下一条 | 再次跨线才发 |
模型健康态是派生值。 熔断的禁用粒度是 模型×密钥组合(model_key_ban),模型级 disabled 没有单一写入点,它是「绑定密钥全部被永久禁用」的聚合结论(store.ModelHealth,与 /api/health 共用同一套判定,避免两处漂移)。因此检测放在周期扫描里而非熔断调用点:CheckModelHealth 每 30s 步长都跑(判定只是几张表的全量读),只在 disabled 与其恢复这两个跃迁上记通知;cooldown(30s→1m→3m 自愈阶梯)与 no_key(未绑定 / 全部冷却中)刻意不记,否则会刷屏。这条路径也顺带覆盖了「管理员手动禁用模型」——手动禁用同样是写 model_key_ban。
配额类事件受 quota.alert_enabled 总开关管(关掉后站内与外发一起停,避免「关了还在记」);模型类事件受 notify.model_health_enabled 管(站内通知只写本地库、不外发,故默认开)。
保留:通知只由低频事件产生,用固定条数上限兜住增长(store.NotificationKeepRows = 500,在既有的每小时清理循环里剪枝),不单独开保留期配置。