多 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 就不会再从环境变量悄悄回来。