章亦春(agentzh)的黑名单设计理念可以总结为

APISIX 黑名单管理系统使用指南

功能概述

APISIX黑名单管理系统提供了高性能、分布式的IP黑白名单管理能力，支持通过RESTful API进行管理，并能在集群环境下保持一致性。

API端点

1. 黑名单管理

获取黑名单列表

GET /apisix/admin/plugin_metadata/ip-blacklist

更新黑名单

PUT /apisix/admin/plugin_metadata/ip-blacklist
Content-Type: application/json

{
  "redis_host": "127.0.0.1",
  "redis_port": 6379,
  "redis_key": "apisix:ip_blacklist",
  "redis_database": 0,
  "use_redis": false,
  "redis_timeout": 1000,
  "id": "ip-blacklist",
  "blacklist": [
    {
      "ip": "192.168.1.100",
      "start_time": 1747870000,
      "expire": 3600
    }
  ]
}

添加IP到黑名单

POST /apisix/admin/security/ip_blacklist
Content-Type: application/json

{
  "ip": "192.168.1.1",
  "expire": 3600,
  "reason": "可疑活动"
}

从黑名单删除IP

DELETE /apisix/admin/security/ip_blacklist/{ip}

2. 白名单管理

添加IP到白名单

POST /apisix/admin/security/advanced_firewall/whitelist
Content-Type: application/json

{
  "ip": "10.0.0.1",
  "ttl": 86400
}

从白名单移除IP

DELETE /apisix/admin/security/advanced_firewall/whitelist/{ip}

3. 认证管理

重置IP的认证状态

POST /apisix/admin/security/advanced_firewall/reset/{ip}

获取认证统计信息

GET /apisix/admin/security/advanced_firewall/stats

命令行工具

Redis直接操作黑名单

查看当前黑名单列表

redis-cli -a PASSWORD SMEMBERS security:blacklist:ip

添加IP到黑名单

redis-cli -a PASSWORD SADD security:blacklist:ip 192.168.1.100

从黑名单移除IP

redis-cli -a PASSWORD SREM security:blacklist:ip 192.168.1.100

清空黑名单

redis-cli -a PASSWORD DEL security:blacklist:ip

配置示例

启用IP黑名单插件

plugins:
  - name: ip-blacklist
    enable: true
    config:
      rejected_code: 403
      message: "您的IP已被封禁"

最佳实践

1. 分层缓存策略：使用ETCD存储长期配置，Redis缓存高频访问数据，本地内存做极速检查
2. 定期清理过期记录：设置合理的过期时间，避免黑名单无限增长
3. 监控与告警：对黑名单命中率设置监控，异常情况及时告警
4. 定期备份：重要的黑名单数据需要定期备份
5. 渐进式防御：先警告，再挑战验证，最后才加入黑名单

故障排除

1. 黑名单未生效：检查插件是否启用，配置是否正确
2. 误判处理：提供快速将IP从黑名单中移除的机制
3. 性能问题：检查Redis连接池配置，确保连接数充足

安全建议

1. 设置复杂的Redis密码并定期轮换
2. 限制对管理API的访问，只允许内网或VPN访问
3. 记录所有对黑名单的修改操作，便于审计
4. 定期检查日志中是否有可疑的API调用模式

章亦春(agentzh)的黑名单设计理念可以总结为:
极简API - 只提供必要的增删改查操作
多层缓存 - 内存+Redis+ETCD的优化策略
原子一致 - 使用ETCD事务确保原子性操作
容错自愈 - 在组件失效时仍能正常工作
高性能 - 优化查询路径减少延迟
可扩展 - 设计支持未来功能增强
清晰错误处理 - 每个操作都有明确的错误处理
集群友好 - 适应分布式系统环境
这种设计既满足了大规模APISIX集群的需求，又保持了章亦春一贯的简洁高效风格。