Files
ipass__ipass/docs/llm/MULTI_ACCOUNT_ROUTING.md
T
admin 1bc316e014 fix(stats): 「上次落盘」记录移入共享内存(1.0.19)
1.0.18 首次线上验证暴露:error.log 里有 10 次 [stats] 落盘(来自 6#0/18#0/23#0
多个 worker),GET /api/admin/stats/persist 却报「本进程还没落过」。

根因:LAST_DUMP_AT 是每 worker 的进程内静态量。maybe_dump() 挂在记账路径上,
而记账每 worker 各算各的 → 落盘时刻也就每 worker 一份;接口落到没落过盘的
worker 就报 0。与 1.0.18 已修过的 spr:last(上次恢复)是同一类错误。

修法:发布到共享内存 spd:last(publish_dump 取 max)。一次解决两件事:
* 上报一致 —— 所有 worker 报同一份;
* 节流收敛 —— maybe_dump 新增慢路径查它,把「8 个 worker 各写一遍同一个文件」
  收敛成「全局每间隔一次」。快路径仍是原子比较,热路径代价不变。

顺带:
- 新增回归断言「状态页报告的上次落盘时刻非空」(套件开 2 worker,能暴露该分歧)
- deploy/agent.sh 加 stats-persist / stats-dump 子命令(线上观测口)
- 统一文档里过期的断言条数(90/111/160/179/196/262/298 → 实际值)
- 记录审计容量巡检 LAST_PURGE_AT/PURGING 同为每 worker 静态量(另案)

回归:bash tests/run.sh all → 299 条全绿(网关 102 + LLM 197)。
2026-09-14 20:05:51 +08:00

13 KiB
Raw Blame History

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)

{
  "minimax": {
    "base": "https://api.minimax.chat/v1",
    "models": ["abab6.5s-chat"],
    "enabled": true,
    "accounts": [
      {"auth": "Bearer <key1>", "note": "acct-1", "resets": [604800, 18000]},
      {"auth": "Bearer <key2>", "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)。只填裸 key 也行——读出时 normalize_auth 自动补 Bearer ,避免上游回 1004(详情见 §10)
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:<downstream_key>  → 已有账号下标
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:<slot> base \n <naccounts> 上游基址 + 账号数
upa:<slot>:<idx> auth \n <resets csv> 单账号 auth + 重置周期
uac:<slot>:<idx> exhausted_until 冷却截止(TTL = until,自然到期即视为恢复)
ukb:<downstream_key> acct_idx 粘性绑定(TTL = max resets)
upe:<slot> status_csv \n markers_json 上游级耗尽检测配置
uda:<slot>:<idx>:<day> requests:tin:tout(DayBucket) 账号级负载日桶(TTL 90 天)
uex:<slot>:<idx>:<day> 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 展示(管理台「上游」页 · 密钥 / 负载 列)

上游页密钥/负载列

(示意图,数据为构造值;含双 Key 轮换上游、单 Key 老记录、无账号上游三种形态)

每个上游账号一块:

  • 今日负载行:今日 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 条;条数随迭代增长, 当前见 CLAUDE.md「本机验证夹具」一节)。 假上游 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 错误。

十、auth 规范化(兜住「只填裸 key」的历史坏数据)

适用版本:ipass-1.0.15+

现象

线上某 slot(如 minimax)管理台「密钥」列能看到 accounts[],但点「测试」按钮上游回:

minimax 不通:login fail: Please carry the API secret key in the
'Authorization' field of the request header (1004)  (195 ms)

1004 是 MiniMax 的「缺鉴权头」错误码,与额度耗尽无关。原因:表单 placeholder 写的是 sk-...,用户照着填了裸 key,而 accounts[].auth 字段语义是「完整的 Authorization 头值」——转发时网关原样发出 Authorization: sk-cp-...,上游只认 Bearer sk-cp-..., 于是 1004。唯一让用户感知到的现象就是「测试按钮红字」——靶机层面的真实状态码与 厂商错误体都看不到(管理台没回显原始 body;点「测试」之前的旧版本会回 401 而非厂商原话, 更易让人误判成「Key 失效」)。

解决:normalize_auth

plugin-llm/src/upstreams.rs 新增 normalize_auth(auth: &str) -> String, 两处应用:

  1. 写入(upsert):用户保存时若填了裸 key(无空格),自动补 Bearer 前缀存盘—— 历史坏数据在下次保存时归正,无需用户手动重填。
  2. 读出(read_upa):转发时不管盘上存的是「裸 key」、「已带 Bearer」还是「Basic 自定义」, 读出即归一化后发往上游——这一道是给存量坏数据用的兜底,免去强制让用户重存的运维。

规则

输入 输出 说明
""(空) "" 未配 Key 是合法状态
sk-cp-xxx(裸 key) Bearer sk-cp-xxx 兜住"只填裸 key"
Bearer sk-cp-xxx Bearer sk-cp-xxx 已完整,不动
Basic dGVzdA== Basic dGVzdA== 非 Bearer scheme 也放过
sk-cp-xxx Bearer sk-cp-xxx trim 后判定
Bearer sk cp Bearer sk cp 含空格 = 已完整,不动

判定逻辑一句话:「trim 后还含空白字符 → 视为已完整;否则补 Bearer 」。

自检工具

发版后用控制面脚本自助验证(不靠用户点管理台按钮):

bash deploy/agent.sh upstreams                  # 逐账号 Authorization 掩码 + 冷却 + 今日负载
bash deploy/agent.sh upstream-test minimax      # 真实打上游 → 打印 status_code + 厂商响应体

upstreams 输出的「掩码为空 → 显式标 **空**」是发现这类问题的关键指示器:旧镜像没有这个 输出(直接回脱敏后的掩码,肉眼对比看不出问题),新镜像会显式标红。