最有效防护！Apache APISIX IP黑白名单实战指南

你是否曾因恶意IP攻击导致服务异常？还在手动封禁可疑IP地址浪费时间？本文将带你掌握Apache APISIX的IP黑白名单功能，通过5分钟配置构建网络安全的第一道防线。读完本文你将学会：

• 快速配置IP白名单/黑名单
• 灵活使用CIDR网段限制
• 实时更新防护规则无需重启
• 自定义拦截响应信息

什么是IP黑白名单？

IP黑白名单（IP Whitelisting/Blacklisting）是网络安全中的基础访问控制机制。通过将IP地址或网段列入白名单（允许访问）或黑名单（拒绝访问），可以精确控制谁能访问你的服务。Apache APISIX通过plugins/ip-restriction.lua插件实现这一功能，支持单个IP、多个IP及CIDR（无类别域间路由）范围的限制。

插件核心属性解析

官方文档详细定义了插件的三个核心属性，使用时需注意白名单与黑名单不可同时启用：

参数名	类型	必选项	默认值	描述
whitelist	array[string]	否		允许访问的IP/CIDR列表
blacklist	array[string]	否		禁止访问的IP/CIDR列表
message	string	否	"Your IP address is not allowed"	拦截时返回的提示信息

5步启用IP限制插件

1. 获取管理员密钥

从配置文件中提取admin_key，用于后续API调用授权：

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

2. 配置白名单示例

以下命令将创建路由并启用IP白名单，仅允许本地IP(127.0.0.1)和113.74.26.0/24网段访问：

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "uri": "/index.html",
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    },
    "plugins": {
        "ip-restriction": {
            "whitelist": [
                "127.0.0.1",
                "113.74.26.106/24"
            ],
            "message": "IP访问被拒绝，请联系管理员"
        }
    }
}'

3. 测试访问控制效果

使用允许的IP访问将返回200状态码：

curl http://127.0.0.1:9080/index.html -i
# HTTP/1.1 200 OK

使用禁止的IP访问将被拦截：

curl http://127.0.0.1:9080/index.html -i --interface 127.0.0.2
# HTTP/1.1 403 Forbidden
# {"message":"IP访问被拒绝，请联系管理员"}

4. 动态更新规则

通过Admin API实时更新IP列表，无需重启服务：

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "uri": "/index.html",
    "plugins": {
        "ip-restriction": {
            "whitelist": [
                "127.0.0.2",  // 更新为新允许的IP
                "192.168.1.0/24"
            ]
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {"127.0.0.1:1980": 1}
    }
}'

5. 禁用插件

当需要临时关闭IP限制时，可通过清除插件配置实现：

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "uri": "/index.html",
    "plugins": {},  // 清空插件配置
    "upstream": {
        "type": "roundrobin",
        "nodes": {"127.0.0.1:1980": 1}
    }
}'

最佳实践与注意事项

CIDR网段高效配置

对于需要批量允许/禁止某一网段的场景，使用CIDR表示法更高效。例如：

• 192.168.1.0/24 表示192.168.1.0-192.168.1.255整个网段
• 10.0.0.0/8 涵盖所有10开头的IP地址

与其他安全插件协同

IP限制插件可与limit-req（限流）、key-auth（密钥认证）等插件组合使用，构建多层次安全防护体系。配置示例可参考t/cli/test_ip.sh测试用例。

实时监控与日志

启用IP限制后，建议通过prometheus插件监控访问情况，被拦截的请求会记录在APISIX日志中，可通过utils/log-util.lua进行日志分析。

总结

Apache APISIX的IP限制插件为服务提供了简单而强大的访问控制能力。通过本文介绍的方法，你可以在几分钟内完成配置，有效阻挡恶意IP访问。记住安全是一个持续过程，建议定期审计你的IP规则，并结合APISIX的其他安全特性构建完整防护体系。

需要更高级的访问控制？可参考authz-casbin插件实现基于角色的访问控制(RBAC)。