# LLM 上游多账号路由与额度耗尽自动切换 > 适用版本:`ipass-1.0.14`(插件化后的 `plugin-llm`)。 > 涉及文件:`rust/crates/plugin-llm/src/{models,upstreams,llm,usage_filter,handlers,api}.rs`、 > `conf/nginx.conf`(LLM server)、`tests/llm/{e2e.sh,upstream.py,fixtures/llm-upstreams.json}`。 --- ## 一、解决什么问题 同一上游厂商(如 MiniMax)往往给**多个账号 Key**,且额度按周期清零(MiniMax 是 「每周清零 + 每 5 小时清零」)。本特性让一个 `slot`(上游)挂多个账号,做到: 1. **下游用户 Key → 上游账号 Key 粘性绑定**:同一下游 Key 尽量一直走同一个上游账号 (便于对账、便于厂商侧按账号看用量),但这是**尽力语义**——重启后重新绑定。 2. **额度耗尽自动切换**:某上游账号被厂商判额度耗尽,下次请求自动切到同厂商下一个可用账号。 3. **重置窗口感知**:额度按周期清零,冷却时长取「最近一个重置边界」,不盲目冷却整段固定时间。 --- ## 二、数据模型(`llm-upstreams.json` 的 slot) ```json { "minimax": { "base": "https://api.minimax.chat/v1", "models": ["abab6.5s-chat"], "enabled": true, "accounts": [ {"auth": "Bearer ", "note": "acct-1", "resets": [604800, 18000]}, {"auth": "Bearer ", "note": "acct-2", "resets": [604800, 18000]} ], "exhaust_status": [401, 402, 429, 403], "exhaust_markers": ["\"status_code\":1004", "余额不足"], "created_at": 1757500000 } } ``` | 字段 | 含义 | |---|---| | `accounts` | 多账号数组。**取代旧版单 `auth` 字段**;`accounts` 为空时由顶层 `auth` 兼容合成单账号 | | `accounts[].auth` | 完整的 `Authorization` 头值(如 `Bearer sk-xxx`)。留空表示免鉴权后端 | | `accounts[].note` | 备注(如「华东主账号」),仅展示 | | `accounts[].resets` | 该账号的**额度重置周期(秒)数组**,如 `[604800, 18000]` = 周 + 5 小时。全空=不自动切换 | | `exhaust_status` | 命中即判「额度耗尽」的 HTTP 状态码(**上游级,所有账号共用**)。如 `[401,402,429,403]` | | `exhaust_markers` | 响应体含任一子串即判耗尽(逐字节匹配,大小写敏感)。用于厂商「HTTP 200 + body 报错」的场景 | > **敏感级别等同 `users.json`**:`accounts[].auth` 含上游真 Key,配置文件不入库 / 不进 Gitea raw。 --- ## 三、路由逻辑(access 阶段 `pick_account`) ``` 1. 查下游 Key 的粘性绑定 ukb: → 已有账号下标 2. 无绑定 → FNV-1a(key) % 可用数 → 冷分散(不是固定 avail[0],也不是随机) 3. 绑定账号在冷却中 → 跳过,按下流 key 在剩余可用里重新分散 4. 全部冷却中 → 选「最早恢复」的账号(min cool_until) 5. 选定后写/刷新 ukb 粘性绑定(TTL = max(resets),兜底 7 天) ``` ### 3.1 冷分配为什么用「键哈希」而不是「随机」或「固定第 0 个」 三者要同时满足两个看似矛盾的目标: | 目标 | 为什么需要 | |---|---| | **均匀铺开** | MiniMax 这类厂商对**单账号有 agent 并发上限**。若所有下游 Key 都落 `account#0`,一把 Key 被打满、同 slot 的其它 Key 却闲着 | | **分配后保持** | 同一用户的请求若被轮到不同上游账号,**prompt / token 缓存前缀对不上 → 缓存命中率暴跌**,等于白缓存 | - **固定 `avail[0]`**:满足「保持」但不满足「铺开」——全部压在第一个账号。 - **随机分配**:满足「铺开」但不满足「保持」——同一用户每次请求都可能换账号,缓存必然失效。 - **FNV-1a(key) % n**:`key` 固定 ⇒ 落点固定(满足保持);不同 `key` 哈希值不同 ⇒ 落到不同账号(满足铺开)。 且**确定性可复现**——本机回归能用同一段哈希精确预测首次落点,不必依赖全局随机源。 (随机源仅在**没有下游 Key** 时兜底:管理台「测试」按钮这类内部探测流量走 `ngx_random()`,不要求粘性。) ⚠️ 分散是**冷分配时选一次**,之后由 `ukb:` 绑定固定住;绑定账号冷却被跳过时会在剩余可用账号里按同一哈希重新分散。 - **粘性仅共享内存**:重启后绑定丢失,下次请求重新冷分配,符合「尽可能同一 Key 用同一上游 Key」的尽力语义。 --- ## 四、耗尽检测(log 阶段,双重保险) | 来源 | 机制 | 适用场景 | |---|---|---| | HTTP 状态码 | 读 `$upstream_status` 末段,命中 `exhaust_status` → 标记 | 厂商直接回 401/402/429/403 | | 响应体标记 | `usage_filter` 在 body **流式**扫描 `exhaust_markers`,`take_exhausted` 透给 log | 厂商「HTTP 200 + body 报错」(如 MiniMax `status_code:1004`) | 任一命中 → 读 `$llm_acct`(本次 access 阶段选中的账号下标,确定一致)→ `mark_exhausted(slot, idx, resets)` 写冷却。 --- ## 五、冷却窗口(天锚定,关键) `cool_until_until(resets, now)` 的边界计算**锚定到「当天的 0 点」**,而非简单 `now + 窗口` 滚动: ``` day0 = RESET_DAY_OFFSET_SEC + floor((now - RESET_DAY_OFFSET_SEC) / 86400) * 86400 elapsed = now - day0 boundary = day0 + ceil(elapsed / 窗口) * 窗口,且封顶到 day0 + 86400(次日 0 点) ``` **为什么必须天锚定**(MiniMax 实测口径): MiniMax 的 5 小时额度从当天 0 点起每 5h 清一次,但 `24 = 5×4 + 4`—— 最后一段窗口 `20:00–24:00` **只有 4 小时**,到点随「天」一起重置。 如果简单 `now + 5h` 滚动,21:00 耗尽会冷却到次日 01:00,与厂商口径对不上; 天锚定后封顶到当日 24:00(差 3h),与厂商行为一致。 - `RESET_DAY_OFFSET_SEC`(默认 `28800` = 北京时间)让 MiniMax 描述的开箱即用;其他时区厂商改成 `0` 即可。 - **多窗口取最早恢复**:`resets=[604800, 18000]` 时,周额度与 5h 额度哪个先恢复用哪个。 - `resets` 全空 → 兜底滚动冷却 `ACCT_COOLDOWN_DEFAULT = 4h`。 --- ## 六、共享内存布局 | 键 | 值 | 说明 | |---|---|---| | `up:` | `base \n ` | 上游基址 + 账号数 | | `upa::` | `auth \n ` | 单账号 auth + 重置周期 | | `uac::` | `exhausted_until` | 冷却截止(TTL = until,自然到期即视为恢复) | | `ukb:` | `acct_idx` | 粘性绑定(TTL = max resets) | | `upe:` | `status_csv \n markers_json` | 上游级耗尽检测配置 | | `uda:::` | `requests:tin:tout`(`DayBucket`) | 账号级负载日桶(TTL 90 天) | | `uex:::` | `requests`(=耗尽次数) | 账号级额度耗尽次数日桶(TTL 90 天) | 写操作均写穿共享内存;停用(`enabled=false`)即摘 `up:` 条目,热路径「查不到=停用」。 --- ## 七、账号级负载统计(问题发现与跟踪) **为什么用共享内存日桶而不是数据库**:项目红线是「不引入数据库 / Redis / MQ / 额外常驻进程」。 而负载统计本质是**每请求计数器**——nginx 共享内存 zone 正是为此而生(worker 间天然共享、 原子、TTL 自动淘汰、无文件锁);换成 SQLite 反而要在多 worker 下处理 WAL 与 busy_timeout 的写锁竞争, 在网关热路径上是退步。账号级只是给已有的上游级日桶(`uds:`)**多一维下标**, 完全复用内核 `ipass_core::usage` 的 `bump_day` 原语,零新依赖、零新文件。 ### 7.1 计数点:**log 阶段**,且只记一次 ``` access : pick_account 只做决策,不记账 ($llm_target / $llm_auth / $llm_acct 三个变量各触发一次 pick_account, 在这里记账会把同一请求记三遍) proxy : nginx 原生转发 log : read_llm_acct(r) 取本次选中账号(NOCACHEABLE,与 access 同一结果) → bump_acct_load(slot, idx) 每次真实转发 +1 → 命中耗尽 → bump_acct_exhaust(...) +1 → body filter 抓到 usage → add_acct_tokens(...) ``` 口径与请求级用量一致:**只算真的转发出去的请求**(被拒的 401/403/404/429 不入账)。 ### 7.2 展示(管理台「上游」页 · 密钥 / 负载 列) 每个上游账号一块: - **今日负载行**:`今日 N 请求 · 入 X / 出 Y tok` - **比例条**:该 Key 占「本上游负载最大的 Key」的百分比——**本上游内部相对量**最有信息量, 谁在扛、有没有偏斜一眼可见(不占全局总量,否则多上游场景下每根条都很短) - **14 天迷你趋势**:后端 `account_trend()` 按日窗 id 精确取键渲染(零第三方依赖的 SVG), 悬停给出「近 14 天合计 / 峰值 / 峰值日期」 - **徽标**:`冷却`(`uac:` 键存在)、`耗尽N`(今日被判耗尽并冷却的次数,来自 `uex:`) - 上游级一行合计:`N 把 Key · 今日合计 M 请求` 账号级序列**不参与任何转发决策**,纯展示;`view()` 投影见 `upstreams::view`。 --- ## 八、管理台 - `www/assets/upstreams.js` 编辑卡支持**多账号行**:每行 auth(掩码回显)、note、resets(逗号分隔周期)。 - 列表「密钥 / 负载」列展示账号数、冷却/耗尽状态与**各 Key 今日负载 + 比例条 + 14 天迷你趋势**(见 §七)。 - 保存接口 `POST /api/admin/upstreams/save` 接受 `accounts`(JSON 数组); auth 留空=保留原值(编辑时不用每次重填真 Key)。 --- ## 九、验证 - **本机回归**:`tests/llm/e2e.sh` 多账号组(粘性 + 耗尽自动切换 + 靶机真收 Key + 账号级负载分布), 全量 `bash tests/run.sh all` 期望 **279 条断言全绿**(gateway 102 + llm 177)。 假上游 `upstream.py` 支持 `UPSTREAM_FAIL_AUTH` 环境变量模拟「账号额度耗尽」。 - **真 MiniMax 双 Key 实测**:key1 稳定 200 + 粘性 `acct=0`;key1 失效 → 自动切 key2(`acct=1`,200)。 真 Key 仅存临时目录、测完即删,不入库。 - **前端渲染**:以真实 `admin.css` + 真实 `upstreams.js` 渲染路径做无头浏览器断言—— 比例条宽度与负载成比例(412 vs 96 → 100% / 23%)、每账号 14 个条块、悬停峰值日期与数据逐位吻合、 单账号老记录与无账号上游兜底正常、无横向溢出、零 JS 错误。