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 即可。
+30
View File
@@ -635,6 +635,9 @@ DRY_RUN=1 bash deploy/release.sh 1.0.3 # 只构建不推送
| --- | --- |
| `ipass-1.0.0` | 首个完整版(上游多模型 / 模型发现 / 用量统计)。⚠️ 该 tag 在 `base_url` 修复后被**同 tag 覆盖**过(digest 由 `046a9dd7…` 变为 `226321bec…`),是历史遗留;此后不再覆盖。 |
| `ipass-1.0.1` | `base_url` 端口跟随调用方 `Host`(修复 .11 上 88 端口回显地址打不通)。digest `226321bec…`,与 `ipass-1.0.0` 覆盖后的内容相同。**tag 只增不改的约定从这一版生效。** |
| `ipass-1.0.2` | 写共享内存失败必须出声(三处 `sync_shm` 不再丢弃返回值,`reload_shm` 增加「期望条数 vs 实际装载」核对)——热路径无回源兜底,静默失败等于「刚配好却 404/401 且日志无痕」。 |
| `ipass-1.0.3` | 管理台「新建 / 更新 LLM 上游」表单的上游地址、密钥输入框独占整行(原被网格压到 ~170px,地址与密钥看不全)。 |
| `ipass-1.0.4` | **LLM 出站请求头改为「默认不放行」**(`proxy_pass_request_headers off` + 凭据头抹空 + 显式放行清单),堵住网关自己的 Key 经 `x-api-key` 泄漏给上游厂商。详见 `docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md`。 |
---
@@ -817,6 +820,19 @@ curl -s -H "X-API-Key: $KEY" "$API/api/v1/usage"
`https://lm.mayishangshu.cn:88/<slot><上游路径>`——客户端拿它当 `base_url` 直接拼即可,
不必自己关心上游 `base` 里有没有 `/v1`。
> ⚠️ **`base` 写到哪一层,决定 `base_url` 是否「协议中立」。** 上游 `base` 若只写到 host
> (`.11` 上 `minimax` = `https://api.minimaxi.com`),回显的 `base_url` 就是
> `https://lm.mayishangshu.cn:88/minimax`,**末尾没有协议段**:
>
> - **OpenAI 系客户端**直接用它即可(SDK 自己拼 `/v1/chat/completions`);
> - **Anthropic 系客户端必须自己补 `/anthropic`**:
> `ANTHROPIC_BASE_URL=https://lm.mayishangshu.cn:88/minimax/anthropic`(SDK 再拼 `/v1/messages`)。
> 漏掉 `/anthropic` 会打到 `…/minimax/v1/messages` → 厂商侧 404。
>
> 这样**一条 host 粒度的记录能同时服务两套协议**。反过来,`base` 写全路径
> (如 `…/anthropic`)时回显地址自带协议段、可直接用,但该记录被钉死在这条路径下,
> 另一协议 404。取舍与实测见 `docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md` §七。
**端口跟随调用方**:`base_url` 里的端口取自你请求管理接口时用的 `Host` 头。
本网关用宿主 **88** 端口承载三个域名,而 88 不是 443,所以客户端拿到的地址里
**必须带 `:88`** 才能连上;如果哪天前面挂了 443 反代,用 `Host: mdm.mayishangshu.cn`
@@ -827,6 +843,20 @@ curl -s -H "X-API-Key: $KEY" "$API/api/v1/usage"
## 16. 变更记录
- **2026-09-12(续)LLM 出站头「默认不放行」+ 统一注册(`ipass-1.0.4`)**
- **修复凭据泄漏(安全)**:LLM location 此前只覆写 `Authorization`,客户端放在 `x-api-key`
里的**网关自己的 Key** 会被原样送给上游厂商 —— 厂商拿到它可反调本网关挂的**全部**上游。
MiniMax 两处都认,把缺陷掩盖成了 200。改为 `proxy_pass_request_headers off`
+ 凭据头抹空(`x-api-key` / `api-key` / `x-goog-api-key`)+ 显式放行清单
(`Content-Type` / `Accept` / `anthropic-version` / `anthropic-beta` / `openai-beta` / `User-Agent`)。
与 LiteLLM / one-api / Higress 的做法一致,调研与验收证据见
`docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md`。
- **`minimax` 上游 base 改到 host 粒度**(`…/anthropic` → `https://api.minimaxi.com`):
同一条记录、同一把 Key,`/minimax/anthropic/v1/messages` 仍 **200**(落点一字不变),
`/minimax/v1/chat/completions` 由 **404 → 200**。⚠️ 客户端 `base_url` 用法随之变化,见 §15 提示框。
- `ipass-1.0.2` / `ipass-1.0.3` 内容见 §12.6 的 tag 表(写共享内存失败必须出声;上游表单地址/密钥框独占整行)。
- 回归扩至 **167 条**(网关 78 + LLM 89),全绿;新增断言经过反证(还原成改造前配置 → 86 通过 / 3 失败)。
- **2026-09-12 .11 实机交付验证 + `base_url` 端口自适应**
- 在 .11 完成镜像更新(`ipass-1.0.0`,digest `046a9dd7…`):端口 `88:18098`、
网络 `ipass_default`、数据目录 `/home/train11/ipass/data` 全部复刻,3 账号 / 1 域名 / 1 上游无损。