# 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/`,访问 `/apixp/` → 404 - passthrough 条目:只能走 `/apixp//`,访问 `/apix/` → 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/`) —— 这是 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:` 从 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/` 归组(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 下拉 + 透传提示 |