Redis Lua 脚本怎样限制单次执行范围

如果你想限制 Redis Lua 脚本“每次最多做多少工作”，只调一个时间参数是不够的。Redis 的执行阈值主要负责在脚本运行过久时让其他客户端收到 BUSY，它不会像应用层的 context timeout 那样自动把脚本截断；真正可控的做法是给脚本传入 batch_size 和 cursor，让每次 EVAL 只处理有限窗口。

官方地址：https://redis.io/docs/latest/develop/programmability/

把“时间阈值”和“单次工作量”分开设计：阈值用于暴露慢脚本和保护客户端体验，批量大小与游标用于从源头缩小一次 EVAL 的处理范围。

Redis 的时间阈值到底限制了什么

Redis Lua 脚本在服务端执行时会阻塞其他普通命令，这是原子性语义的一部分。当前 Redis 文档把触发繁忙响应的配置称为 busy-reply-threshold，默认值是 5 秒；当脚本超过这个阈值，Redis 会开始向大多数其他请求返回 BUSY，但脚本本身仍然继续运行。

因此，下面这个参数更像“慢脚本告警线”或“繁忙状态触发线”，而不是“每个脚本最多运行多少毫秒”的硬杀开关。

先读取阈值，再决定是否临时调整

排查慢脚本时，先读取当前配置，不要直接把生产环境改成一个看起来合理的数字。阈值单位是毫秒，运行时用 CONFIG SET 修改只影响当前实例配置；如果要让重启后的配置保持一致，还需要同步修改配置文件或按部署方式持久化配置。

# 读取当前的脚本繁忙阈值，先确认实例实际使用的参数名和值。
redis-cli CONFIG GET busy-reply-threshold

# 仅用于经过评估的实例：把触发 BUSY 的阈值临时调整为 3000 毫秒。
redis-cli CONFIG SET busy-reply-threshold 3000

# 修改后再次读取，确认运行时配置已经生效。
redis-cli CONFIG GET busy-reply-threshold

不同 Redis 发行版或较老部署可能仍以 lua-time-limit 出现在配置材料中。遇到参数不识别时，应先用当前实例的 CONFIG HELP、CONFIG GET 或对应版本文档确认名称，不要把旧配置名直接复制到另一套环境。

阈值调得太大，其他客户端可能长时间处于等待或 BUSY；调得太小，又可能让正常但稍重的脚本频繁暴露为慢脚本。它适合帮助发现问题，不适合代替批量设计。

脚本进入 BUSY 后为什么不能随便杀

当其他客户端看到类似 BUSY Redis is busy running a script 的错误时，通常只有少数管理命令还能执行。SCRIPT KILL 只能终止尚未修改数据集的脚本，因为中断已经写入数据的脚本会破坏 Lua 脚本的原子性保证。

# 只在确认当前 EVAL 尚未写入数据时尝试终止脚本。
redis-cli SCRIPT KILL

# 如果脚本已经写过数据，SCRIPT KILL 可能返回 UNKILLABLE；
# 只有明确接受硬停止与未持久化变更风险时才考虑下面的命令。
redis-cli SHUTDOWN NOSAVE

这也是为什么不能把 busy-reply-threshold 理解成“到点自动回滚”。Redis 不会为了满足时间限制而把一个已经产生写入效果的脚本切成半完成状态。工程上更可靠的方向，是让脚本在进入执行前就知道本次最多处理多少条数据。

真正限制单次工作量：batch_size 加 cursor

下面用一个列表作为待处理集合，用另一个集合记录已经处理到的成员。脚本每次从 cursor 开始读取，最多取 batch_size 条；如果还有数据，就返回下一次调用要使用的游标；如果已经到末尾，则返回 -1。

示例把两个 key 都写成带有同一个 hash tag 的形式，便于 Redis Cluster 把它们放在同一个槽位。真实业务里还要保证成员的处理动作幂等，避免调用方在网络超时后重试造成重复副作用。

-- 只处理一个有限窗口，避免一次 EVAL 扫描整个大集合。
local start = tonumber(ARGV[1]) or 0
local requested = tonumber(ARGV[2]) or 50

-- 在脚本内再设一个上限，避免调用方传入过大的批量值。
local batch = math.min(math.max(requested, 1), 100)
local stop = start + batch - 1

-- KEYS[1] 是待处理列表；一次 LRANGE 最多取 batch 个成员。
local items = redis.call('LRANGE', KEYS[1], start, stop)
for _, item in ipairs(items) do
    -- 示例用集合记录处理结果；生产逻辑应替换为幂等的业务动作。
    redis.call('SADD', KEYS[2], item)
end

-- 不足一批说明已经到末尾，调用方可停止继续 EVAL。
local next_cursor = start + #items
if #items 

调用时把 key 列表和两个参数分开传入。KEYS 应只放脚本实际访问的 key，ARGV 只放字段值、数量或游标等普通参数；不要在脚本里拼接一个未声明的 key 名称。

# 两个 key 使用同一个 hash tag，cursor=0，单次最多处理 20 个成员。
redis-cli EVAL "local start=tonumber(ARGV[1]) or 0; local requested=tonumber(ARGV[2]) or 50; local batch=math.min(math.max(requested,1),100); local items=redis.call('LRANGE',KEYS[1],start,start+batch-1); for _,item in ipairs(items) do redis.call('SADD',KEYS[2],item) end; local next=start+#items; if #items 

分片脚本还有三个容易忽略的边界

列表是否会变化：上例用的是按下标读取的列表。如果处理期间有其他调用插入或删除列表前部，下一次游标可能跳过或重复成员。适合重试的任务应使用稳定的任务 ID、幂等标记，或改用更适合游标扫描的数据结构。

阈值不是事务超时：客户端的网络超时、连接池超时和 Redis 的 BUSY 阈值是三件事。客户端先超时，不代表 Redis 里的 Lua 已经停止；重试前应根据业务幂等性判断是否可能重复处理。

配置修改不是持久化：CONFIG SET 改的是运行中的实例。容器、托管 Redis 或配置文件管理工具可能有自己的持久化方式，不要只改运行时值就认为重启后仍然有效。

什么时候该拆掉 Lua，而不是继续加限制

如果脚本需要扫描大量成员、做复杂字符串计算，或者单批处理仍然会让 Redis 长时间进入繁忙状态，就不要继续把更多逻辑塞进 EVAL。可以把每批工作压到较小范围，由应用层保存游标并循环调用；如果任务本身允许异步化，再把工作移到专门的任务处理流程。Lua 更适合把一小段必须原子完成的读写放在 Redis 内，而不是承载长时间离线计算。

常见问题

Redis Lua 有没有每个脚本独立的硬超时参数？

常用配置主要控制脚本运行过久时的繁忙响应，并不会安全地强制截断任意脚本。要限制单次业务工作量，应在脚本中限制批次并由调用方续传游标。

超过阈值后脚本会自动回滚吗？

不会。阈值触发的是 BUSY 行为，不是事务回滚。脚本仍按自己的逻辑继续执行，已经写入的数据也不会因为超过阈值自动撤销。

为什么 SCRIPT KILL 有时返回 UNKILLABLE？

因为脚本已经执行过写命令。为了保留原子性，Redis 不允许此时只杀掉脚本而留下半完成数据；应等待它结束，或在明确风险后执行硬停止。

batch_size 设置得越大越好吗？

不是。批量越大，单次网络往返越少，但脚本持有 Redis 执行权的时间、返回数据量和重试代价也会上升。应结合成员大小、写入动作和可接受延迟选择上限，并保留游标续跑能力。

参考入口：https://redis.io/docs/latest/develop/programmability/eval-intro/；BUSY 错误说明：https://redis.io/docs/latest/develop/reference/errors/common/busy/；SCRIPT KILL：https://redis.io/docs/latest/commands/script-kill/。