网关插件是安装在**专属网关**实例上的扩展能力模块，用于在请求或响应的处理链路中对数据进行干预。通过安装并配置插件规则，您可以实现认证凭据的位置转换、自定义签名与鉴权、审计与风控拦截等能力，而无需修改后端服务。当前网关提供**凭据转换**插件和**自定义服务扩展**插件，本文介绍两种插件的适用场景、安装方式、规则配置等。

注意

当前仅 MCP 类型专属网关实例支持插件能力。

## 插件类型网关提供**凭据转换**和**自定义服务扩展**两种插件。 |**插件名称** |**用途** |**适用场景** | |---|---|---| |**凭据转换** |将请求中的认证凭据按配置规则转换后发往后端服务，未匹配规则或请求中不存在对应凭据时，插件会自动跳过，不影响请求继续转发。 |* 将 Header 或 Query 中的认证凭据写入 POST 请求的 JSON Body 指定路径。

* 将 Header 中的认证凭据写入 GET 请求的 Query 参数。

* 将凭据从原位置写入目标位置后，移除原 Header 或 Query 参数。

* 屏蔽内部认证 Header，并通过自定义 Header 向外部服务传递凭据，避免泄露内部认证 Header。 | |**自定义服务扩展** |将自有服务接入网关处理链路，当选择外部函数服务作为扩展服务后，网关会在请求或响应处理过程中调用该函数，并根据函数返回结果修改请求头、请求体、响应头或响应体，也可以直接返回自定义响应。 |* 自定义签名或鉴权：生成签名并写入 Header、Query 或 Body。

* 审计、风控与拦截：命中规则时直接返回响应，未命中时继续转发。 | ## 前提条件 * 已创建专属网关实例。配置操作，请参见[创建专属网关](https://docs.volcengine.com/docs/86681/2650647)。 * 已创建 MCP 服务，且服务状态为**运行中**。配置操作，请参见[创建 MCP 服务](https://docs.volcengine.com/docs/86681/1844857)。 * 已部署函数服务，且函数处于已发布或可调用状态。配置操作，请参见[部署函数服务](https://docs.volcengine.com/docs/86681/2684650)。 ## 安装插件 1. 登录 [AgentKit 控制台](https://console.volcengine.com/agentkit)。 2. 在左侧导航树中选择“网关 \> 网关总览”，在“专属网关”页签下，单击 MCP 类型网关名称。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_935c19f92794da108658dc9e84536555.png) 3. 在“插件”页签单击目标插件“操作”列的“安装”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_395820beadace8eb24e38562d7c15523.png) 4. 在弹出的对话框中，单击“确认安装”按钮，完成插件安装。

说明

插件安装成功后，当前网关将会具备该插件功能，但不会自动影响线上请求，需配置规则后才会生效。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_542f317fb2f5a8fadeec678c1c5dd19a.png) 5. （可选）卸载插件。后续如果确认插件不再使用，您可卸载插件。 1. 在“插件”页签下，单击目标插件“操作”列的“卸载”按钮。

注意

卸载插件可能对此网关线上流量产生影响，请谨慎操作。

不支持卸载存在已启用规则的插件，如需卸载请参考下文“管理规则”部分，停用或删除全部规则。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_7106fafbb0dba0dce3310d7c0bd1f963.png) 2. 弹出的对话框中，单击“确认卸载”按钮，完成插件卸载。 ## 配置插件规则 ### 添加规则插件安装完成后，您需要为插件添加相关规格后才能对线上请求生效。**当前仅支持在 MCP 服务维度配置插件规则**。 1. 登录 [AgentKit 控制台](https://console.volcengine.com/agentkit)。 2. 在左侧导航树中选择“网关 \> 网关总览”，在“专属网关”页签下，单击 MCP 类型网关名称。 3. 选择“插件”页签，在插件列表中，单击目标插件“操作”列的“规则配置”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c6f8f1f678ce573cb352f10dbbc7e800.png) 4. 单击“添加规则”按钮，参考下表配置插件规则。凭据转换规则参数配置请参考下表，配置凭据转换规则。

说明

每个规则最多可配置 10 个配置组。

如果一则规则中配置了多个配置组，会按照配置组从上到下的顺序进行匹配，您可通过配置组右上方的“上移”“下移”按钮调整顺序。

|参数 |说明 | |---|---| |**基础配置** || |生效范围 |选择插件生效的资源范围，当前仅支持 MCP 服务。 | |生效资源 |选择插件规则生效的 MCP 服务。仅可选择状态为「运行中」且未配置该插件规则的 MCP 服务，支持同时选择多个。

说明

如果凭据转换插件规则“生效资源”中的 MCP 服务被删除，系统将自动将其从该插件规则的“生效资源”中移除。

| |**插件特定配置** || |匹配条件 |匹配条件用于限定规则仅在指定请求下执行。

* **配置说明**

* 可不配置匹配条件，不配置规则对所有请求生效。

* 如需配置匹配条件，单击“添加匹配条件”按钮配置。每个配置组内最多可配置 ** 5 个**匹配条件。多个匹配条件之间是**且**的关系，即全部条件都匹配成功，规则才会执行。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_82d626c2c29efab9a8a320f2244d61fe.png)

* **参数说明**

* **匹配对象**：指定匹配的来源位置，当前支持 `Header`、`Query`和`Method`。

* **字段名**：需要匹配的`Header`或`Query`的字段名。`Header`名不区分大小写，系统加载时会统一转为小写。`Query`名必须区分大小写。

* **匹配方式**：字段值的匹配规则。

* **精确匹配**：字段值与匹配值完全一致时，才为命中规则。

* **前缀匹配**：字段值以匹配值开头时，即为命中规则。

* **匹配值**：与字段名对应的期望值，请求中该字段的值与此处配置完全一致时，命中规则。 | |转换配置 |转换配置用于指定对凭据的具体处理方式，支持将凭据写入指定位置或删除指定参数。

* **转换操作**：选择对凭据的处理方式。

* **Set：** 读取原始凭据并写入目标位置。

* **Remove**：删除指定目标参数，可用于将凭据写入目标位置后移除原始凭据。

* **原凭据位置**：仅转换操作为“Set”时需配置。原始凭据所在的位置，支持`Header`、`Query`。

* **原凭据字段名**：仅转换操作为“Set”时需配置。原始凭据对应的字段名，例如`Authorization`。

* **目标位置**：凭据写入的目标位置，支持`Header`、`Query`、`Body`。

* `Header`：需配置**目标字段名**，凭据写入的目标`Header`字段名称，例如`X-API-Key`。字段名大小写不敏感，保存后将被统一转为小写。

* `Query`：需配置**目标字段名**。凭据写入的目标`Query`参数名称，例如`api_key`。字段名**区分大小写**，请确保与后端服务实际接收的参数名一致。

* `Body`：需配置 **Body 格式**，支持 **JSON Body**、**表单 Body** 。

* **JSON Body**：适用于 Content\-Type 为`application/json`的请求，请在“JSON Body 写入路径”中填写 JSON Pointer 路径，例如`/api_key`。

* **表单 Body** ：适用于 Content\-Type 为`application/x-www-form-urlencoded`的请求，请在“表单 Body 字段名”中填写表单的字段名，如`api_key`。 | 自定义服务扩展规则参数配置请参考下表，配置自定义服务扩展规则。

说明

每个规则最多可配置 1 个请求阶段的配置组和 1 个响应阶段的配置组。

|参数 |说明 | |---|---| |**基础配置** || |生效范围 |选择插件生效的资源范围，当前仅支持 MCP 服务。 | |生效资源 |选择插件生效的资源，仅可选择**运行中且未配置过该插件规则**的 MCP 服务 **。** | |**插件特定配置** || |外接服务类型 |选择外接服务的类型，当前仅支持**函数服务**。 | |函数服务 |选择实际使用的外接函数服务，仅支持选择**已发布**或处于**可调用**状态的函数服务。若无可用函数服务请先创建，详见[部署函数服务](https://docs.volcengine.com/docs/86681/2684650)。 | |处理阶段 |选择插件介入的阶段。

* **请求阶段**：在请求发往后端服务前调用函数。

* **响应阶段：** 在后端服务返回响应后调用函数。 | |是否传递 Body |是否开启传递 Body 功能。

* **开启**：外接服务可读取并修改请求或响应 Body。

* **关闭**：Body 不会传递给外接服务，函数无法读取或修改请求/响应 Body。 | |超时时间 |调用外接函数服务时的最长等待时间。

* 默认值 30，单位为**秒，** 若函数在该时间内未返回结果，视为调用超时。

* 超时后的行为由**失败时放行**决定：开启失败时放行则跳过该插件继续处理请求，未开启失败时放行则返回错误信息。 | |失败时放行 |是否开启失败时放行功能。

* **开启**：函数调用失败时将跳过该插件继续处理请求。

* **未开启**：函数调用失败将直接返回错误。 | 5. 规则添加成功后会立即**启用**，您可在规则列表中查看规则生效状态。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0bf7a5e4c99068e3a09a33e877f833fd.png) ### 管理规则插件规则添加完成后，您可以对规则进行启用、停用、编辑或删除操作，以管理其对线上请求的处理行为。 1. 登录 [AgentKit 控制台](https://console.volcengine.com/agentkit)。 2. 在左侧导航树中选择“网关 \> 网关总览”，在“专属网关”页签下，单击 MCP 类型网关名称。 3. 选择“插件”页签，单击目标插件“操作”列的“规则配置”按钮，在规则列表中管理目标规则。 * **停用/启用规则**：单击目标规则“操作”列的“启用”/“停用”按钮。

说明

仅可启用已经停用的规则，或者停用已经启用的规则。

* **编辑规则**：单击目标规则“操作”列的“编辑”按钮。

说明

仅支持编辑规则中的“插件特定配置”，不支持修改规则生效的资源。

* **删除规则**：单击目标规则“操作”列的“删除”按钮。

注意

删除后不可恢复，请谨慎操作。

仅支持删除生效状态为未启用的规则，已启用的规则不支持删除，请停用后再删除。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d526c9f4d39dc6b9a59b8898e558dc97.png)