跳到主要内容

状态:设计中 / 实现中。 这一页是设计稿,描述定时探测被自动禁用的 模型×密钥 组合并自动解禁的机制。配置与行为以当前版本代码为准。

定时探测与自动解禁(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 目前把三种来源混在一起:

  1. 失败归因产生的永久禁用;
  2. 管理员手动禁用单个组合;
  3. 管理员手动禁用整个模型(实现上是对当时绑定的每个组合写 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 语义​

值写入点
autoRecordModelKeyFailure、RecordModelKeyRateLimited、BanAllModelKeys 之外的自动路径;旧数据默认值
manualBanAllModelKeys(模型级手动禁用)、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_enabledboolfalse-总开关
probe.modestringbanned_anybanned_any | disabled_only候选范围,见 §6
probe.interval_sint30060–86400模型全禁用时的基础探测间隔
probe.degraded_multiplierint41–24模型仍有可用组合时的间隔倍数(默认 20 分钟)
probe.timeout_sint151–300单次探测超时;同时压住提供商默认 120s
probe.max_concurrencyint21–16全局并发探测上限
probe.max_per_cycleint201–200每轮最多探测数,防止启动后一次性打满
probe.max_interval_sint360060–86400指数退避上限,且必须 ≥ probe.interval_s
probe.recover_authboolfalse-是否探测 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 行成为候选,必须同时满足:

  1. status = 'perm_banned';
  2. origin = 'auto';
  3. model_key 行仍存在(组合仍被绑定);
  4. api_key.provider_id = model.provider_id(与 router.Selector、store.ModelHealth 同口径;跨提供商的绑定路由根本不收);
  5. 模型类型在 probe.types 中;
  6. probe.recover_auth = true,或 last_error 不是 401/403;
  7. 已到探测时间(见 §6.2);
  8. 租约可用(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

内部:

  1. 加载 model / provider / key,校验 model_key 绑定与 key.provider_id == model.provider_id;
  2. 复制 provider,把 TimeoutMs 压到 opt.Timeout;
  3. 调用现有 probeModelKey;
  4. 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 之一
embeddingdata 数组非空
rerankresults 数组非空
imagedata 或 images 非空
audiobody 非空(沿用现有判断)

不满足时视为探测失败(last_probe_error = "invalid_response"),不解禁,并记录一条截断后的响应预览(不含密钥)。

7.5 并发​

  • 全局信号量 probe.max_concurrency;
  • 每轮最多 probe.max_per_cycle 个候选;
  • 同一模型内串行(避免对同一上游同时打多个请求),不同模型可并行;
  • 每轮对候选做一次随机打散,并给 dueAt 加 ±10% 抖动,避免所有模型整点一起探。

7.6 为什么不做用户脚本​

结论:不做。理由按重要性排序:

  1. 脚本拿不到完整的成功语义。真正要验证的是“这把 key 经这套协议适配、这个 base_url、这个模型,现在能不能返回可用响应”。脚本只能自己重新实现鉴权、协议转换、代理和解析,每个 provider 一份,且容易与代理真实行为不一致。
  2. 密钥泄露面。脚本需要密钥原文;走 argv/env 会被同机其他用户从 ps 看到。把密钥交给用户可控代码,等于在网关进程里开了一个任意代码执行入口。
  3. 可移植性。Windows 没有 sh;还要处理解释器、超时、进程树、退出码语义。
  4. 现有能力已经覆盖。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 通知。

本期用三个机制压住:

  1. 真实流量要连续失败 3 次才重新永久禁用(现有阈值);
  2. 探测失败指数退避;
  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.goModelKeyBan 新增列;ManualBanReason 常量
internal/store/store.go迁移序列后调用 migrateBanOrigin
internal/store/probe.go(新增)ProbeCandidate、ListProbeCandidates、UpdateProbeFailure、ClaimProbeLease、migrateBanOrigin
internal/breaker/breaker.goUnbanModelKeyIfAuto;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.goRuntime 字段、settingSpecs、解析、strEnum 校验器
internal/api/models.gomodelKeyBanItem 追加字段与 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_only vs banned_any、全禁用快探 / 降级慢探、探测期间被手动禁用(CAS 不删)。
  • config
    • mode 枚举、types 子集、max_interval_s >= interval_s、video 拒绝。
  • api
    • /api/models/{id}/bans 返回新增字段与 ProbeEligible 文案;旧字段不变。

13.2 集成与手动验收​

  1. 建一个模型 + 两把 key;手动把其中一把 perm_banned(origin=auto),开启探测,把间隔调到 60s,确认只探这一把、成功后行消失。
  2. 把两把都设为 401 禁用,确认默认不探;打开 recover_auth 后开始探,并退避到上限。
  3. 探测期间通过管理台手动禁用该组合,确认探测成功后不会删掉 manual 行。
  4. 共享 MySQL 起两个实例,确认同一组合同一时间只有一个实例在探(日志/租约)。
  5. 关闭总开关,确认没有任何出站请求。

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,建议本次实现)​

  1. origin 列 + 迁移回填;手动写入口改为 manual。
  2. model_key_ban 探测状态列。
  3. 配置项与校验、Settings 分区。
  4. 候选查询、循环、退避、租约、并发上限。
  5. ProbeModelKey(超时覆盖、context、严格校验)。
  6. UnbanModelKeyIfAuto + CAS。
  7. BanManagerModal 展示来源/探测/跳过原因。
  8. updateKey 改 key 值时清 auto 禁用。
  9. 全部单测 + 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=4disabled_only(成本更低,但部分禁用组合会卡住)
D2默认基础间隔全禁用 300s,降级 1200s全禁用 600s(更省)
D3401/403 是否默认探测否是(每 5 分钟敲一次死 key,风险较高)
D4默认参与类型chat / embedding / rerank加入 image/tts/stt(会产生真实费用)
D5video固定排除允许配置(会真实提交渲染,不建议)
D6改动 key_value 时清 auto 禁用是否(用户需手动解禁)
D7恢复通知复用 model.recovered,不新增组合级通知新增 combo.recovered(易刷屏)
D8探测脚本不做,保留声明式覆盖支持 shell 脚本(密钥泄露面 + 可移植性问题)
D9循环位置新包 internal/recovery,与 notify 并行并入 notify 的 30s 扫描(慢 I/O 会拖长通知延迟)

附录 A:与同类产品的对照​

产品自动禁用自动恢复探测方式关键细节
one-api401 / 额度 / 认证 / 余额关键词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 进入 cooldowncooldown 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)手动禁用永不恢复;认证错误默认不探;昂贵类型默认排除;多实例按组合租约;探测失败不加重禁用