Files
ipass__ipass/docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md
T
admin bfa3cf8ff8 feat(llm): 上游多账号路由 + 账号级负载统计 (1.0.14)
一个 slot 挂多把上游账号 Key,解决厂商「单账号额度/并发受限」与
「同一用户缓存命中」两个矛盾诉求。

多账号路由 (plugin-llm)
- models: Upstream.accounts[] (auth/note/resets) + 上游级
  exhaust_status/exhaust_markers;顶层 auth 保留兼容(accounts 为空时合成单账号)
- upstreams::pick_account:粘性绑定 ukb:<key> 优先 → 无绑定时
  FNV-1a(下游 Key) % 可用数 冷分散 → 绑定账号冷却则重新分散 → 全冷却取最早恢复
  * 分散避开厂商单账号 agent 并发上限;落点固定保住 prompt/token 缓存
- cool_until_until 天锚定冷却:boundary = day0 + ceil(已过/窗口)*窗口,
  封顶次日 0 点(MiniMax 5h 窗口、24=5*4+4 → 末段 20:00-24:00 只有 4h 随天重置)
- 耗尽双检测 (log 阶段):$upstream_status 命中 exhaust_status,或
  usage_filter 流式扫到 marker → $llm_acct 定位本次账号 → 写冷却 uac:
- shm: up:/upa:/uac:/ukb:/upe: 五类前缀;$llm_acct 变量 (NOCACHEABLE)

账号级负载统计(问题发现与跟踪)
- 新增 uda:<slot>:<idx>:<day>(请求/token)与 uex:(耗尽次数) 日桶,
  复用内核 usage::bump_day —— 无数据库、无新进程(项目红线)
- 计数点只在 log 阶段一次;pick_account 会被 $llm_target/$llm_auth/$llm_acct
  三个变量各触发一次,放进那里会三倍计数
- view() 投影带每账号 load 与 account_trend + trend_labels(日期由后端算)
- 管理台「上游」页密钥列:各 Key 今日请求/token/耗尽 + 负载比例条 +
  14 天迷你趋势(自绘 SVG,零第三方依赖)+ 冷却/耗尽徽标 + 上游合计

测试与验证
- 回归 279 条全绿(网关 102 + LLM 177),新增 6 条多账号/负载断言
- 假上游新增 UPSTREAM_FAIL_AUTH 模拟账号额度耗尽;靶机验证 Key 真被替换
- 前端以真实 admin.css + upstreams.js 渲染路径做无头浏览器断言:
  比例条与负载成比例(412 vs 96 → 100%/23%)、每账号 14 条块、
  悬停峰值日期与数据逐位吻合、单账号/无账号兜底正常、无横向溢出、零 JS 错误

文档
- 新增 docs/llm/MULTI_ACCOUNT_ROUTING.md(数据模型/路由/冷却数学/shm 布局/负载统计)
- readme §11 数据模型 + §15 上游配置 + §15 用量统计 + §12.6 tag 表 + §16 变更记录
- 修正 docs/llm/*.md 中插件化前的过时路径(rust/src/* → crates/plugin-llm/src/*)
2026-09-14 11:57:08 +08:00

17 KiB
Raw Blame History

LLM 多协议网关:上游路由与鉴权头的成熟做法

调研日期 2026-09-12。目的:回答「上游同时有 OpenAI 与 Anthropic 两套协议时, 统一注册再分发、还是注册两条」,以及「网关 Key 经请求头泄漏给上游」怎么修。 结论全部来自开源实现或厂商官方文档,并附本机靶机实测证据(本项目硬规矩: 验证请求头替换必须看上游收到的请求)。

涉及文件:conf/nginx.conf(LLM server)、rust/crates/plugin-llm/src/llm.rs、 rust/crates/plugin-llm/src/upstreams.rs、tests/llm/upstream.py

路径说明:ipass-1.0.12 插件化重构后,原 rust/src/llm.rs / rust/src/upstreams.rs 已迁入 rust/crates/plugin-llm/src/(本文其余段落若提到旧路径,按此对应)。 多账号路由与账号级负载统计见 docs/llm/MULTI_ACCOUNT_ROUTING.md。


一、结论速览

问题 成熟做法 我们的对应
协议怎么区分 路径,三个主流网关一致 已有:slot 在前 + 客户端路径在后
要不要网关分发 不要。「统一注册」= 一条记录 + base 写到 host 改 base 粒度即可,零代码
出站凭据头 默认不放行(allowlist)或按「哪个头用于网关鉴权」摘除 待改:现在漏 x-api-key
客户端该用哪个变量 Anthropic 官方:走网关用 ANTHROPIC_AUTH_TOKEN 文档引导即可

二、三个开源方案的实际做法

2.1 LiteLLM(最主流,Python)

协议路由:路径前缀即 provider 路由。官方文档原话—— "Anything after http://0.0.0.0:4000/anthropic is treated as a provider-specific route"。 客户端把 https://api.anthropic.com 换成 {网关}/anthropic,其余路径照抄。

鉴权头(litellm/proxy/litellm_pre_call_utils.py,真实源码):

# clean_headers() —— 决定哪些头**能**被转发
for header, value in headers.items():
    header_lower = header.lower()

    if header_lower == "authorization" and is_anthropic_oauth_key(value):
        # 只有「不是用来做网关鉴权的那把」才转发
        if authenticated_with_header is None or authenticated_with_header.lower() != "authorization":
            clean_headers[header] = value
        continue
    elif header_lower == "x-api-key":
        # 默认不转发;仅 BYOK 且「不是网关鉴权用的那个头」才转发
        if forward_llm_provider_auth_headers and (
            authenticated_with_header is None or authenticated_with_header.lower() != "x-api-key"
        ):
            clean_headers[header] = value
    elif forward_llm_provider_auth_headers and header_lower in _SPECIAL_HEADERS_CACHE:
        if litellm_key_lower and header_lower == litellm_key_lower:
            continue
        if header_lower == "authorization":
            continue          # ★ Authorization 永不转发给上游
        if header_lower == "x-litellm-api-key":
            continue
        clean_headers[header] = value
    elif header_lower not in _SPECIAL_HEADERS_CACHE and (
        litellm_key_lower is None or header_lower != litellm_key_lower
    ):
        clean_headers[header] = value
# _get_forwardable_headers() —— 第二层:allowlist
for header, value in headers.items():
    if (
        header.lower().startswith("x-")
        and not header.lower().startswith("x-stainless")   # 会让 OpenAI SDK 出错
        or header.lower().startswith("anthropic-beta")
    ):
        forwarded_headers[header] = value

三条可直接借用的原则:

  1. authenticated_with_header —— 记录「客户端用哪个头做了网关自身鉴权」, 那个头绝不转发。比按名字硬编码精确:同一个 x-api-key,用来过网关时要摘掉, 作为 BYOK 凭据时要转发,区别就在这里。
  2. 默认摘除凭据头,官方文档明确列了 x-api-key / x-goog-api-key / api-key, 理由是 "these are typically used to authenticate with the proxy itself"。
  3. 双层防护:clean_headers 先摘凭据头,_get_forwardable_headers 再 allowlist (只放行 x-* 与 anthropic-beta)。且日志副本走 redact_credential_headers() 把凭据值替换成 ***REDACTED***,转发的副本保留真值 —— 凭据与可观测性两副本分离。

BYOK(客户端自带厂商 Key)是显式开关:forward_llm_provider_auth_headers: true。

2.2 one-api / new-api(国内主流,Go)

路由:客户端 ANTHROPIC_BASE_URL 指向网关根,路径天然区分 (/v1/messages 是 Anthropic、/v1/chat/completions 是 OpenAI); model 字段只用于选 channel,不用于判协议。

官方 README 给的 Claude Code 用法:

export ANTHROPIC_BASE_URL="https://oneapi.laisky.com/"   # 根,不带 /anthropic
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxx"                  # 注意用的是 AUTH_TOKEN

鉴权头(relay/adaptor/anthropic/adaptor.go):出站同时设三个头 —— x-api-key: <上游真Key> + anthropic_version + Authorization: Bearer <上游真Key>。 即入站的客户端凭据被完全替换,不存在"另一个头漏过去"。

它的 adaptor 接口把「建 URL / 设鉴权头」拆成 GetRequestURL() / SetupRequestHeader() 两个独立职责,与我们 llm.rs 的 $llm_target / $llm_auth 分工一致。

2.3 Higress(阿里,Envoy/Wasm,CNCF Sandbox)

协议路由:官方文档称 Automatic Protocol Detection —— "allowing it to simultaneously handle OpenAI and Claude protocols without explicit configuration"。

值得注意的是它的演进方向:v2.2.3 release notes 提到 「Claude API 名称识别从宽泛匹配改成更准确的后缀判断(#3839),减少同一套客户端换个模型就出现异常 400 的概率」。

即:从"猜"(按模型名)改成"看确定判据"(按路径后缀)。这正是不该按 body 猜协议的权威背书。

同版本还有一条:「AI Proxy 支持 vLLM 透传 Anthropic Messages 和新版 OpenAI endpoints(#3989)。 能原样透传的请求不再做多余转换,链路更短,排查也更轻。」—— 与我们的纯透传定位一致。


三、决定性事实:Anthropic 官方对网关场景的指引

Claude Code 官方文档(code.claude.com/docs/en/authentication)原文:

ANTHROPIC_AUTH_TOKEN environment variable. Sent as the Authorization: Bearer header. Use this when routing through an LLM gateway or proxy that authenticates with bearer tokens rather than Anthropic API keys.

ANTHROPIC_API_KEY environment variable. Sent as the X-Api-Key header. Use this for direct Anthropic API access with a key from the Claude Console.

这条改变了问题的定性:

  • Claude Code 走网关的正确姿势就是 ANTHROPIC_AUTH_TOKEN → 发 Authorization: Bearer, 根本不会发 x-api-key。所以「支持 x-api-key 入站」不是必需能力,是兼容 bonus。
  • 反过来说,客户端发 x-api-key 只有两种情形:(a) 用户把网关 Key 错放进 ANTHROPIC_API_KEY; (b) 真的有客户端偏好这个头。两种情形下漏给上游都是缺陷,不是"预期行为"。
  • 所以修法优先级:出站摘除(必做)> 文档引导用户用 ANTHROPIC_AUTH_TOKEN(配套)。

四、本机靶机实测(证据)

靶机 tests/llm/upstream.py 改为记录全部收到的头(不再手挑字段——第一版只记 Authorization,于是 x-api-key 泄漏在整轮 155 条回归里全绿通过,完全不可见)。

4.1 现状(proxy_pass_request_headers on,默认)

客户端用 x-api-key: sk_<网关Key> 调用:

上游收到 值
authorization Bearer sk-UPSTREAM-REAL-SECRET ✅ 已替换
x-api-key sk_bob_bbbb…(网关自己的 Key)❌ 泄漏
anthropic-version 2023-06-01 ✅
anthropic-beta prompt-caching-2024-07-31 ✅
content-type / accept / user-agent 透传

生产侧 A/B(.11:88,Host: lm.mayishangshu.cn):/minimax/anthropic/v1/messages 两种携带方式 都返回 200 —— MiniMax 两处都认,宽松厂商掩盖了缺陷。换到只认 x-api-key 的严格厂商 会 401,且报错形状像「上游密钥配错」。

4.2 proxy_pass_request_headers off + 显式注入(allowlist)

同样客户端用 x-api-key 调用:

上游收到 值
authorization Bearer sk-UPSTREAM-REAL-SECRET ✅
x-api-key 不存在 ✅ 不再泄漏
anthropic-version / anthropic-beta ✅(来自显式注入)
content-type / accept ✅(来自显式注入)
user-agent 被丢弃(未注入)

4.3 off 模式下必须显式注入的清单(反推实测)

只注入 Host / Authorization / anthropic-version 时,实测丢失:

头 后果
Content-Type 所有 POST 失效 —— 上游收到无 content-type 的 body
anthropic-version Anthropic 协议必填,缺失即被拒
anthropic-beta Claude Code 的 prompt caching 等扩展能力静默失效
Accept SSE 流式可能受影响

自动保留:Content-Length(nginx 自动生成)。X-Real-IP / X-Forwarded-* / Connection 本就是自己设的,不受 off 影响。

代价:清单需要维护。将来厂商新增扩展头(如 openai-beta)必须记得加, 漏一个就是静默功能缺失,而 Content-Type 这种漏了是全量故障。


五、落到我们的网关

5.1 协议与 base 粒度(对用户问题的直接回答)

三个开源方案都用路径区分协议,无一按 body 的 model 猜。而我们的 「slot 在前 + 客户端路径在后」就是 LiteLLM 的 /anthropic/... 模式:

base = https://api.minimaxi.com          (只到 host)
  ├─ /minimax/v1/chat/completions            → …/v1/chat/completions
  └─ /minimax/anthropic/v1/messages          → …/anthropic/v1/messages

所以不需要任何分发代码。「统一注册」不是"网关分发",是 base 粒度写到 host。 base = …/anthropic(.11 上 minimax 现状)等于把记录钉死在该前缀下,另一协议 404。

代价:host 粒度把厂商整个路径空间开放给客户端。要收敛就用全路径 + 两条记录, 那时"两条"是自然结果,不是设计选择。

5.2 鉴权头(已按下面这个组合改造并上线,见 §七)

推荐组合(贴合 LiteLLM 的双层 + 保留我们的透传定位):

location / {
    ipass_llm on;

    # 第一层:默认不放行客户端头(allowlist 语义)
    proxy_pass_request_headers off;

    # 第二层:显式注入上游真正需要的头
    proxy_set_header Host               $llm_host;
    proxy_set_header Authorization      $llm_auth;      # 换上游真 Key
    proxy_set_header anthropic-version  $http_anthropic_version;
    proxy_set_header anthropic-beta     $http_anthropic_beta;
    proxy_set_header Content-Type       $content_type;
    proxy_set_header Accept             $http_accept;
    # 自己产生的头
    proxy_set_header X-Real-IP          $remote_addr;
    proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto  $scheme;
    proxy_set_header Connection         "";
    ...
}

最小改动替代方案(若不愿维护清单):保留 on,逐个抹除凭据头:

proxy_set_header x-api-key "";   # nginx 空串 = 不发该头
proxy_set_header api-key   "";

两者取舍:off 默认安全、未知头一律不放行(LiteLLM 思路),但清单要维护; blocklist 改动一行、不影响现有透传,但将来厂商新增凭据头得记得补。

长期正确解是 LiteLLM 的 authenticated_with_header 语义:llm::downstream_key 已经知道客户端用哪个头鉴权,把这个信息暴露成变量后按需摘除。当前阶段两种方案都能先堵住泄漏。

5.3 严格厂商(只认 x-api-key)的支持

.11 上 deepseek/minimax 都是宽松厂商(两处都认),所以现在不阻塞。 若要支持严格厂商,最省的做法是在上游记录里加一个鉴权风格字段(bearer / x-api-key / both), 由 llm.rs 算出 $llm_auth 与 $llm_auth_x_api_key 两个变量,nginx 侧按需注入。 别按厂商名硬编码 —— 那是 Higress 已经改掉的"宽泛匹配"老路。


六、参考来源

  • LiteLLM litellm/proxy/litellm_pre_call_utils.py(clean_headers / _get_forwardable_headers)
  • LiteLLM 文档:Anthropic Passthrough、Forward Client Headers to LLM API、Native /v1/messages Passthrough
  • one-api relay/adaptor/anthropic/adaptor.go、README(Claude Code 段)
  • new-api relay/channel/claude/adaptor.go
  • Higress plugins/wasm-go/extensions/ai-proxy/、v2.2.3 release notes(#3839 / #3989)
  • Anthropic 官方:Claude Code Authentication(ANTHROPIC_AUTH_TOKEN vs ANTHROPIC_API_KEY)
  • nginx proxy_pass_request_headers 语义(默认 on = 透传客户端头)

七、落地记录(2026-09-12,ipass-1.0.4)

7.1 出站头策略(已上线)

conf/nginx.conf 的 LLM location 与两个测试模板(tests/llm/nginx.conf.in、 tls.conf.in)现在是同一套:

proxy_pass_request_headers off;          # 默认不放行(allowlist 语义)
proxy_set_header x-api-key      "";      # 第一层:凭据头显式抹空
proxy_set_header api-key        "";
proxy_set_header x-goog-api-key "";
# 第二层:显式放行上游真正需要的头
proxy_set_header Host / Authorization / Content-Type / Accept /
                 anthropic-version / anthropic-beta / openai-beta / User-Agent …

两层都要留,但真正在堵漏的是「抹空」那三条。 实测:只把 off 翻回 on, 断言仍然全绿(抹空还在生效);把抹空也去掉(= 改造前的真实状态)才会漏。 保留 off 的用意是默认安全,保留抹空的用意是——将来谁把 off 改回去,这层仍兜底。

验收证据(.11 生产;临时挂一条指向 postman-echo 的上游,用完即删):

上游实际收到 改造前 改造后
x-api-key / api-key / x-goog-api-key 网关自己的 sk_… 三个都不存在
Authorization Bearer <上游真 Key> Bearer <上游记录里的值> ✅
Content-Type / Accept 透传 显式注入,仍在 ✅
anthropic-version / anthropic-beta / openai-beta 透传 显式注入,仍在 ✅
User-Agent 透传 仍透传 ✅

同一轮还确认了真实上游没被改坏:/minimax/anthropic/v1/messages 以 Authorization: Bearer <网关Key> 与 x-api-key: <网关Key> 两种方式调用都是 200。

回归:bash tests/run.sh → LLM 89 + 网关 78,失败 0(较改造前 +12 条断言)。 反证:把测试模板还原成改造前状态(无 off、无抹空)重跑,3 条凭据断言如实 变红(86 / 3)——证明这组断言不是空转。

7.2 统一注册(已应用到 .11)

minimax 的 base 从 https://api.minimaxi.com/anthropic 改成 https://api.minimaxi.com。 只改 base:省略 auth / models 即保持原值(实测响应里 auth_mask 仍是原密钥, 没被清空)。同一条记录、同一把 Key 的实测:

客户端路径 落点 改造前 改造后
/minimax/anthropic/v1/messages …/anthropic/v1/messages 200(Anthropic 形状) 200,落点一字不变
/minimax/v1/chat/completions …/v1/chat/completions 404(被 /anthropic 前缀钉死) 200(object:"chat.completion")

代价与副作用(必须知道):

  1. 客户端能到达的路径空间从 /anthropic/* 扩到厂商整个路径空间。 持 Key 者 可以借网关调用厂商其它计费接口(TTS / 视频 / 文件等),网关侧无法按路径收敛 —— 要收敛就得回到「全路径 + 两条记录」。这是本方案唯一的真实代价。
  2. 面板给客户端的 base_url 从此是「协议中立」的:现在显示 https://lm.mayishangshu.cn/minimax。OpenAI 系客户端可直接用; Anthropic 系客户端必须自己补 /anthropic,否则打到 …/minimax/v1/messages → 厂商侧 404:
    ANTHROPIC_BASE_URL=https://lm.mayishangshu.cn/minimax/anthropic   # SDK 再拼 /v1/messages
    
    这正是 LiteLLM 的用法({网关}/anthropic 之后才是 provider 路由)。

回退(改回一条记录即恢复原状,密钥保持不动):

curl -sk -b <admin 会话 cookie> -X POST "https://<mdm 域名>:88/api/admin/upstreams/save" \
  -H 'Host: <mdm 域名>' -H 'Content-Type: application/json' \
  -d '{"slot":"minimax","base":"https://api.minimaxi.com/anthropic"}'

deepseek 本轮未动:base https://api.deepseek.com/v1 只服务 OpenAI 协议, 本轮问题是 Anthropic 侧;动它只有「客户端省略 /v1 会怎样」这类额外不确定性, 没有对应收益。将来它若也要接 Anthropic(DeepSeek 有 /anthropic 端点),再按 同一套办法改 base 即可。