最有效防护！Apache APISIX IP黑白名单实战指南
【免费下载链接】apisix The Cloud-Native API Gateway 
项目地址: https://gitcode.com/GitHub_Trending/ap/apisix
你是否曾因恶意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)。
【免费下载链接】apisix The Cloud-Native API Gateway 项目地址: https://gitcode.com/GitHub_Trending/ap/apisix
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
