Redis Lua脚本无法直接获取客户端IP,因沙箱环境使CLIENT LIST返回全量连接信息且无法定位当前请求源;必须由应用层(如Nginx、网关)提取IP并作为参数传入,再通过原子化脚本实现限流/拦截。

Redis 的 Lua 脚本本身不能直接获取客户端 IP,必须由应用层传入;所谓“动态 IP 黑名单拦截”,本质是应用在收到请求时把 ip 作为参数传给 Lua 脚本,由脚本完成原子化判断与限流/拦截逻辑。
为什么不能在 Lua 脚本里用 redis.call("CLIENT", "LIST") 提取 IP?
Redis 的 Lua 环境被严格沙箱化:CLIENT LIST、CLIENT GETNAME 等命令虽能执行,但返回的是连接元信息(含 IP),而 Lua 脚本中调用 redis.call("CLIENT", "LIST") 返回的是**所有连接的字符串列表**,无法定位当前请求来源——因为 Lua 执行时已脱离原始网络上下文。官方明确不支持在脚本中识别调用方 IP。
常见错误现象:(error) ERR Error running script (call to f_...): @user_script:3: user_script:3: attempt to concatenate a table value (field '?'),就是试图解析 CLIENT LIST 返回的多行字符串时类型错乱。
正确做法是:由 Nginx、Spring Cloud Gateway 或业务服务在转发请求前,从 TCP 连接或 HTTP 头(如 X-Forwarded-For)提取 ip,作为参数传入 Lua 脚本。
用 EVAL 实现带时间窗口的 IP 拦截脚本
典型场景:1 分钟内同一 IP 请求超过 100 次即加入黑名单,持续 15 分钟;后续请求直接拒绝。
脚本需兼顾原子性、过期控制和状态复位,推荐结构如下:
local ip = KEYS[1]
local limit = tonumber(ARGV[1]) or 100
local window = tonumber(ARGV[2]) or 60
local ban_duration = tonumber(ARGV[3]) or 900
<p>-- 先查是否已被拉黑(用 SET + EX 实现)
if redis.call("EXISTS", "blacklist:" .. ip) == 1 then
return 1 -- 已拉黑,拦截
end</p><p>-- 使用 INCR + EXPIRE 原子计数(避免 key 不存在时多次 SETEX)
local count_key = "ip_count:" .. ip
local count = redis.call("INCR", count_key)
if count == 1 then
redis.call("EXPIRE", count_key, window)
end</p><p>if count > limit then
redis.call("SET", "blacklist:" .. ip, "1")
redis.call("EXPIRE", "blacklist:" .. ip, ban_duration)
return 1
end</p><p>return 0关键点说明:
-
KEYS[1]必须传 IP 字符串,不能含特殊字符(建议提前校验或哈希,如sha256(ip)) - 不要用
GETSET或SETEX替代INCR + EXPIRE,前者在 key 不存在时会重置 TTL,导致计数窗口漂移 - 黑名单用
SET+EXPIRE而非SETEX,便于后续扩展(如记录封禁原因) - 返回值约定:0=放行,1=拦截,应用层据此返回 429 或 403
在不同客户端中安全传参与调用
参数注入风险真实存在——若 IP 来自用户输入且未清洗,可能触发 Lua 语法错误或绕过逻辑。
安全实践包括:
- Nginx 中用
$remote_addr或可信头(如$http_x_real_ip)取 IP,避免直接信任X-Forwarded-For - Java(Lettuce)调用示例:
redis.eval(script, ScriptOutputType.INTEGER, Collections.singletonList(ip), limit, window, ban_duration),注意KEYS和ARGV严格分离 - Python(redis-py)必须用
eval(script, keys=[ip], args=[limit, window, ban_duration]),不能合并为一个 list - IP 若含冒号(如 IPv6)或空格,需在应用层做 URL 编码或 base64,Redis 键名不支持非法字符
真正容易被忽略的是:当多个网关实例共享同一 Redis 时,IP 提取逻辑必须一致(比如都走 X-Real-IP 而非混合使用),否则同一用户在不同节点上计数分裂,导致漏拦或误拦。Lua 脚本再严谨,也救不了上游数据源的不一致。


















