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:
1 parent
9ebee9c96d
commit
b76213bebb
2 files changed
+109
-1
No files matched your search
@@ -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 即可。
|
||||
Reference in new issue
Block a user