- 模型加 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=...
5.5 KiB
5.5 KiB
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)
{
"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 下拉 + 透传提示 |