OpenResty是唯一能支撑动态IP黑名单落地的方案，因其内置lua-resty-redis、init_worker_by_lua_file及ngx.shared.DICT等能力，而原生Nginx不支持运行时Lua加载与共享内存操作。
OpenResty 是唯一能真正支撑动态 IP 黑名单落地的方案，普通 Nginx 不支持运行时加载 Lua 脚本、共享内存和 Redis 连接，硬上会卡在 lua_shared_dict 不存在或 redis-cli 调用失败这类报错上。
必须用 OpenResty，不能只装 nginx + lua-module
很多人踩坑是因为以为“给 Nginx 编译加个 lua-module 就行”，实际不行：lua-resty-redis、init_worker_by_lua_file、ngx.shared.DICT 这些关键能力只有 OpenResty 官方打包版本才默认启用且 ABI 兼容。CentOS 上直接 yum install openresty，别碰源码编译；Ubuntu 用 apt install openresty，确认版本 ≥ 1.21.4.2（2026 年推荐用 1.25.3.1）。
验证是否真装对了：openresty -v 输出里要有 built by gcc 和 OpenResty 字样，不是 nginx version: 开头；再跑 openresty -p /usr/local/openresty/nginx/ -t 看配置语法是否通过。
- 错误现象：
unknown directive "lua_shared_dict"→ 说明你还在用原生 Nginx - 错误现象：
attempt to index global 'resty' (a nil value)→lua-resty-redis没加载，OpenResty 版本太旧或路径错 - 别手动改
nginx.conf的lua_package_path，OpenResty 自带路径已预设好
共享字典大小和定时加载脚本位置很关键
lua_shared_dict ip_blacklist 50m 必须写在 http 块顶层，不能塞进 server 或 location。50MB 是保守值：按每个 IPv4 地址字符串平均占 15–20 字节算，能存约 250 万个 IP；IPv6 地址更长，若预期要存，建议直接设 100m。设太小会导致 ngx.shared.ip_blacklist:set() 静默失败（不报错但不生效）。
全量同步黑名单必须用 init_worker_by_lua_file，不是 init_by_lua_block。后者在 master 进程初始化时执行一次，worker 进程起不来；前者为每个 worker 启动独立定时器，每 60 秒拉一次 Redis 的 SMEMBERS ip_blacklist，然后 flush_all() 再逐条 set(ip, true)。脚本路径如 /usr/local/openresty/nginx/conf/lua/load_blacklist.lua，注意文件权限是 openresty 用户可读。
- Redis 数据结构必须是
SET，不是STRING或HASH，否则SMEMBERS拉不到数据 - 如果 Redis 有密码，
redis:auth()必须在connect()之后、smembers()之前调用，顺序错就认证失败 - 不要在
access_by_lua_file里直连 Redis 查 IP——那会把每次请求都拖成毫秒级延迟
真实客户端 IP 获取必须提前处理，不能靠 Lua 临时解析
ngx.var.real_ip 不是 Nginx 原生变量，得靠 http 块里配 map 指令生成。常见错误是只读 X-Forwarded-For，没考虑多层代理下该 header 是逗号分隔的字符串，也没兼容 IPv6 地址格式（含冒号和方括号）。
正确做法是在 http 块顶部加：
map $http_x_forwarded_for $real_ip {
~^([0-9.]+),?.*$ $1;
~^([0-9a-fA-F:]+),?.*$ $1;
default $remote_addr;
}
这样 $real_ip 才是干净可用的 IP 字符串。Lua 脚本里直接用 ngx.var.real_ip，别再调 ngx.req.get_headers()["X-Real-IP"] —— 那个值可能为空或被伪造。
- 如果你用的是云 WAF（如阿里云、Cloudflare），它们通常会把真实 IP 放在
X-Forwarded-For最右，map规则需微调 - 测试时用
curl -H "X-Forwarded-For: 1.2.3.4, 5.6.7.8" http://your.site/，看日志里记录的是哪个 IP - 没配
map就直接在 Lua 里做字符串切分，遇到 IPv6 或异常格式会 crash
封禁逻辑必须内存级判断，403 返回前留日志
真正拦截只做三件事：local ip = ngx.var.real_ip → local blocked = ngx.shared.ip_blacklist:get(ip) → if blocked then ngx.exit(403) end。整个过程在共享内存里完成，耗时 redis:get()，那是自废武功。
封禁动作发生时，务必加日志：ngx.log(ngx.WARN, "Blocked IP: ", ip)。这条日志会落到 error_log 文件（默认 /usr/local/openresty/nginx/logs/error.log），方便后续用 grep "Blocked IP" error.log | awk '{print $5}' | sort | uniq -c | sort -nr 统计高频攻击源。
- 别用
ngx.say()或ngx.print()，403 响应体应为空，避免暴露服务端信息 - 如果需要返回自定义 JSON 提示，用
ngx.header.content_type = "application/json"+ngx.print('{"code":403,"msg":"Forbidden"}')，但会略增开销 - 检查
error.log时注意时间戳是否同步，Nginx 默认用系统本地时间，跨时区集群建议统一 NTP
共享内存和 Redis 的最终一致性是最大盲区：定时同步有最多 60 秒延迟，管理接口写入 Redis 后，旧请求仍可能放行。生产环境必须接受这个窗口期，不能指望“实时生效”。
