Redis Lua 脚本怎样理解复制命令边界

Redis Lua 脚本的复制边界，关键不在于“副本有没有收到这段 Lua”，而在于哪些写入效果会被传播。Redis 5.0 起脚本效果复制已经是默认方式，Redis 7.0 更是移除了源码复制；因此今天设计脚本时，应先把“脚本执行”“写命令”“AOF”和“replica”四个对象分开看。

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

一、先把复制对象分清楚

一次 EVAL 调用至少包含三层语义：客户端提交的脚本入口、Lua 脚本内部调用的 Redis 命令，以及这些命令对数据集造成的效果。复制系统关注的是最后两层之间的传播关系，而不是把客户端的调用形式原样转发。

历史上 Redis 有两种概念模式：

• 源码复制：master 把脚本发给 replica，让 replica 再执行一次。脚本必须在相同数据状态下产生相同写命令。
• 效果复制：master 收集脚本执行过程中产生的写命令，再把这些命令传播给 replica 和 AOF；replica 不重新执行 Lua。

Redis 5.0 起效果复制默认开启，Redis 7.0 起源码复制不再支持。所以“Lua 脚本怎样理解复制命令边界”更适合被理解为：脚本里哪些命令改变了数据，以及这些改变是否应该进入复制流。

二、写入命令怎样进入复制边界

效果复制可以用一个简单模型理解：脚本内部的读命令帮助计算，真正修改数据集的命令形成传播集合。这个集合会同时面对 AOF 与 replica，但它不代表所有 Lua 语句，也不代表脚本返回值。

Redis Lua API 提供 redis.set_repl() 对后续写命令设置传播目标。它可以选择 redis.REPL_ALL、redis.REPL_AOF、redis.REPL_REPLICA 或 redis.REPL_NONE。这是高级能力，缩小传播范围时必须确认 master、AOF 和 replica 仍能得到一致的业务状态。

-- 只让最终业务结果进入 AOF 与 replica，临时键不进入传播流
local temporary_key = KEYS[2]
local result_key = KEYS[1]

-- 计算阶段的写入只留在 master，避免传播中间状态
redis.set_repl(redis.REPL_NONE)
redis.call('SET', temporary_key, ARGV[1])

-- 恢复默认传播，让最终结果成为复制边界
redis.set_repl(redis.REPL_ALL)
redis.call('SET', result_key, ARGV[2])
redis.call('DEL', temporary_key)

-- 返回业务结果，不把返回值误认为复制内容
return redis.call('GET', result_key)

这段示例只用于说明 API 语义：如果临时键没有进入 AOF 或 replica，故障恢复时就不能把它当成持久状态使用。多数业务脚本不需要主动改变传播模式，保持默认的 REPL_ALL 更容易维护。

三、确定性规则应该怎样落到脚本

如果你维护的是 Redis 7 以上环境，效果复制降低了副本重跑脚本的确定性压力，但脚本仍然应该保持可解释：同一组输入要产生清楚、有限的写命令。这样排查主从差异、读取 AOF 和做故障演练时，边界更容易复盘。

如果要兼容 Redis 7 以前的源码复制场景，则需要额外遵守确定性规则：

• 不要让写入结果依赖系统时间、外部 I/O 或不可控的随机状态。
• 使用随机命令时，不要在其后继续做依赖随机结果的写操作，除非使用效果复制。
• 把时间、随机种子和业务决策作为 ARGV 显式传入，让输入边界可以被记录。
• 只通过 KEYS 传入脚本访问的键名，把键和普通参数分开，方便集群路由与代码审查。

脚本的原子执行解决的是“其他客户端不会插入到脚本中间”，复制语义解决的是“其他 Redis 实例怎样得到同一组数据修改”。这两个保证不要混成一个概念。

四、用一个库存脚本检查设计

下面的脚本只做一个边界明确的动作：库存大于零时扣减一个单位并返回新值，否则返回 -1。它不读取系统时间，不调用随机命令，也不把业务判断交给副本重新计算。

-- KEYS[1] 是库存键，ARGV[1] 是本次扣减数量
local stock_key = KEYS[1]
local amount = tonumber(ARGV[1])

-- 先校验调用参数，避免无效数量进入写入逻辑
if not amount or amount 

审查这个脚本时可以问四个问题：写入命令是不是只有预期的那一条？键名是否都来自 KEYS？数量和时间等外部输入是否来自 ARGV？是否误把返回值、日志或临时 Lua 变量当成复制数据？如果答案清楚，复制边界通常也就清楚了。

客户端使用 EVALSHA 只是通过脚本摘要命中脚本缓存，不会改变脚本的复制语义；读操作场景则应结合 EVAL_RO 或 EVALSHA_RO 的只读语义选择入口。

五、相关问题

Redis 7 还需要调用 redis.replicate_commands() 吗？

Redis 7 已经只支持脚本效果复制，该函数在新版本中不再承担切换到效果复制的必要职责。兼容旧版本时，才需要结合目标版本和配置确认是否显式调用。

脚本返回值会被复制到 replica 吗？

不会。复制关注的是数据修改命令；返回值只返回给发起脚本调用的客户端。

为什么脚本中用了随机命令还要关注确定性？

因为旧版本源码复制会让副本重新执行脚本。若环境仍可能采用源码复制，随机结果可能导致副本生成不同的写入；效果复制则传播已经产生的写命令。