- docs §七:本次改造实际发出的配置、生产验收表(.11 临时挂 echo 上游)、 反证结果(还原成改造前 → 3 条凭据断言如实变红)、统一注册的改前改后实测、 两个副作用(路径空间放大 / base_url 变协议中立)与回退命令。 - readme:§12.6 tag 表补齐 1.0.2 / 1.0.3 / 1.0.4(这三版此前没登记); §15 增加提示框说明「base 写到哪一层决定 base_url 是否协议中立」及 Anthropic 客户端必须自己补 /anthropic;§16 补本轮变更记录。
17 KiB
LLM 多协议网关:上游路由与鉴权头的成熟做法
调研日期 2026-09-12。目的:回答「上游同时有 OpenAI 与 Anthropic 两套协议时, 统一注册再分发、还是注册两条」,以及「网关 Key 经请求头泄漏给上游」怎么修。 结论全部来自开源实现或厂商官方文档,并附本机靶机实测证据(本项目硬规矩: 验证请求头替换必须看上游收到的请求)。
涉及文件:conf/nginx.conf(LLM server)、rust/src/llm.rs、rust/src/upstreams.rs、
tests/llm/upstream.py。
一、结论速览
| 问题 | 成熟做法 | 我们的对应 |
|---|---|---|
| 协议怎么区分 | 路径,三个主流网关一致 | 已有: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
三条可直接借用的原则:
authenticated_with_header—— 记录「客户端用哪个头做了网关自身鉴权」, 那个头绝不转发。比按名字硬编码精确:同一个x-api-key,用来过网关时要摘掉, 作为 BYOK 凭据时要转发,区别就在这里。- 默认摘除凭据头,官方文档明确列了
x-api-key/x-goog-api-key/api-key, 理由是 "these are typically used to authenticate with the proxy itself"。 - 双层防护:
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_TOKENenvironment 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_KEYenvironment 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/messagesPassthrough - 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_TOKENvsANTHROPIC_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") |
代价与副作用(必须知道):
- 客户端能到达的路径空间从
/anthropic/*扩到厂商整个路径空间。 持 Key 者 可以借网关调用厂商其它计费接口(TTS / 视频 / 文件等),网关侧无法按路径收敛 —— 要收敛就得回到「全路径 + 两条记录」。这是本方案唯一的真实代价。 - 面板给客户端的
base_url从此是「协议中立」的:现在显示https://lm.mayishangshu.cn/minimax。OpenAI 系客户端可直接用; Anthropic 系客户端必须自己补/anthropic,否则打到…/minimax/v1/messages→ 厂商侧 404:这正是 LiteLLM 的用法(ANTHROPIC_BASE_URL=https://lm.mayishangshu.cn/minimax/anthropic # SDK 再拼 /v1/messages{网关}/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 即可。