docs(llm): 多协议路由与鉴权头调研(开源实现 + 官方指引 + 实测)
- LiteLLM:/anthropic/* 路径前缀路由;clean_headers 的 authenticated_with_header 语义 + 默认摘凭据头 + 双层 allowlist + 日志/转发两副本分离 - one-api:根地址 + 路径天然区分,model 只选 channel,出站三头齐设 - Higress:Automatic Protocol Detection;v2.2.3 把按模型名宽泛匹配改成路径后缀判断 - Anthropic 官方:走网关用 ANTHROPIC_AUTH_TOKEN(发 Authorization),直连才用 ANTHROPIC_API_KEY(发 X-Api-Key) - 靶机改为记录全部收到的头:手挑字段会让未替换的头在回归里全绿通过 结论:协议由客户端路径表达,不需要网关分发;统一注册的实体是 base 写到 host。 鉴权头两种修法与 off 模式的必注入清单(漏 Content-Type 会让所有 POST 废)见文档。
This commit is contained in:
1 parent
02601f6d33
commit
9ede90b06e
2 files changed
+276
-3
No files matched your search
@@ -0,0 +1,271 @@
|
||||
# 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`,真实源码):
|
||||
|
||||
```python
|
||||
# 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
|
||||
```
|
||||
|
||||
```python
|
||||
# _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 用法:
|
||||
```bash
|
||||
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 的双层 + 保留我们的透传定位):
|
||||
|
||||
```nginx
|
||||
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`,逐个抹除凭据头:
|
||||
|
||||
```nginx
|
||||
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 = 透传客户端头)
|
||||
@@ -22,13 +22,15 @@ class H(BaseHTTPRequestHandler):
|
||||
protocol_version = "HTTP/1.1"
|
||||
|
||||
def _record(self, body: bytes):
|
||||
# 记录**全部**收到的头,而不是手挑几个字段。
|
||||
# 教训:手挑字段会漏掉"没被替换的那个头"——第一版只记 Authorization,
|
||||
# 于是 x-api-key 泄漏在整轮回归里全绿通过,完全看不见。
|
||||
rec = {
|
||||
"path": self.path,
|
||||
"method": self.command,
|
||||
"headers": {k.lower(): v for k, v in self.headers.items()},
|
||||
# 下面几个是长期被断言的字段,保留以免旧断言失效
|
||||
"auth": self.headers.get("Authorization", "-"),
|
||||
# x-api-key / anthropic-version 必须记:Anthropic 协议的上游只认
|
||||
# `x-api-key`,而网关当前只覆写 Authorization。**不记就意味着
|
||||
# 「下游那把 sk_ 是否被原样漏给上游」这件事在这里是看不见的**。
|
||||
"x_api_key": self.headers.get("x-api-key", "-"),
|
||||
"anthropic_version": self.headers.get("anthropic-version", "-"),
|
||||
"host": self.headers.get("Host", "-"),
|
||||
|
||||
Reference in new issue
Block a user