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

354 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`,真实源码):
```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 = 透传客户端头)
---
## 七、落地记录(2026-09-12,`ipass-1.0.4`)
### 7.1 出站头策略(已上线)
`conf/nginx.conf` 的 LLM location 与两个测试模板(`tests/llm/nginx.conf.in`、
`tls.conf.in`)现在是同一套:
```nginx
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:
```bash
ANTHROPIC_BASE_URL=https://lm.mayishangshu.cn/minimax/anthropic # SDK 再拼 /v1/messages
```
这正是 LiteLLM 的用法(`{网关}/anthropic` **之后**才是 provider 路由)。
**回退**(改回一条记录即恢复原状,密钥保持不动):
```bash
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 即可。