docs(llm): 补落地记录(出站头策略 + 统一注册),并同步 readme

- 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 补本轮变更记录。
This commit is contained in:
admin committed 2026-09-12 12:46:42 +08:00
1 parent 9ebee9c96d
commit b76213bebb
2 files changed
+109 -1

No files matched your search

+79 -1
View File
@@ -211,7 +211,7 @@ base = https://api.minimaxi.com (只到 host)
代价:host 粒度把厂商整个路径空间开放给客户端。要收敛就用全路径 + 两条记录,
那时"两条"是自然结果,不是设计选择。
### 5.2 鉴权头(待修)
### 5.2 鉴权头(已按下面这个组合改造并上线,见 §七)
推荐组合(贴合 LiteLLM 的双层 + 保留我们的透传定位):
@@ -269,3 +269,81 @@ blocklist 改动一行、不影响现有透传,但将来厂商新增凭据头
- 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 即可。