Files
ipass__ipass/docs/apix/PASSTHROUGH_MODE.md
T
admin 4533db8536 feat(apix): 透传模式 passthrough —— 通用内部 REST 出口 (1.0.20)
- 模型加 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=...
2026-09-15 10:51:29 +08:00

120 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 下拉 + 透传提示 |