返回博客

多 Key 轮询与冷却

每个上游最多 16 把 Key,逐请求轮询;失败后按错误类型进入冷却,而不是简单地继续轮询。

如果你给同一个上游配了多把 Key,Free Router 不会把它们全部塞给同一个请求。它按请求轮询,并且在失败时让那把 Key 暂时退出轮询。

轮询

每家上游最多 16 把 Key。网关为每家上游维护一个并发安全的游标,每次请求取一次起点:

start = (cursor += 1) % key_count

然后从这个起点依次尝试。一把 Key 在一个请求里最多被试一次,不会反复重试同一把。

这个设计的直接后果是:只要上游的限流是按 Key 计的,配更多 Key 就能摊薄单把 Key 的压力。

冷却

失败不是简单地“跳过这一次”。网关会根据错误类型给这把 Key 设一个冷却时间:

错误 冷却时长
401 / 403 300 秒
429 / 5xx 30 秒
连接失败 5 秒

如果上游在 429 响应里带了整秒的 Retry-After,以它为准。

几个细节值得知道:

  • 冷却只会延长,不会缩短。 一次新的失败会把剩余时间往后推,但不会因为某次响应更快就提前放行。
  • 成功会清空冷却。 这把 Key 下一次被轮到时照常参与。
  • 冷却中的 Key 会被直接跳过,不会浪费一次请求。
  • 如果一家上游的 Key 全都在冷却,网关返回 503,并带上最早的 Retry-After。它不会原地等待。

冷却时长可以用 GATEWAY_KEY_COOLDOWN_SECS 统一覆盖(上限 86400 秒,设为 0 表示关闭冷却)。默认值对大多数场景是合适的,遇到了再调。

增删改不用重启

在 Settings 里添加、删除或调整 Key 的优先级会立即生效。CLI 也是一样:

free-router keys list
free-router keys add
free-router keys remove

密钥不会被回显

界面和 GET /api/status 都不会返回密钥原文。它们返回的是不可逆的标识符(key_<sha256 前缀>)、一个 Key N 标签,以及冷却剩余秒数。

保存的密钥在配置目录的 settings.local.json 里,权限 0600。前端不回显已保存的上游密钥,也不会把它们写进浏览器存储。

环境变量只是种子

OPENROUTER_API_KEY 这类环境变量用于初始化密钥池。一旦你在 Settings 里保存过配置,Settings 的值优先——包括你把某一把 Key 清空的情况。清空之后,那把 Key 就不会再从环境变量悄悄回来。