状态:设计中 / 实现中。 这一页是设计稿,描述定时探测被自动禁用的 模型×密钥 组合并自动解禁的机制。配置与行为以当前版本代码为准。
定时探测与自动解禁(Probe Auto-Recovery)
状态:待确认(草案) 适用版本:v1.x 关联模块:
internal/breaker、internal/proxy/probe.go、internal/store、internal/api、internal/notify、web/src/pages/Settings.tsx、web/src/components/BanManagerModal.tsx
1. 背景
当前熔断只发生在「模型 × 密钥」组合这一粒度(model_key_ban):
- 401/403 立即
perm_banned; - 超时 / 5xx / 连接失败 / 断流按阶梯冷却,连续失败达到
breaker.disable_threshold(默认 3)后perm_banned; - 429 短冷却,不计入失败次数;
- 成功会删除该组合的禁用行。
perm_banned 之后没有任何自动恢复路径:路由会跳过该组合,因此它永远拿不到一次成功的真实请求来清除自己,只能由人手动解禁、删除模型/密钥,或者(在模型全部密钥被禁时)使用模型级解禁。
同时,perm_banned 目前把三种来源混在一起:
- 失败归因产生的永久禁用;
- 管理员手动禁用单个组合;
- 管理员手动禁用整个模型(实现上是对当时绑定的每个组合写
perm_banned)。
自动恢复必须能区分 1 和 2/3,否则会把管理员的手动操作解掉。
仓库里已经有完整的探测能力:proxy.ProbeModelKeys / probeModelKey 会按模型类型构造最小真实请求,走与正式代理相同的协议适配器、body_override、提供商代理和超时配置,并且不写 request_log(探测流量不计入统计)。本方案复用它,只补「调度、判定、解禁、状态展示」。
2. 目标与非目标
2.1 目标
| # | 能力 |
|---|---|
| G1 | 可配置的周期探测:对满足条件的被禁组合发起最小真实请求 |
| G2 | 探测成功自动解禁该「模型 × 密钥」组合,失败保持禁用 |
| G3 | 只恢复“自动禁用”,手动禁用永不自动恢复 |
| G4 | 成本可控:按类型、按错误类型、按模型状态分级;并发与单轮数量有上限;失败指数退避 |
| G5 | 多实例下不重复探测(按组合租约) |
| G6 | 管理台可见:来源、最近探测结果、下次探测时间、跳过原因 |
| G7 | 默认关闭,升级不改变现有行为 |
2.2 非目标(本期不做)
- 不做用户自定义探测脚本(见 §7.6 的理由)。
- 不恢复手动禁用(模型级或组合级)。
- 不默认恢复 401/403(认证类错误不会自愈,且高频 401 可能触发上游风控)。
- 不探测
image/tts/stt/video(默认);video永久排除(会真实提交一次渲染)。 - 不把探测流量写入
request_log、不计入虚拟密钥用量与统计。 - 不新增组合级通知类型;恢复通知复用现有
model.recovered。 - 不做模型级/提供商级的探测开关(留到二期,见 §16)。
3. 关键设计决策
| 决策 | 选择 | 理由 |
|---|---|---|
| 恢复单元 | 模型 × 密钥组合 | 与熔断粒度一致;模型健康是派生值,不能做单一写入点 |
| 可恢复来源 | 仅 origin=auto | 手动禁用必须绝对保留 |
| 探测方式 | 内置最小真实请求 | 同时验证鉴权、配额、模型权限、网络与协议转换;已有实现 |
| 默认模式 | banned_any + 降频倍数 | disabled_only 会让“部分 key 被禁”的组合永远卡住(见 §6.3) |
| 认证错误 | 默认不探 | 401/403 不会自愈;每 5 分钟敲一次是无效且有风险的流量 |
| 昂贵类型 | 默认排除 | image 真实生成、video 真实渲染,探测成本不可接受 |
| 解禁方式 | CAS 删除,条件含 origin='auto' | 探测期间管理员手动禁用时不能误删 |
| 失败处理 | 只更新探测状态,不改 status / fail_count | 探测失败不能延长或加重禁用(对齐 new-api 的 allowDisable=false) |
| 多实例 | 组合级租约 | 共享库部署下避免 N 倍探测成本 |
| 默认开关 | 关闭 | 升级默认不产生任何出站流量 |
4. 数据模型
4.1 model_key_ban 新增列
type ModelKeyBan struct {
// ... 现有字段不变
Origin string `json:"origin" gorm:"size:16;not null;default:'auto'"` // auto | manual
LastProbeAt int64 `json:"last_probe_at" gorm:"not null;default:0"`
LastProbeOK bool `json:"last_probe_ok" gorm:"not null;default:false"`
LastProbeError string `json:"last_probe_error" gorm:"size:512;not null;default:''"`
ProbeFailCount int `json:"probe_fail_count" gorm:"not null;default:0"` // 连续探测失败次数,与真实流量 fail_count 分离
NextProbeAt int64 `json:"next_probe_at" gorm:"not null;default:0"`
ProbeLeaseUntil int64 `json:"-" gorm:"not null;default:0"` // 多实例探测租约
}
要点:
ProbeFailCount与FailCount必须分开。前者驱动退避,后者是真实流量熔断计数;探测失败不能推进后者。LastProbeError只记探测结果,不覆盖LastError(真实流量最近错误),否则管理台会分不清“上次真实失败”和“上次探测失败”。- 探测成功后整行被删除,探测状态随之消失,语义正确。
- 该表已有
(model_id, key_id)唯一索引,新增列不影响索引。
4.2 origin 语义
| 值 | 写入点 |
|---|---|
auto | RecordModelKeyFailure、RecordModelKeyRateLimited、BanAllModelKeys 之外的自动路径;旧数据默认值 |
manual | BanAllModelKeys(模型级手动禁用)、banModelKey(组合级手动禁用) |
把当前写死的 "manually disabled via admin API" 提成一个共享常量(例如 store.ManualBanReason),三处(breaker、api、迁移回填)复用,避免文案漂移。
4.3 迁移与回填
AutoMigrate 自动加列,默认值保证旧行为不变。随后执行一次幂等回填(与 migrateNotificationReads 同一模式,放在 store.Open 的迁移序列里):
UPDATE model_key_ban
SET origin = 'manual'
WHERE ban_reason = ? AND origin <> 'manual'
- 旧库中手动写入的禁用行 reason 就是该常量,能准确识别。
- 失败归因行的 reason 是「连续 N 次失败…」「上游返回 401…」「上游限流 429」等,保持
auto。 - 回填失败不阻止启动,但记录
slog.Warn(它只影响自动恢复的边界,不影响熔断本身)。
4.4 状态与生命周期
真实流量失败
│
├─ 401/403 ──────────────────────► perm_banned (origin=auto)
├─ 可重试失败达阈值 ─────────────► perm_banned (origin=auto)
└─ 429 ──────────────────────────► temp_banned(TTL 自愈,不参与探测)
手动禁用(模型/组合)────────────────► perm_banned (origin=manual)
探测成功 + CAS 删除 ─────────────────► 行删除(组合恢复 active)
探测失败 ───────────────────────────► 行保留,更新 last_probe_* / next_probe_at
temp_banned 不参与自动探测:它的 TTL 到期后本来就半开可用,探测只会增加成本。
4.5 配套改动:改密钥值时清掉该 key 的自动禁用
当前 updateKey 只改 key_value,不碰 model_key_ban。一把失效的 key 换成新值后,旧模型上的 perm_banned 仍在,用户会以为“换了 key 还没好”。
建议在同一事务里:
DELETE FROM model_key_ban WHERE key_id = ? AND origin = 'auto'
手动禁用行保留。这解决的是一个与此功能高度相关的实际痛点,且成本极低。
5. 配置项
全部放入运行层(settingSpecs),保存即热生效;循环每个 tick 读 rt.Snapshot(),不重建 ticker。
| 键 | 类型 | 默认 | 范围 | 说明 |
|---|---|---|---|---|
probe.recover_enabled | bool | false | - | 总开关 |
probe.mode | string | banned_any | banned_any | disabled_only | 候选范围,见 §6 |
probe.interval_s | int | 300 | 60–86400 | 模型全禁用时的基础探测间隔 |
probe.degraded_multiplier | int | 4 | 1–24 | 模型仍有可用组合时的间隔倍数(默认 20 分钟) |
probe.timeout_s | int | 15 | 1–300 | 单次探测超时;同时压住提供商默认 120s |
probe.max_concurrency | int | 2 | 1–16 | 全局并发探测上限 |
probe.max_per_cycle | int | 20 | 1–200 | 每轮最多探测数,防止启动后一次性打满 |
probe.max_interval_s | int | 3600 | 60–86400 | 指数退避上限,且必须 ≥ probe.interval_s |
probe.recover_auth | bool | false | - | 是否探测 401/403 禁用 |
probe.types | []string | ["chat","embedding","rerank"] | chat/embedding/rerank/image/tts/stt | 参与自动探测的模型类型;video 固定排除 |
校验规则:
mode必须是枚举值;types必须是合法子集,包含video时直接拒绝并提示“视频探测会提交真实渲染,不参与自动探测”;max_interval_s >= interval_s;- 其他整数走现有
intRange; - 新增一个
strEnum校验器(仓库目前没有)。
Runtime 结构体新增对应字段(ProbeRecoverEnabled、ProbeMode、ProbeIntervalS 等),解析时对 mode/types 再做一次兜底,避免手工改库写入非法值。
6. 候选选择
6.1 基本条件
一个 model_key_ban 行成为候选,必须同时满足:
status = 'perm_banned';origin = 'auto';model_key行仍存在(组合仍被绑定);api_key.provider_id = model.provider_id(与router.Selector、store.ModelHealth同口径;跨提供商的绑定路由根本不收);- 模型类型在
probe.types中; probe.recover_auth = true,或last_error不是401/403;- 已到探测时间(见 §6.2);
- 租约可用(
probe_lease_until <= now)。
temp_banned、origin=manual、未绑定、跨提供商的组合一律跳过。
6.2 节奏:全禁用快探,降级慢探
先按 store.LoadModelHealthAt(now) 计算每个模型的状态(该函数已被 /api/health 与通知扫描使用,口径一致):
| 模型状态 | 有效间隔 |
|---|---|
disabled(全部绑定组合 perm_banned) | probe.interval_s(默认 300s) |
active(仍有可用组合) | probe.interval_s × probe.degraded_multiplier(默认 1200s) |
其他(no_key / cooldown) | 不探(no_key 无意义;cooldown 会自愈) |
到期判定使用:
dueAt = max(next_probe_at, last_probe_at + effective_interval)
next_probe_at由失败退避写入;last_probe_at + effective_interval保证模型从 disabled 变成 active 后,剩余组合自动降频,不需要批量改写next_probe_at;- 两个值都为 0(新产生的自动禁用)时立即到期,下一次 tick 就会探一次。
循环 tick 固定 30 秒(与 notify.Checker 同一量级),不用配置值重建 ticker。
6.3 两种模式的取舍
banned_any(建议默认):所有自动禁用组合都参与。模型还有别的可用 key 时按降频间隔探。disabled_only:只在模型“全部组合被禁”时探。
disabled_only 的已知副作用:模型有 3 把 key 全坏,探活第 1 把并解禁后,模型立刻变成 active;剩下 2 把仍是 perm_banned,而路由不会再选中它们,它们会永远卡住。除非管理员手动解禁,否则这部分容量永远回不来。
因此默认用 banned_any + 降频倍数:全禁用时 5 分钟快探,部分禁用时 20 分钟慢探,既避免卡死,也把成本压住。如果更在意成本、且接受手动清理“部分禁用”的组合,可以选 disabled_only。
6.4 查询实现
建议在 store 新增 ListProbeCandidates(now, opts),一条 JOIN 查询拿到候选,再用 LoadModelHealthAt 的结果做 §6.2 的过滤:
SELECT b.*, m.name AS model_name, m.type AS model_type, m.provider_id AS model_provider_id
FROM model_key_ban b
JOIN model m ON m.id = b.model_id
JOIN api_key k ON k.id = b.key_id
JOIN model_key mk ON mk.model_id = b.model_id AND mk.key_id = b.key_id
WHERE b.status = 'perm_banned'
AND b.origin = 'auto'
AND k.provider_id = m.provider_id
AND m.type IN ?
AND b.probe_lease_until <= ?
ORDER BY b.next_probe_at, b.id
认证过滤与到期判定可以在 SQL 里做,也可以取出后在内存里做(候选数量很小)。disabled_only 用 ModelHealthSnapshot.StatusOf 过滤,避免自己再写一套“是否全部被禁”的判定。
7. 探测执行
7.1 入口
在 internal/proxy/probe.go 新增导出的单组合探测:
type ProbeOptions struct {
Timeout time.Duration // 0 表示沿用 provider.TimeoutMs
Strict bool // 自动恢复用 true:要求响应结构与模型类型匹配
}
func ProbeModelKey(db *store.Store, rt *config.RuntimeManager, modelID, keyID int64, opt ProbeOptions) ProbeResult
内部:
- 加载 model / provider / key,校验
model_key绑定与key.provider_id == model.provider_id; - 复制 provider,把
TimeoutMs压到opt.Timeout; - 调用现有
probeModelKey; Strict时追加 §7.3 的响应校验。
现有 ProbeModel / ProbeModelKeys / ProbeProvider 保持行为不变(手动测试不受影响)。
7.2 载荷
直接复用现有 probeModelKey 的类型分支:
- chat:一条
ping消息 +max_tokens=16; - embedding:
input: "ping"; - rerank:
query: "ping"+ 单文档; - image / tts / stt / video:本期默认不参与自动探测,载荷保留给手动测试。
不新增“用户脚本”路径。body_override 已经能覆盖“这个模型必须带某个额外字段”的情况。
7.3 超时与取消
- 每次探测使用
context.WithTimeout(ctx, probe.timeout_s); probeModelKey内改用http.NewRequestWithContext,让进程退出时在途探测能及时取消;- 客户端超时取
min(provider.TimeoutMs, probe.timeout_s),避免一次挂起占住 worker 15 秒以上; - 现有
HTTPClientFor每次新建 client,探测频率下可接受;不引入新的连接池。
7.4 严格成功判定
probeModelKey 目前只要 2xx 且 body 非空就 Ok=true,一个 200 的维护页/网关错误页会被误判为恢复。自动解禁必须更严格:
| 模型类型 | 额外要求 |
|---|---|
| chat(completions / responses / messages / gemini) | body 是合法 JSON,且至少出现 choices(非空)、output、content(非空)、candidates 或非零 usage 之一 |
| embedding | data 数组非空 |
| rerank | results 数组非空 |
| image | data 或 images 非空 |
| audio | body 非空(沿用现有判断) |
不满足时视为探测失败(last_probe_error = "invalid_response"),不解禁,并记录一条截断后的响应预览(不含密钥)。
7.5 并发
- 全局信号量
probe.max_concurrency; - 每轮最多
probe.max_per_cycle个候选; - 同一模型内串行(避免对同一上游同时打多个请求),不同模型可并行;
- 每轮对候选做一次随机打散,并给
dueAt加 ±10% 抖动,避免所有模型整点一起探。
7.6 为什么不做用户脚本
结论:不做。理由按重要性排序:
- 脚本拿不到完整的成功语义。真正要验证的是“这把 key 经这套协议适配、这个 base_url、这个模型,现在能不能返回可用响应”。脚本只能自己重新实现鉴权、协议转换、代理和解析,每个 provider 一份,且容易与代理真实行为不一致。
- 密钥泄露面。脚本需要密钥原文;走 argv/env 会被同机其他用户从
ps看到。把密钥交给用户可控代码,等于在网关进程里开了一个任意代码执行入口。 - 可移植性。Windows 没有
sh;还要处理解释器、超时、进程树、退出码语义。 - 现有能力已经覆盖。7 种模型类型的最小载荷都已实现;特殊 provider 可以通过
body_override或后续的声明式probe_path/probe_body覆盖。
如果未来确实需要“非标准健康端点”,优先加声明式配置(probe_path、probe_method、probe_body、probe_expect_status),而不是执行脚本。
8. 解禁与失败处理
8.1 CAS 解禁
新增:
func (rec *Recorder) UnbanModelKeyIfAuto(modelID, keyID int64) (bool, error) {
res := rec.db.DB.
Where("model_id = ? AND key_id = ? AND status = 'perm_banned' AND origin = 'auto'", modelID, keyID).
Delete(&store.ModelKeyBan{})
return res.RowsAffected > 0, res.Error
}
为什么条件里要有 origin = 'auto':
- 探测期间管理员可能通过
POST /api/models/{id}/bans/{key_id}手动禁用该组合,写入origin='manual';无条件DELETE会把这次手动操作抹掉。 - 管理员手动解禁(删除行)或真实流量成功(删除行)后,CAS 删除影响 0 行,属于正常。
- 不需要依赖
updated_at秒级精度;origin的翻转已经覆盖最危险的那条竞态。
8.2 探测状态更新
失败时只更新探测字段,且同样带条件,避免把已删除/已改为手动的行写脏:
UPDATE model_key_ban
SET last_probe_at = ?, last_probe_ok = 0, last_probe_error = ?,
probe_fail_count = probe_fail_count + 1, next_probe_at = ?,
probe_lease_until = 0
WHERE id = ? AND status = 'perm_banned' AND origin = 'auto'
成功时直接走 §8.1 的 CAS 删除;如果删除影响 0 行,记录一条 Info 日志(说明期间状态被人工改变),不重试。
绝不修改:status、banned_until、ban_reason、fail_count、last_error。
8.3 探测结果分类
| 探测结果 | 处理 |
|---|---|
| 2xx + 严格校验通过 | CAS 解禁 |
| 2xx + 校验不通过 | 失败,invalid_response,退避 |
| 400 | 失败,400;连续 3 次后把退避拉到上限并 slog.Warn(多半是探测载荷与 body_override 不匹配) |
| 401 / 403 | 失败,保持禁用;默认根本不会成为候选(recover_auth=false)。开启后连续失败会很快退避到上限 |
| 404 | 失败,404;多半是模型被上游下线,退避到上限并 slog.Warn |
| 429 | 失败,保持 perm_banned;不要调用 RecordModelKeyRateLimited(避免把永久禁用改成临时冷却) |
| 5xx / 超时 / 连接失败 | 失败,保持禁用,退避 |
所有失败都只影响探测节奏,不影响真实流量的熔断计数。
8.4 退避公式
effective = base × (model.status == "disabled" ? 1 : degraded_multiplier)
delay = min(effective × 2^min(probe_fail_count, 6), max_interval_s)
next = now + delay × (1 ± 10% 抖动)
probe_fail_count从 0 开始,第一次失败后为 1;- 模型从 active 变成 disabled 时,已经写入的
next_probe_at不回退(最多等一个旧退避周期),换来实现简单;新产生的禁用行仍然立即探测; - 探测成功后行被删除,计数自然清零。
8.5 与现有熔断的交互
- 探测成功只删行,不写
request_log,不影响统计和虚拟密钥额度; - 探测失败不推进
fail_count,所以不会因为“探了几次”就再次永久禁用; - 真实流量在探测期间失败:由于组合是
perm_banned,路由不会选中它,正常不会发生;若同时存在手动解禁/半开窗口,真实流量的成功会删行、失败会按原有逻辑重新计数,探测侧无需特殊处理。
9. 多实例与并发
OmniGate 支持 MySQL/Postgres 共享库,多入口部署时每个进程都会跑探测循环。按组合抢租约:
UPDATE model_key_ban
SET probe_lease_until = ?
WHERE id = ? AND probe_lease_until <= ?
RowsAffected == 1 才执行探测;租约时长建议 probe.timeout_s + 30s,进程崩溃后自动过期。探测结束(成功删行或失败更新)时把 probe_lease_until 归零。
- SQLite 单文件部署实际上只有一个写者,租约仍保留,避免未来多进程/误配置时重复探测。
- 不做全局 leader 选举:按组合租约的粒度更细,一个实例挂了不会拖住全部探测。
10. 通知与可观测性
10.1 通知
- 复用现有
notify.Checker:它每 30 秒扫描模型健康,disabled → active时发model.recovered。自动解禁会让这个跃迁自然发生,不需要新代码。 - 本期不新增组合级通知。否则一个模型下多把 key 恢复会刷屏。
- 如果模型仍有其他被禁组合、解禁后仍非
active,不发恢复通知(现有逻辑已经只在active时宣告,口径正确)。
10.2 日志
- 解禁成功:
slog.Info("model-key auto recovered", "model", ..., "key_id", ..., "latency_ms", ..., "probe_count", ...)。 - 单次探测失败:
slog.Debug,避免 30 秒一轮的日志噪声。 - 连续 3 次 400/404:
slog.Warn,提示检查body_override/ 模型是否下线。 - 租约抢占失败:不记日志(正常竞争)。
10.3 抖动(flap)
可能出现的循环:探测成功 → 解禁 → 真实流量失败 3 次 → 再次永久禁用 → 5 分钟后探测成功……每轮会发一对 model.disabled / model.recovered 通知。
本期用三个机制压住:
- 真实流量要连续失败 3 次才重新永久禁用(现有阈值);
- 探测失败指数退避;
- 每轮只探有限数量、并打散。
如果实测仍有明显抖动,二期加“同一组合在 probe.flap_window_s(默认 600s)内被探测恢复过,则下次基础间隔翻倍”的内存态抑制(重启丢失可接受)。
11. API 与 UI
11.1 API(向后兼容的字段追加)
GET /api/models/{id}/bans 的 modelKeyBanItem 追加:
Origin string `json:"origin"` // auto | manual(active 行为空)
LastProbeAt int64 `json:"last_probe_at"`
LastProbeOK bool `json:"last_probe_ok"`
LastProbeError string `json:"last_probe_error,omitempty"`
ProbeFailCount int `json:"probe_fail_count"`
NextProbeAt int64 `json:"next_probe_at"`
ProbeEligible bool `json:"probe_eligible"` // 后端按当前配置算
ProbeSkipReason string `json:"probe_skip_reason,omitempty"`
ProbeEligible / ProbeSkipReason 由后端根据 probe.recover_enabled、probe.mode、probe.types、probe.recover_auth 和模型当前状态计算,取值示例:
manual:手动禁用,不自动恢复auth:认证类错误,未开启自动探测type:该模型类型不参与自动探测mode:当前模式下不探测(仅disabled_only且模型仍有可用组合)temp:临时冷却,会自愈disabled:自动探测总开关关闭
不需要新增 REST 端点;手动测试仍走现有 /api/models/{id}/probe。
11.2 禁用管理弹窗(BanManagerModal.tsx)
- 新增「来源」列:
自动/手动标签。 - 新增「最近探测」列:时间 + 成功/失败图标;失败时 Tooltip 显示
last_probe_error。 - 新增「下次探测」列:相对时间;
ProbeEligible=false时显示ProbeSkipReason的中文文案(如“认证错误,不自动探测”)。 - 手动禁用行不显示探测信息,操作列仍只有「解禁」。
- 顶部加一条
Alert:自动探测会发送真实请求并产生上游费用(仅当总开关开启时显示)。
11.3 设置页(Settings.tsx)
新增 probe 分区(Section 联合类型、sectionLabels、numericRanges 同步补齐):
- 开关:启用自动探测解禁
- 单选:探测范围(任意被禁组合 / 仅模型全禁用)
- 数字:基础间隔(秒)、模型仍可用时的间隔倍数、单次超时(秒)、并发上限、单轮上限、退避上限(秒)
- 开关:探测 401/403(带警告说明)
- 多选:参与探测的模型类型(
video置灰并说明固定排除) Alert:解释“探测是真实调用,会计费;手动禁用永不被自动恢复”
save 逻辑沿用现有 PUT /api/settings,新键没有特殊处理。
11.4 文案调整
breaker.disable_threshold 的帮助文案目前是“失败3→禁用(需手动解禁或改阈值让第3档生效)”,改为“失败3→禁用(可开启‘探测恢复’自动解禁)”。
12. 代码落点
| 文件 | 改动 |
|---|---|
internal/store/models.go | ModelKeyBan 新增列;ManualBanReason 常量 |
internal/store/store.go | 迁移序列后调用 migrateBanOrigin |
internal/store/probe.go(新增) | ProbeCandidate、ListProbeCandidates、UpdateProbeFailure、ClaimProbeLease、migrateBanOrigin |
internal/breaker/breaker.go | UnbanModelKeyIfAuto;BanAllModelKeys / 手动禁用写 origin=manual |
internal/proxy/probe.go | 导出 ProbeModelKey;ProbeOptions;probeModelKey 接受 context 与 strict;现有手动入口保持行为 |
internal/recovery/recovery.go(新增) | 循环、候选调度、并发、退避、租约、日志;探测函数可注入以便测试 |
cmd/omnigate/main.go | 在 go notify.New(st, rt).Run(ctx) 旁启动 go recovery.New(st, rt).Run(ctx) |
internal/config/runtime.go | Runtime 字段、settingSpecs、解析、strEnum 校验器 |
internal/api/models.go | modelKeyBanItem 追加字段与 ProbeEligible 计算 |
internal/api/keys.go | 改 key_value 时删除该 key 的 origin='auto' 禁用行 |
web/src/components/BanManagerModal.tsx | 来源/探测列、跳过原因、费用提示 |
web/src/pages/Settings.tsx | 新增 probe 分区与表单项 |
docs/AGENTS.md | 熔断章节补充自动恢复语义与四类边界(手动/认证/类型/租约) |
包依赖方向:
cmd/omnigate ──► internal/recovery ──► internal/proxy ──► internal/breaker
│ │
└────────────────────┴──► internal/store / config
recovery 是叶子包,不反向被 proxy 引用,无循环依赖。
13. 测试计划
13.1 单元测试
- store
TestListProbeCandidates:模式、origin、类型、认证过滤、到期时间、跨提供商绑定、租约占用。TestMigrateBanOrigin:手动 reason 回填为 manual;失败 reason 保持 auto;重复执行幂等。TestClaimProbeLease:两个并发 claim 只有一个成功;过期租约可被重新抢占。
- breaker
TestUnbanModelKeyIfAuto:auto 行被删;manual 行保留;temp 行不受影响。TestManualBanOrigin:BanAllModelKeys/banModelKey写入 manual。
- proxy
TestProbeModelKeyTimeoutOverride:ProbeOptions.Timeout压过 provider 默认值。TestStrictProbeValidation:各模型类型的合法/非法响应(200 HTML、200 错误 JSON、缺choices等)。
- recovery
- 注入假探测函数 + 假时钟,表驱动覆盖:成功解禁、失败退避、400/404 上限、429 不改状态、认证跳过、类型跳过、
disabled_onlyvsbanned_any、全禁用快探 / 降级慢探、探测期间被手动禁用(CAS 不删)。
- 注入假探测函数 + 假时钟,表驱动覆盖:成功解禁、失败退避、400/404 上限、429 不改状态、认证跳过、类型跳过、
- config
mode枚举、types子集、max_interval_s >= interval_s、video拒绝。
- api
/api/models/{id}/bans返回新增字段与ProbeEligible文案;旧字段不变。
13.2 集成与手动验收
- 建一个模型 + 两把 key;手动把其中一把
perm_banned(origin=auto),开启探测,把间隔调到 60s,确认只探这一把、成功后行消失。 - 把两把都设为 401 禁用,确认默认不探;打开
recover_auth后开始探,并退避到上限。 - 探测期间通过管理台手动禁用该组合,确认探测成功后不会删掉 manual 行。
- 共享 MySQL 起两个实例,确认同一组合同一时间只有一个实例在探(日志/租约)。
- 关闭总开关,确认没有任何出站请求。
13.3 提交前
go test ./...
go vet ./...
go test -race ./internal/recovery ./internal/breaker ./internal/store
cd web && npm run build
14. 迁移、兼容与灰度
- 默认关闭:升级后
probe.recover_enabled=false,即使库里有旧的perm_banned,也不会产生任何探测流量。 - 列追加:
AutoMigrate在 SQLite/MySQL/Postgres 上都只加列,不重建表;旧版本二进制会忽略新列。 - 回填:只把
ban_reason = ManualBanReason的旧行标为 manual;其余保持 auto。回填失败只影响边界,不影响现有熔断。 - 灰度:建议先在单实例 SQLite 环境开启,调好间隔/类型后再在共享库多实例环境启用。
- 回滚:关闭开关即可;新列和探测状态不影响旧逻辑。若回滚到旧二进制,新列保留但被忽略。
15. 风险与对策
| 风险 | 对策 |
|---|---|
| 探测成本失控 | 默认排除 image/tts/stt,video 硬排除;并发、单轮上限、指数退避;全禁用快探、降级慢探 |
| 高频 401 触发上游风控 | 默认不探 401/403;开启后也受退避上限约束 |
| 200 维护页被误判恢复 | 严格响应校验(JSON + 协议特征字段) |
| 探测期间管理员手动禁用被抹掉 | CAS 删除,条件含 origin='auto' |
| 多实例重复探测 | 组合级租约 + 租约过期 |
disabled_only 导致部分被禁组合永久卡住 | 默认 banned_any + 降频;文档明确说明 disabled_only 的取舍 |
| 探测载荷与 provider 不匹配(400) | 连续 3 次后拉满退避并告警;可用 body_override 修正;二期支持声明式 probe body |
| 恢复-禁用抖动刷通知 | 3 次失败阈值 + 退避;二期加 flap 窗口抑制 |
| 探测失败反而加重禁用 | 探测失败只写 last_probe_* / probe_fail_count,绝不改 status / fail_count |
| 跨提供商绑定被误探 | 候选 SQL 强制 api_key.provider_id = model.provider_id,与路由同口径 |
16. 分期实施
一期(MVP,建议本次实现)
origin列 + 迁移回填;手动写入口改为 manual。model_key_ban探测状态列。- 配置项与校验、Settings 分区。
- 候选查询、循环、退避、租约、并发上限。
ProbeModelKey(超时覆盖、context、严格校验)。UnbanModelKeyIfAuto+ CAS。BanManagerModal展示来源/探测/跳过原因。updateKey改 key 值时清 auto 禁用。- 全部单测 +
go vet+-race。
二期
- 按模型覆盖:
model.probe_enabled/model.probe_interval_s/model.probe_types。 - 声明式探测覆盖:
probe_path/probe_method/probe_body/probe_expect_status。 - flap 窗口抑制与组合级恢复日志(可查询)。
- 探测历史表(用于统计恢复耗时、成功率),而不是只保留最后一次。
- 按错误类型自适应间隔(例如 404 直接 24h、5xx 正常退避)。
三期(仅在确有需求时)
- Webhook 型外部探针:让用户提供一个返回 2xx 的 URL,而不是执行脚本。
- 多实例共享探测结果缓存(类似 LiteLLM 的 Redis shared health state)。
17. 待确认决策
| # | 决策 | 建议 | 备选 |
|---|---|---|---|
| D1 | 默认模式 | banned_any + degraded_multiplier=4 | disabled_only(成本更低,但部分禁用组合会卡住) |
| D2 | 默认基础间隔 | 全禁用 300s,降级 1200s | 全禁用 600s(更省) |
| D3 | 401/403 是否默认探测 | 否 | 是(每 5 分钟敲一次死 key,风险较高) |
| D4 | 默认参与类型 | chat / embedding / rerank | 加入 image/tts/stt(会产生真实费用) |
| D5 | video | 固定排除 | 允许配置(会真实提交渲染,不建议) |
| D6 | 改动 key_value 时清 auto 禁用 | 是 | 否(用户需手动解禁) |
| D7 | 恢复通知 | 复用 model.recovered,不新增组合级通知 | 新增 combo.recovered(易刷屏) |
| D8 | 探测脚本 | 不做,保留声明式覆盖 | 支持 shell 脚本(密钥泄露面 + 可移植性问题) |
| D9 | 循环位置 | 新包 internal/recovery,与 notify 并行 | 并入 notify 的 30s 扫描(慢 I/O 会拖长通知延迟) |
附录 A:与同类产品的对照
| 产品 | 自动禁用 | 自动恢复 | 探测方式 | 关键细节 |
|---|---|---|---|---|
| one-api | 401 / 额度 / 认证 / 余额关键词 | AutomaticEnableChannelEnabled,定时测试通过即启用 | 真实请求,顺序执行 | 状态枚举区分手动/自动禁用,但 ShouldEnableChannel 未检查状态,定时测试可能把手动禁用也重新启用 |
| new-api | 状态码区间 / 关键词 / 响应时间阈值 | 仅 ChannelStatusAutoDisabled,测试通过即启用 | 真实请求(走 relay,消耗测试用户额度) | 模式 scheduled_all / auto_ban_only / passive_recovery;恢复模式 allowDisable=false;并发 1–32;system task 租约防多实例重复;跳过 Midjourney/Suno/Kling/视频等昂贵类型 |
| LiteLLM | 默认无永久禁用;失败达 allowed_fails=3 进入 cooldown | cooldown TTL 到期自动恢复(默认 5s) | 可选后台健康检查(默认 300s,真实调用,health_check_max_tokens 限制输出) | 401/402/408/404/429/5xx 冷却,其余 4xx 不冷却;按 deployment 可关闭健康检查;Redis 共享健康状态 |
| OmniGate(本方案) | 组合级:401/403 立即永久;可重试失败达阈值永久;429 短冷却 | 仅 origin=auto 的组合,探测成功 CAS 解禁 | 内置最小真实请求(复用现有 7 类载荷,自动恢复只用 chat/embedding/rerank) | 手动禁用永不恢复;认证错误默认不探;昂贵类型默认排除;多实例按组合租约;探测失败不加重禁用 |