16. 请求变换、网关扩展与开放 API
完整版章节。内容按 2026.10 主线代码核对；具体入口以当前许可、账号权限和交付环境为准。
本章说明业务系统接入网关时的两类配置：安装网关扩展并绑定到流量，以及获取开放 API 文档。请求和响应改写属于流量规则的动作，见第 15 章。
16.1 请求和响应变换
请求和响应变换在「管理控制台 → 路由策略 → 流量规则」的规则动作中配置，需要「动态路由」许可模块。可用的变换动作包括「改写请求头」「改写请求字段」「改写请求正文」「改写响应头」「改写响应字段」和「状态码映射」，改写失败时的处理方式在「异常处理」中设置。动作的适用调用类型、字段约束和验证方法见第 15.5 节，本章不重复说明。
16.2 安装、配置和绑定网关扩展
网关扩展是运行在网关请求处理过程中的 WASM 插件，用于在模型调用或 MCP 调用中执行准入、改写等逻辑。入口为「管理控制台 → 路由策略 → 网关扩展」，属于「基础功能」，需要租户管理员或「系统管理员」权限。
页面为插件目录，列出本租户可用的网关扩展，列包括「插件」「类型与能力」「当前版本」「状态」「绑定数」「凭据绑定数」「安装时间」。可按「安装状态」筛选，也可在「搜索插件…」中输入 2 至 128 个字符、不超过 8 个词进行搜索。本租户上传的私有插件带「本租户」标记，平台发布的插件在详情中显示为「平台共享」。
插件详情包含以下标签：
| 标签 | 内容 |
|---|---|
| 「概览」 | 身份信息、安装状态、当前版本、能力（「插件类型」「插入阶段」「读取请求体」）、供应链标识与摘要 |
| 「配置」 | 安装插件、填写插件配置并「保存配置」 |
| 「网关策略」 | 请求屏蔽、防重放和并发上限，见第 16.3 节；仅对已安装、非 MCP 上游用户身份类的网关扩展显示 |
| 「版本」 | 版本历史、「插件版本管理」 |
| 「绑定」 | 流量绑定和密钥绑定 |
| 「权限」 | 插件声明的「网络目标」「密钥要求」「安全与数据要求」「PII 要求」 |
| 「执行统计」 | 插件运行结果与耗时 |
安装并启用插件的步骤如下：
- 在目录中选择「安装」，或打开详情后在「配置」标签操作。
- 查看「权限」标签，确认插件声明的网络目标、密钥、安全与 PII 要求符合本单位要求。
- 在「配置」标签按表单填写配置后选择「安装（停用）」；插件无需配置时选择「以空配置安装（停用）」。插件以停用状态安装，配置发布后再启用。
- 等待状态依次经过「等待发布」「等待网关加载」并显示「已生效」，再在详情页打开「启用」开关。
- 在「绑定」标签确认绑定范围；插件已停用时，绑定不会生效。
- 用命中和不命中的请求分别验证，再到「执行统计」核对结果。
绑定插件到流量
流量绑定决定插件对哪些请求执行。绑定范围包括「全部流量」「模型」「路由」「调用方」「消费者」「MCP 服务」和「所有 MCP 服务」。每条绑定显示执行方式（「强制」或「观察」）、采样比例和优先级，可在「绑定」标签中启停或「删除」。
不同类型插件的绑定方式不同：
- MCP 上游用户身份类插件（「类型与能力」显示「MCP 上游用户身份」）：在「绑定」标签选择「创建绑定」，在「MCP 服务」中选择一个服务，或选择「所有 MCP 服务」。选择「所有 MCP 服务」时，插件对当前及后续新增的所有已启用、通过网关访问的 MCP 服务的全部调用生效。该类绑定始终以「强制」方式执行全部调用。
- 模型调用类插件：「绑定」标签展示和维护已有绑定；新建绑定通过开放 API
POST /api/v1/plugins/bindings，scopeType取global、model、route或principal；未指定执行方式时默认为观察模式。创建并启用绑定后，可在流量规则详情的「插件绑定」标签中通过「添加插件」挂载到规则；插件仅在调用类型限定为「模型调用」的规则上生效，每条规则最多挂载 8 个插件绑定，详见第 15 章。
MCP 上游用户身份类插件与 MCP 服务自带的上游用户身份配置不能同时作用于同一服务：
- 目标 MCP 服务已启用上游用户身份原配置时，创建或启用插件绑定前需关闭原配置。对话框提供「关闭原配置并创建绑定」，需要填写「变更原因」。
- 租户内任一 MCP 服务仍保留上游用户身份原配置时，不能绑定「所有 MCP 服务」。
- 同一 MCP 服务只能有一条启用的此类插件绑定；已存在「所有 MCP 服务」绑定时，不能再为单个服务启用绑定，反之亦然。
- IAM 身份来源未配置时，缺少用户身份的调用会被拒绝，页面提供「前往 IAM 提供者设置」。
维护插件版本与卸载
- 在「版本」标签的「插件版本管理」中选择「上传新版本」提交完整插件包，或对已有版本选择「切换到此版本」。
- 切换前在「目标版本配置」中填写目标版本的完整配置，选择「继续预览」。预览会列出将被删除的配置键，需勾选确认。
- 在「确认插件变更」中核对影响后选择「确认」。确认后才发布到网关；并发变化会阻止本次操作。
- 页面显示发布和加载进度。新版本在网关运行失败时，平台自动回滚到原版本并提示「自动回滚完成」。
- 卸载前选择「卸载」查看影响：将清理的绑定和配置、将被清理的网络凭据绑定，以及将停用并移除插件引用的流量规则。本租户私有插件可同时勾选「同时删除这个租户私有插件包及全部版本」。
- 操作完成后在插件目录、「绑定」标签、「执行统计」和操作审计中核对版本与状态。
上传私有插件与下载开发包
- 上传插件：在插件目录选择「上传插件」，提交
.zplugin插件包。插件包不超过 140 MiB，平台校验压缩包结构、清单、制品摘要、WASM 组件、接口类型和配置结构，校验未通过时拒绝上传。上传成功后作为本租户私有插件出现在目录中。 - 下载 SDK：选择「下载 SDK」，在「下载网关扩展 SDK」中选择「开发语言」（「Rust：编译为 WASM 组件」或「Lua：只需编写 plugin.lua」），填写「插件标识」，选择插件类型（「请求准入：模型调用前放行或拒绝」「请求转换：修改请求正文或请求头」「响应转换：处理模型流式响应」）。下载包包含对应 SDK、WIT 接口定义、清单、示例代码以及构建、校验和发布说明。Lua 无需配置 Rust 或 WASM 工具链，但解释执行可能慢于 Rust；对延迟或吞吐敏感时优先选择 Rust。
- AI 开发说明：同一对话框的「下载 AI Skill」提供一份 SKILL.md，供 AI 编程助手按本网关的接口编写插件。
查看执行统计
「执行统计」仅适用于已安装的网关 WASM 插件。启用安装并至少有一条启用的流量绑定后才开始采集。
- 选择时间范围，自定义区间不超过 7 天。
- 查看「执行次数」「成功」「拦截」「观察命中」「失败」「p95 耗时」和「各阶段执行次数」。
- 按「阶段」和「执行结果」筛选执行记录。阶段包括「P0 模型改写」「P1 请求准入」「P1' 路由感知准入」「P2 请求改写」「P3 响应改写」。
- 在记录中核对「发生时间」「原因」「耗时」「绑定」和「版本」；需要查看对应调用时，在「调用链 / 请求」列选择「请求」，在弹出的对话框中直接查看该次调用的报文，选择「调用链」进入调用链。
页面提示存在投递缺口时，对应时间段内的部分执行记录未能采集，不能据此判断插件未运行。统计仅涵盖当前安装，重新安装后不包含此前的数据。
16.3 配置插件网关策略
已安装的网关扩展（MCP 上游用户身份类除外）在详情中提供「网关策略」标签。策略由网关侧执行，随该插件的绑定生效，保存后选择「保存网关策略」发布。
| 策略 | 配置项 | 限制与说明 |
|---|---|---|
| 「请求屏蔽规则」 | 「规则 ID」「原因码」「路径前缀」「路径包含」「请求头名称」「请求头包含」「请求头等于」「提示信息」 | 最多 200 条；每条至少设置路径前缀、路径包含或请求头名称之一；填写请求头名称时需同时设置“包含”或“等于”条件。命中即拒绝请求 |
| 「防重放（Nonce + 时间戳）」 | 「启用执行」「强制要求 nonce 头（缺则拒绝）」「Nonce 请求头」「时间戳请求头」「最大时间偏差（秒）」「Nonce 保留时间（秒）」 | 偏差与保留时间范围均为 1 至 86400 秒；重复 nonce 被拒绝。需与调用方的时间戳和 nonce 生成方式联调 |
| 「并发上限」 | 「启用执行」「最大并发数」「计数维度」「超限行为」「租约 TTL（秒）」 | 最大并发数 1 至 100000；计数维度可选 consumer、model、org、consumer_model；超限行为当前只有 reject；请求结束时释放槽位 |
单次请求 Token 上限在流量规则中配置，见第 15.5.4 节。
插件声明了网络目标和密钥要求时，「绑定」标签的「密钥绑定」列出已有的网络凭据绑定及其「允许目标」。每条绑定以逻辑名称引用一个密钥，并限定该密钥只能用于指定目标。新建密钥绑定通过开放 API POST /api/v1/plugins/secret-bindings（参数为 installationId、logicalName、secretReference、allowedDestination）。
插件的「执行统计」用于观察运行状态，「概览」的用量面板和「网关请求」用于核对消耗，操作审计用于追溯配置变更。
16.4 获取开放 API 文档
开放 API 规范文件（OpenAPI）用于查看平台管理接口的路径、参数和响应结构。规范文件不经访问入口对外提供，需要时向交付方索取与平台同版本的文件。规范中列出的接口不代表当前身份有权调用。
调用接入流程如下：
- 取得与目标平台同版本的规范文件，生成或更新客户端。
- 按接口所属身份类型配置平台会话、API 密钥或服务 Token。
- 在隔离环境发送最小请求，验证认证、权限、幂等和错误结构。
- 在「概览 → 网关请求」或「操作审计」中核对调用方、时间、耗时、状态码和关联 ID。
- 把实际开放的路径、身份、模型范围和限流约束记录到业务接入单。
需要通过 MCP 客户端执行管理操作时，可使用平台管理 MCP，见第 11.9 节。
16.5 集成上线检查
- 真实业务调用经过预期的流量规则。
- API 密钥或服务 Token 已存入密钥管理系统，日志中不可见原文。
- 请求和响应变换已分别用流式、非流式请求验证。
- 网关扩展的权限声明、绑定范围、执行方式和网关策略已经确认，「执行统计」中有预期记录。
- 开放 API 规范与平台版本一致，错误响应和限流行为已纳入客户端处理。
- 调用记录可以关联调用方、模型、路由、插件和最终状态。