Files
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

5.5 KiB
Raw Permalink Blame History

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 下拉 + 透传提示