- 模型加 mode 字段(vendor 默认 / passthrough 新增),shm payload 扩为 4 字段 base\nkey\nasset_id\nmode;旧数据零迁移(无 mode → vendor) - 拆 location 而非按 mode 分支:/apixp/ 不施加 vendor 强约束 (proxy_method POST + 强制 Content-Type + proxy_pass_request_headers off 是 location 级指令,无法按请求级 shm 的 mode 动态切换) - handler 校验路径前缀 vs mode 一致(vendor slug 走 /apixp/ → 404,反之亦然), 避免 vendor 条目继承 passthrough 强制 Content-Type 致 415 之类静默故障 - passthrough:方法/请求体/Content-Type 原样透传(含 multipart),上游路径 = base + /apixp/<slug> 之后的 URI 尾部(含 query 由模块拼,变量式 proxy_pass 不自动追加);Key 可空(内部服务免鉴权,下发时 nginx 空串 = 不发该头) - 探测按 mode 分流:vendor 走 POST 预估 / passthrough 走 GET 打上游根地址 - nginx:lm server 加 /apixp/,mdm server 加 /_apixp_probe/(internal) - 测试 §11.6 新增 35 条断言(鉴权/路径转发/体透传/Key 下发/路径-mode 一致 /管理台回显/探测);账号态 count 1→3 同步;回归 225/0 全绿 - 管理台:列表加 mode 标签、表单加 mode 下拉 + 透传说明 + 路径示例复制 - 文档:docs/apix/PASSTHROUGH_MODE.md 真源(决策/兼容/改动一览) OCR 是第一条 passthrough 配置:/apixp/ocr/ocr、/apixp/ocr/ocr/base64、 /apixp/ocr/ocr/url?src=...
120 lines
5.5 KiB
Markdown
120 lines
5.5 KiB
Markdown
# apix 透传模式(passthrough)
|
||
|
||
## 为什么需要
|
||
|
||
vendor 模式假设「单一供应商收口 `POST /api/v1/ai/request`,资产由 body 里的
|
||
`asset_id` 决定」,网关负责拼体(堵客户端挑最贵的资产刷)——对 LLM 资产市场型
|
||
服务很合理。但公司内部一些 REST 服务(OCR / 文生图 / TTS)有完全不同的形态:
|
||
|
||
| 维度 | vendor 模式 | passthrough 模式 |
|
||
| --- | --- | --- |
|
||
| 上游 | 单一收口 | 多端点(`/ocr` `/ocr/base64` `/ocr/url` 等) |
|
||
| 请求体 | 网关从 query 拼 | 客户端原样带(含 multipart) |
|
||
| Content-Type | 强制 `application/json` | 原样透传(含 `multipart/form-data`) |
|
||
| 方法 | GET 被强制改成 POST | 原样透传 |
|
||
| 鉴权 | 必填供应商 Key | 可空(内部服务免鉴权) |
|
||
| 资产选择权 | 服务端(asset_id 在网关侧) | 客户端(URL 路径即端点) |
|
||
|
||
强行套 vendor 会 4 处冲突(路径写死 / 体来源 / Content-Type / 方法),所以新加
|
||
passthrough 模式作为「通用内部 REST 出口」——OCR 只是第一条配置。
|
||
|
||
## 设计要点
|
||
|
||
### 拆 location 而不是按请求级切模式
|
||
|
||
vendor `/apix/` 在 nginx 层强制了 `proxy_method POST` + `proxy_set_body` +
|
||
`Content-Type: application/json` + `proxy_pass_request_headers off`,这些
|
||
location 级指令**无法按请求级 shm 的 mode 动态切换**。
|
||
|
||
所以 passthrough 走独立 `/apixp/` location,不施加上述约束,零风险保留 `/apix/`
|
||
的 vendor 行为。nginx 端按 URL 前缀选 location 是**单一判定点**,模块侧不再做
|
||
「同前缀按 mode 分支」的二选一。
|
||
|
||
### Mode 必须与路径前缀一致
|
||
|
||
- vendor 条目:只能走 `/apix/<slug>`,访问 `/apixp/<slug>` → 404
|
||
- passthrough 条目:只能走 `/apixp/<slug>/<tail>`,访问 `/apix/<slug>` → 404
|
||
|
||
handler 在 access 阶段校验,避免「vendor 条目继承 passthrough 的强制
|
||
`Content-Type` 导致 415」之类静默故障。
|
||
|
||
### 路径尾部 + query 透传
|
||
|
||
- `$apixp_target = base + tail + (?args if any)`
|
||
- 变量式 `proxy_pass` 不自动追加 query,由模块在 `var_get` 里把 `args_raw` 拼上
|
||
(与 LLM 同约束)
|
||
- 内部探测走 `$apixp_probe_target = base/`(GET 打上游根地址验连通性)
|
||
|
||
### 鉴权语义
|
||
|
||
- vendor:供应商 Key 必填,空 → 503「供应商 API Key 未配置」
|
||
- passthrough:Key 可空,空时不下发 `X-API-Key`(nginx 空串 = 不发该头)
|
||
- 两模式**都**走 `sk_` 下行 Key + 配额 + 用量统计(slot 前缀 `api/<slug>`)
|
||
—— 这是 passthrough 仍过 iPass 的意义,不是「直连上游」
|
||
|
||
## 配置示例(OCR)
|
||
|
||
```json
|
||
{
|
||
"ocr": {
|
||
"supplier": "internal-ocr",
|
||
"asset_id": "",
|
||
"base": "http://192.168.1.11:9003",
|
||
"key": "",
|
||
"mode": "passthrough",
|
||
"name": "内部 OCR 服务",
|
||
"desc": "多端点透传:/ocr、/ocr/base64、/ocr/url",
|
||
"params": [],
|
||
"enabled": true
|
||
}
|
||
}
|
||
```
|
||
|
||
调用方走网关同一把 `sk_` Key:
|
||
|
||
```
|
||
POST /apixp/ocr/ocr multipart/form-data(上传图片)
|
||
POST /apixp/ocr/ocr/base64 {"image_base64":"..."}
|
||
POST /apixp/ocr/ocr/url?url=... {"url":"..."}
|
||
```
|
||
|
||
## shm payload 兼容
|
||
|
||
shm `ax:<slug>` 从 3 字段 `base\nkey\nasset_id` 扩成 4 字段 `base\nkey\nasset_id\nmode`。
|
||
|
||
- 旧数据(无 mode)→ 解析时 mode = "",lookup 视为 vendor(向后兼容)
|
||
- 旧代码读 3 元组版本未在线,会被新版本解析时 None 化(重启即统一)
|
||
|
||
## 回归覆盖
|
||
|
||
`tests/llm/e2e.sh` §11.6(35 条断言)覆盖:
|
||
|
||
- 鉴权(无 Key / 坏 Key / 不存在 / 停用 → 401/404)
|
||
- 空 Key 透传放行(内部服务免鉴权)
|
||
- 路径尾部单级 + 多级(`/ocr` `/ocr/base64` `/ocr/url`)
|
||
- query 透传(`/apixp/ocr/ocr/url?src=...`)
|
||
- 方法透传(POST 没被改)
|
||
- 请求体透传(multipart / JSON 原样)
|
||
- `X-API-Key` 按需下发(空 → 不发)
|
||
- 下行 `sk_` Key 绝不外传
|
||
- 路径/模式一致性(vendor 走 `/apixp/` → 404,反之亦然)
|
||
- 管理台:mode 字段回显、调用地址用 `/apixp/` 前缀
|
||
- 探测:passthrough 走 GET 打上游根地址
|
||
- 内部探测口 `/_apixp_probe/` 外部直连 → 404
|
||
- 用量统计按 `api/<slug>` 归组(passthrough 同样计)
|
||
|
||
## 文件改动一览
|
||
|
||
| 文件 | 改动 |
|
||
| --- | --- |
|
||
| `rust/crates/plugin-apix/src/models.rs` | `ApiProxy` 加 `mode` 字段(默认 vendor) |
|
||
| `rust/crates/plugin-apix/src/config.rs` | `APIX_MODE_VENDOR` / `APIX_MODE_PASSTHRU` 常量 |
|
||
| `rust/crates/plugin-apix/src/apix.rs` | `PUB_PT_PREFIX` / `PROBE_PT_PREFIX`;shm payload 4 元;`slug_of` 返回 `(slug, tail, is_passthru_path)`;`lookup` 返 4 元;`var_get` 增 `$apixp_*` 透传分支;`call_url` 按 mode 选前缀;`view` 回显 mode |
|
||
| `rust/crates/plugin-apix/src/handlers.rs` | access 阶段校验「路径前缀 vs mode」一致;passthrough 放行空 Key |
|
||
| `rust/crates/plugin-apix/src/api.rs` | `upsert` 收 mode(passthrough 下 asset_id 可空);`view` 含 mode;`h_admin_apix_test` 按 mode 选探针前缀 |
|
||
| `conf/nginx.conf` | lm server 加 `/apixp/`;mdm server 加 `/_apixp_probe/`(GET) |
|
||
| `tests/llm/nginx.conf.in` | 同步 `/apixp/` 与 `/_apixp_probe/` |
|
||
| `tests/llm/fixtures/api-proxies.json` | 新增 `ocr`(空 Key)+ `ocrk`(带 Key)两个 passthrough 夹具 |
|
||
| `tests/llm/e2e.sh` | §11.6 加 35 条透传断言;§11.5 账号态计数 1→3 |
|
||
| `www/apix.html` | 列表说明加 vendor/passthrough 两模式解释 |
|
||
| `www/assets/apix.js` | 列表 mode 标签;表单 mode 下拉 + 透传提示 | |