From b76213bebb7025474662f68588d291ec821d35cb Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 12 Sep 2026 12:46:42 +0800 Subject: [PATCH] =?UTF-8?q?docs(llm):=20=E8=A1=A5=E8=90=BD=E5=9C=B0?= =?UTF-8?q?=E8=AE=B0=E5=BD=95=EF=BC=88=E5=87=BA=E7=AB=99=E5=A4=B4=E7=AD=96?= =?UTF-8?q?=E7=95=A5=20+=20=E7=BB=9F=E4=B8=80=E6=B3=A8=E5=86=8C=EF=BC=89?= =?UTF-8?q?=EF=BC=8C=E5=B9=B6=E5=90=8C=E6=AD=A5=20readme?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 补本轮变更记录。 --- docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md | 80 +++++++++++++++++++++++++- readme.md | 30 ++++++++++ 2 files changed, 109 insertions(+), 1 deletion(-) diff --git a/docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md b/docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md index cd980e1..3810b6c 100644 --- a/docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md +++ b/docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md @@ -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 -X POST "https://:88/api/admin/upstreams/save" \ + -H 'Host: ' -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 即可。 diff --git a/readme.md b/readme.md index 1d30509..99f77d8 100755 --- a/readme.md +++ b/readme.md @@ -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/<上游路径>`——客户端拿它当 `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 上游无损。