16. 网关扩展与开放 API
完整版章节。内容按 2026.10 主线代码与运行环境界面核对；具体入口以当前许可、账号权限和交付环境为准。
本章内容：面向租户管理员、系统管理员、安全管理员与集成开发人员，说明两类扩展方式——网关扩展插件（在网关请求处理链路中运行，用于企业自有的准入、改写与合规标识，支持热更新与版本回切），以及用访问密钥签名调用平台管理接口的开放 API。本章同时说明网关在访问域名、来源网段控制与跨租户隔离上的边界能力。
本章的「插件」指网关扩展，不是「能力 › 插件」页面里的智能体插件。
16.1 网关扩展目录与插件详情
前提：租户管理员或系统管理员权限。
操作步骤：进入「管理后台 › 流量 › 网关扩展」。目录列出平台内置插件与本租户上传的私有插件，列包括「插件」「类型与能力」「当前版本」「状态」「绑定数」「凭据绑定数」「最近更新」，右上角为「下载 SDK」「上传插件」。
你会看到：状态有「未安装」「已安装」「已生效」「已停用」四种。选择「管理」进入详情，页签为「概览」（扩展 ID、可见范围、安装与运行状态、当前版本与供应链标识）、「配置」（按插件声明的表单填写并保存）、「版本」（版本历史与产物摘要）、「绑定」（流量绑定与凭据绑定）、「权限」（插件声明的网络目标、密钥要求与数据要求）与「执行统计」（执行次数、按结论与按钩子的计数、执行记录）。
注意：安装、启用与卸载都记入「操作审计」。上传私有插件前，先看「权限」页签声明的网络目标是否符合本单位要求。
16.2 下载 SDK 与开发插件
操作步骤
- 在目录选择「下载 SDK」，选「开发语言」：「Rust：编译为 WASM 组件」性能更好，适合对延迟和吞吐敏感的场景；「Lua：只需编写
plugin.lua」无需 Rust 或 WASM 工具链，上手快，解释执行可能慢于 Rust。 - 填写「插件标识」（1～128 个字母、数字、点、下划线或短横线），选择「下载 SDK」。
- 需要让编程助手按本网关接口编写插件时，选「下载开发说明」获取
SKILL.md；SDK 包中也附带一份。
你会看到：SDK 包内含 manifest.json（清单版本、宿主接口版本、钩子、服务类型与失败策略）、plugin.lua（示例逻辑）、harness.lua（本地自检）、.zr/sdk/（类型标注与本地模拟宿主）与 README。两种语言使用相同的安全限制。
构建与校验：zr-plugin build . --output ./dist/plugin.zip 生成插件包，再用 zr-plugin validate ./dist/plugin.zip 校验。validate 与服务端上传使用同一套校验，并在生产宿主中实际编译、执行一次合成请求。
运行限制：指令预算每次执行 2,000,000，单次执行 20 毫秒，内存 4 MiB，插件包不超过 140 MiB；外部 HTTP 请求只能访问清单声明、并由凭据绑定授权的目标。超出限制即中断执行，按失败策略处理：「失败关闭」（插件超时或出错时拒绝请求）或「失败放行」，安全相关插件应使用「失败关闭」。插件可声明请求头、请求体、响应头、响应流、响应整包、响应结束 6 个钩子。
注意：用「下载 SDK」拿到的模板不能直接上传——归档里必须是 manifest.json 加编译好的组件，按 README 用 zr-plugin build 生成插件包；把源码直接打成压缩包上传会被判为「插件包内容有问题」。
16.3 上传、安装与绑定
操作步骤
- 在目录选择「上传插件」并选中构建好的插件包。平台校验包结构、清单、制品摘要、接口版本与配置结构，通过后提示「插件已发布」。
- 对插件选择「安装」，或打开详情在「配置」页签操作；先看「权限」页签声明的网络目标与密钥要求。
- 填写配置后安装；无需配置的选择「以空配置安装（停用）」。插件以停用状态安装，状态变为「已安装」。
- 在「绑定」页签选择「创建绑定」，填服务类型、作用范围（「全部服务」或「指定服务」）、调用方（可选，留空表示不限制）、配置覆盖（JSON，留空
{}使用安装默认配置），再在弹窗内选择「创建绑定」。 - 打开右上角「启用」开关，等状态变为「已生效」。
- 用命中和不命中绑定范围的请求分别验证，再到「执行统计」核对。
你会看到：命中绑定范围的请求按插件逻辑处理，例如响应头中出现插件写入的标记；不命中的请求不受影响。「执行统计」中对应钩子的执行次数增加，在「运行总览 › 请求」打开该次调用还能看到插件执行记录。
注意：
- 插件已停用时绑定不生效，「绑定」页签提示「插件已停用，绑定暂不生效」。
- 指定服务的绑定优先于同一插件的「全部服务」绑定；同一次请求每个钩子只执行一次。
- 页面上有两个文案都叫「创建绑定」的按钮（目录页顶部一个、绑定弹窗内一个），要在弹窗内确认后才真正提交。
- 也可以在流量规则中添加处置动作「挂载插件」，让插件只对命中该规则的请求执行；流量规则只能进一步缩小已绑定的范围。
- 插件需要访问外部服务时，在「绑定」的凭据绑定中以逻辑名称引用密钥，并限定允许的目标地址。
校验不通过的提示：不是合法的插件包时提示「插件包内容有问题，请修复后重新上传」；宿主接口版本过旧时提示用新版本 SDK 重新构建；清单不符合规范时整个插件被拒收。上传成功后插件作为本租户私有插件出现在目录中，状态为「未安装」，可见范围为「本租户」；每次上传（包括被拒的）都记入「操作审计」。
16.4 升级、回切与停用
操作步骤：打开插件详情的「版本」页签，在「插件版本管理」中选择「上传新版本」提交完整插件包，或对已有版本选择「切换到此版本」；在「目标版本配置」中核对后「继续预览」（预览会列出将被删除的配置键，需勾选确认）；在「确认插件变更」中核对影响后「确认」；页面显示逐副本发布进度，完成后所有副本均已运行新版本。
注意：旧版本的产物与 SHA-256 保留在版本历史中，可随时切回；新版本在网关运行失败时平台自动回滚并提示「自动回滚完成」；升级时移除仍有绑定的服务类型会被拒绝，需先删除对应绑定。升级后先在试点服务上验证流式与非流式输出，再扩大绑定范围。
停用与卸载：关闭详情右上角的「启用」开关后插件不再执行，绑定保留，再次启用即恢复。选择「卸载」时，确认框会列出将清理的绑定、配置、凭据绑定与引用该插件的流量规则；本租户私有插件可同时勾选「同时删除这个租户私有插件包及全部版本」。卸载前建议先停用并观察业务调用。
16.5 用内置策略实现请求拦截与并发上限
适用场景：拦截某类请求、限制同时执行的请求数——不需要开发插件，直接作为流量规则的处置动作。前提：许可中包含「动态路由」或「模型护栏」模块。
操作步骤：「流量规则」中选择「新建规则」，在「条件判断」中添加条件把规则收窄到目标流量（如「调用类型」为模型调用、「模型」为指定模型，再加一个专用请求头）；选择「添加处置动作」——请求拦截选「拒绝本次调用」并填原因码，并发上限选「应用限额」并把限制类型设为「并发」、填上限与计数维度；「配置检查」显示正常后「保存规则」，在「确认变更」中核对字段差异与命中顺序，选「确认并应用」。
你会看到：命中拦截规则的请求返回 403 permission_denied，deniedBy 为 routePolicy，details 中带配置的原因码，不调用上游；不命中的请求正常返回，「运行总览 › 请求」中该请求状态为「已拦截」。并发上限为 N 时同时进行的请求不超过 N 个，超出部分返回 429 TRAFFIC_CONCURRENCY_LIMITED 并带 Retry-After，请求结束后释放名额。
注意：规则按清单顺序评估，排在前面、条件更宽且「结束匹配」的规则会让后面的规则无法命中，保存前在「确认变更」中核对命中顺序。规则与限额的完整说明见第 15 章。
16.6 为模型回答添加 AI 生成内容标识
内置插件「AI 生成内容标识」按《人工智能生成合成内容标识办法》与 GB 45438-2025 为模型回答添加显式文字标识，并在响应头写入隐式标识元数据。
操作步骤：在网关扩展目录找到该插件，选择「安装」或「管理」；在「配置」页签填写显式标识文字（默认「本内容由人工智能生成」）、标识位置（回答开头或末尾，默认末尾）、服务提供者名称或编码、是否写入隐式标识元数据（默认勾选，在响应头 aigc 写入规定元数据，ProduceID 为网关请求号），保存配置；在「绑定」页签创建绑定，服务类型选「模型分组」；打开右上角「启用」开关。
你会看到：调用绑定范围内的模型分组，回答开头或末尾出现配置的标识文字，响应头中有 aigc 元数据；按其中的 ProduceID 可在调用详情查到对应调用。
注意：该插件声明响应头、响应流、响应整包、响应结束四个钩子，失败策略为「失败关闭」，插件超时或出错时会拒绝请求。启用前先绑定到试点服务，核对流式与非流式输出都正常。
16.7 用访问密钥调用开放 API
访问密钥的权限与创建人本人相同，适用于把查询和配置操作纳入脚本、CI 流水线或自建智能体。
创建访问密钥：在工作台进入「个人设置 › 访问密钥」，选择「创建访问密钥」，填写「名称」（只用于辨认，不影响权限）；页面一次性显示 AccessKeyId 与 SecretAccessKey，立即保存 SecretAccessKey，关闭后无法再次查看。列表显示名称、AccessKeyId、创建人、创建时间、最后使用与状态；不再使用时选择「撤销」，撤销后下一次调用即失效。
签名调用：每次请求携带 x-zenova-date（UTC 时间，格式 YYYYMMDDTHHMMSSZ，与服务端相差不超过 5 分钟）、x-zenova-nonce（每次唯一的随机串）与 Authorization: ZENOVA-HMAC-SHA256 Credential=<AccessKeyId>, SignedHeaders=host;x-zenova-date;x-zenova-nonce, Signature=<签名>。
签名步骤：① 规范请求由六部分按换行连接——请求方法、路径、规范化查询串（按名称和值升序并做百分号编码，无查询串时为空行）、按名称排序的签名请求头（每行 小写名:值，该段以换行结尾）、签名请求头名称列表（分号连接）、请求体的 SHA-256 十六进制摘要；② 待签字符串为三行——ZENOVA-HMAC-SHA256、x-zenova-date 的值、规范请求的 SHA-256 摘要；③ 用 SecretAccessKey 对待签字符串做 HMAC-SHA256，结果取十六进制即签名。
「访问密钥」页面的「怎么签名调用」提供 curl、Node、Python、Go 与命令行工具示例，可直接复制；示例里的日期格式已是服务端要求的写法。
你会看到：签名正确时返回 200，密钥列表的「最后使用」随即更新，读取类接口的结果与管理后台一致。签名错误时返回 401，错误码含义如下。
| 错误码 | 含义 |
|---|---|
| :-- | :-- |
SIGNATURE_MALFORMED | 请求头格式不正确，如日期格式不符 |
SIGNATURE_MISMATCH | 签名与服务端计算结果不一致，通常是密钥错误或规范请求拼接有误 |
SIGNATURE_EXPIRED | 请求时间超出允许偏差 |
NONCE_REPLAYED | 该随机串已被使用过 |
UNAUTHENTICATED | 未携带凭据 |
注意：请求体的摘要参与签名，签名之后再改请求体（哪怕只改一个工具名）会被判为 SIGNATURE_MISMATCH。访问密钥可用于签名调用平台管理 MCP（POST /api/v1/mcp），按调用者真实身份执行；但模型网关不接受签名，只认 Bearer API 密钥，调用模型请用绑定模型分组的 API 密钥（见第 9 章）。密钥应存放在密钥管理系统中，不得写入代码仓库或日志。平台的 OpenAPI 规范只对平台管理员开放：平台管理员登录后，在账号菜单中选择「接口文档」打开在线文档（/api/docs/），规范文件地址为 /api/openapi.json；其他身份访问会被拒绝。规范中列出的接口不代表当前身份有权调用。
16.8 访问域名与证书
操作步骤：打开「管理后台 › 网关接入」，页面有「域名」「证书」「防护规则」三个页签；在「域名」页签中「声明自定义域名」或「分配平台子域名」，列表显示主机名、状态、协议、证书、路由绑定数、验证方式、路由目标与创建时间；打开域名的「查看」，在「路由绑定」中选匹配方式（路径前缀或精确路径）、填路径、把「路由目标」选为一条流量规则并「添加」；用「路由试算」输入路径与协议确认命中的绑定。
你会看到：「证书」页签列出当前可用的证书，协议列显示该域名的接入协议，路由绑定数显示已配置的绑定条数。
注意：域名通常是平台级共享对象，声明、绑定与释放会影响真实流量，变更前与平台管理员确认；路由试算反映的是配置，不是运行中的流量。证书的新增与更换属于部署侧操作，需要时联系平台管理员。
16.9 来源网段与路径的访问控制
流量规则提供「客户端 CIDR」与「请求路径」两个条件，配合「拒绝本次调用」与「放行」两个动作即可实现黑白名单；系统没有独立的名单入口。前提：规则的第一条件建议为「模型分组」属于目标分组，与网段或路径条件取「且」，避免影响其他分组。
黑名单：新建规则，条件为「模型分组」属于目标分组 +「客户端 CIDR」属于某个网段，动作选「拒绝本次调用」并填原因码，保存并确认。需要按路径限制时，把条件换成「请求路径」等于或以前缀匹配某个路径，动作同样选拒绝。
白名单：先建一条「放行」规则（条件为「模型分组」属于目标分组 +「客户端 CIDR」属于允许的网段，命中后结束匹配）并排在前面；在其后排一条兜底「拒绝本次调用」规则，条件只限定「模型分组」属于目标分组，原因码写明「不在名单内」。
大陆来源限制：在「客户端 CIDR」中勾选「中国大陆」，无需逐个填写网段。只拦截已识别的非大陆来源，可选「不属于」并配「拒绝本次调用」；严格只允许大陆来源，使用前面的两条白名单规则，把允许的网段换成「中国大陆」，未识别、内网或缺少可信来源 IP 的请求由后面的兜底规则拒绝。预置范围支持 IPv4 与 IPv6，不含港澳台；判断依据是访问出口 IP，无法据此确认使用代理的用户实际所在地。
你会看到：名单外的请求返回 403 permission_denied，deniedBy 为 routePolicy，details 中带配置的原因码；名单内的请求正常返回。带 X-Forwarded-For、X-Real-IP 或 Forwarded 等伪造来源头的请求不能绕过——判定用的是网关实际看到的客户端地址。
注意：产品没有「默认拒绝」开关，白名单要按上面的两条规则组合实现；没有转发目标的普通规则是增强规则、不会结束判定，不能代替「放行」。被拒绝的请求同样记入「运行总览 › 请求」，状态为「已拦截」，可按接入凭据筛选追溯。
16.10 跨租户隔离
你会看到：租户与身份只从已验证的会话推导，客户端自行添加的租户、根权限或用户标识请求头一律被忽略；用不属于本租户的资源编号请求返回 404 而不是「无权限」，不泄露资源是否存在；平台级接口对租户管理员返回 403。
| 越权尝试 | 结果 |
|---|---|
| :-- | :-- |
| 正常列出本租户模型分组 | 200，结果全部属于本租户 |
| 附加伪造的租户、组织、用户或根权限请求头 | 200，仍是本租户数据，未提权 |
| 读取不属于本租户的资源编号 | 404，不透露存在性 |
| 访问平台级租户列表，或附加伪造根权限头 | 403 PERMISSION_DENIED |
| 在路径中放入其他租户的编号 | 404 |
注意：数据库层另有按租户的行级隔离策略，业务查询只会命中本租户的行。跨租户验证属于平台运维范畴，需在独立环境准备两个租户后由交付方执行，租户侧不需要也不应自行探测。
16.11 集成上线检查
- 插件所需权限已声明，绑定范围与失败策略已确认，「执行统计」中有预期的执行记录，新版本已在试点范围验证且旧版本可切回。
- AI 生成内容标识已在流式与非流式输出中核对；内置策略规则的命中顺序已在「确认变更」中核对。
- 访问密钥已存入密钥管理系统，按最小权限账号创建，不再使用的已撤销；客户端已处理 401、403、429 等错误响应。
- 域名与路由绑定已通过「路由试算」核对，变更已与平台管理员确认。
能力说明
| 不提供的能力 | 替代做法 |
|---|---|
| :-- | :-- |
| 在管理后台按单个接口启用或禁用平台管理 API | 用角色权限域限制调用方可用的接口范围，或撤销访问密钥使其整体失效（见 16.7） |
| 访问密钥按接口勾选权限范围 | 为自动化任务单独创建权限最小的账号，再用该账号创建访问密钥（见 16.7） |
| 可自定义时间窗与随机串有效期的防重放策略 | 平台已内置时间窗校验与随机串防重放；需要更强策略时由调用方或上游系统实现（见 16.7） |
| 独立的 IP 与路径黑白名单入口，以及在 API 密钥上直接绑定 IP | 用流量规则的「客户端 CIDR」与「请求路径」条件配合「拒绝 / 放行」动作实现（见 16.9） |
| 任意国家或地域的自定义选择器 | 「客户端 CIDR」提供「中国大陆」系统预置；其他地区可填写具体网段，或在接入层配置地域限制（见 16.9） |
| 租户侧的 Web 应用防护（WAF）规则集配置页 | 租户侧不提供 WAF 配置入口；应用层攻击防护在部署层由平台统一实施，需要调整时联系平台管理员 |
| 网关到上游的双向 TLS（客户端证书） | 上游用 HTTPS 单向认证配合 API 密钥或 OAuth；确需 mTLS 时在网关之外用支持双向 TLS 的出口代理或边车完成 |
| 引用外部 KMS 或 Vault 中的密钥 | 上游凭据由平台加密存储，界面与接口只回显指纹；轮换时在供应商账号中更新 |
| 插件内的持久状态、熔断、并发计数与签名校验宿主函数 | 并发与熔断使用流量规则的「应用限额」（见第 15 章）；其余逻辑由上游系统承担 |
| 插件包直接以源码压缩包上传 | 按 SDK 的 README 用 zr-plugin build 生成插件包后再上传（见 16.2） |
---