IP 黑名单和白名单是 API 网关提供的安全防护能力之一。您可以通过配置黑、白名单来拒绝或允许特定 IP 的访问请求。API 网关支持在实例级别、服务级别和路由级别配置 IP 黑名单和白名单，满足精细化的访问控制诉求。本文介绍如何为API 网关设置黑名单和白名单。 ## 前提条件 * 已创建网关实例。详情请参见 [创建实例](https://www.volcengine.com/docs/6569/85693)。 * 已创建服务，具体操作可参见 [创建服务](https://www.volcengine.com/docs/6569/85695#%E5%88%9B%E5%BB%BA%E6%9C%8D%E5%8A%A1)。 * 已创建路由。详情请参见 [创建路由](https://www.volcengine.com/docs/6569/179038)。 ## 使用限制 * 一个资源维度仅支持一个黑白名单插件。 * 同一插件内可以同时定义黑名单和白名单。 * 黑名单和白名单同时生效时，黑名单生效优先级更高。 ## 操作步骤 1. 登录 [API 网关控制台](https://console.volcengine.com/veapig)。 2. 在左侧导航栏选择 **插件管理 \> IP 黑白名单插件**。 3. 在IP 黑白名单插件页面，单击 **创建插件**，配置插件参数。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2c3c08ce0c7dc030c160b8e69189d722.png) |配置项 |说明 | |---|---| |生效级别 |选择 IP 黑白名单插件的生效级别，包括：|\ | ||\ | |* **实例级别**：黑白名单在实例中生效，需要指定生效的目标实例。|\ | |* **服务级别**：黑白名单在服务内生效，需要指定生效的目标实例和目标服务。|\ | |* **路由级别**：黑白名单在路由内生效，需要指定生效的目标实例、目标服务和目标路由。 | |备注 |输入关于当前 IP 黑白名单插件的备注信息，可以为空。 | |IP 黑/白名单 |勾选需要配置 **黑名单** 或 **白名单**。|\ | ||\ | |* **黑名单**：禁止特定 IP 访问。在网关场景针对不友好访问执行来源 IP 封禁。|\ | |* **白名单**：允许特定 IP 访问。在网关场景只开放受信任来源 IP 访问。 | |IP 列表 |输入合法的 IPv4 CIDR 的 IP，输入完成后使用回车确认。支持输入多个，用分号`;`或回车隔开。 | |自定义获取 IP |是否开启自定义获取 IP。|\ | ||\ | |* **IP 获取方式**：当前只支持 **基于 X\-Forward\-For**。|\ | ||\ | |:::warning|\ | |X\-Forward\-For 转发过程中存在被篡改的风险，API 网关无法检验 X\-Forward\-For 内容的可信度。|\ | ||\ | |:::|\ | |* **拦截位置**：在多层转发链路上选择进行访问控制的 IP 位置，IP 信息来自 X\-Forward\-For。 | 4. 单击 **确定**，完成配置。 ## 结果验证 ### 查看配置配置完成后，在 **IP 黑白名单插件** 列表将生成一条新的插件记录。插件状态为 **已启用**，表示插件功能生效。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_502605d2fb5c89eee84f787181884dc2.png =914x) ### 认证测试 1. 使用 API 网关实例中配置的域名访问服务，本例中以黑名单为例，当访问请求的 IP 地址不是黑名单地址时。 ```Bash curl -H "Host: apig-example.com" http://14.xxx.xxx.xxx ``` 预期结果如下，表示能够通过 API 网关访问到后端的服务。 ```Bash Welcome to nginx!

Welcome to nginx!

If you see this page, the nginx web server is successfully installed and working. Further configuration is required.

For online documentation and support please refer to nginx.org.
Commercial support is available at nginx.com.

Thank you for using nginx.

``` 2. 使用 API 网关实例中配置的域名访问服务，当访问请求的 IP 地址为黑名单地址时。 ```Bash curl -H "Host: apig-example.com" http://14.xxx.xxx.xxx ``` 预期结果如下，匹配到 IP 黑名单的请求将被拒绝，并提示`ip restriction deny`。 ```Bash ip restriction deny ```