Redis FUNCTION LOAD 怎样部署函数库

Redis FUNCTION LOAD 接收完整的 Lua 函数库源码；源码第一行声明引擎和库名，通过 redis.register_function 注册可调用函数。首次加载用 FUNCTION LOAD，更新同名库用 FUNCTION LOAD REPLACE，业务调用使用 FCALL 加函数名。下面用一个不访问数据键的版本标识函数演示部署，便于把加载问题和数据操作问题分开。

官方地址：https://redis.io/

准备独立的 Lua 函数库文件

示例适用于支持 Redis Functions 的 Redis 7.0 及以上服务。把下面内容保存为 deploy_catalog.lua，首行前不要插入空行或文件标记。这里的 deploy_catalog 是库名，catalog_release 是对外函数名，返回的 release-a 是这个示例自行约定的版本标识。

#!lua name=deploy_catalog
-- 仅提供版本标识，部署演示不读取或修改任何业务键。
local function release_label(keys, args)
    -- 拒绝多余参数，避免调用方把它误当成数据处理函数。
    if #keys ~= 0 or #args ~= 0 then
        return redis.error_reply('catalog_release expects no inputs')
    end
    return 'release-a'
end

-- 客户端使用注册名调用，Lua 局部函数名不作为外部入口。
redis.register_function('catalog_release', release_label)

文件既是首次安装的输入，也应作为可追溯的部署产物保存。不要只在命令行历史里留一份源码；回滚时还需要旧文件。真正访问数据的函数必须把所用键名显式作为 key 参数传入，不能把任意键名藏在普通参数中。

加载函数库并按函数名调用

以下命令使用本机独立演示服务，实际部署应替换连接配置。redis-cli 的 -x 将标准输入作为命令的最后一个参数，所以重定向的是整个 Lua 文件，不需要把多行代码拼进字符串。

# 首次加载：整个文件作为 function-code 参数发送给演示服务。
redis-cli -h 127.0.0.1 -p 6379 -x FUNCTION LOAD 

首次加载成功时，命令返回库名 deploy_catalog。按上述源码调用时，函数应返回 release-a；这是示例的预期行为，不是本机执行记录。FUNCTION LIST 的列表结构与客户端显示形式有关，重点看库名及其注册的函数名称。

区分库名、函数名和更新范围

FUNCTION LOAD REPLACE 的替换单位是同名的整个函数库。它不会给函数名自动加上库名前缀，也不是只修改某一个注册函数。若新版文件漏掉旧函数，依赖旧入口的客户端可能失去可调用入口，因此发布文件应包含该库打算保留的完整函数集合。

例如把文件中的标识改为 release-b，并保留注册名与参数约定，再执行下面的更新命令。REPLACE 允许同名库替换，但不能抢占另一个库已经注册的同名函数。

# 更新前由部署系统保留上一版完整文件；这里加载已准备好的新版。
redis-cli -h 127.0.0.1 -p 6379 -x FUNCTION LOAD REPLACE 

安排主节点分发与故障处理

一个节点的加载成功回执，只说明该节点接受了函数库。Redis 会把函数库传播给副本；Redis Cluster 中不同主节点的部署仍需要管理员安排，不能把连接任意一个主节点并加载一次当成全体分片完成。建议由部署系统维护目标主节点清单，逐个发送同一份发布文件并记录各节点回执。

对集群的更新不是跨主节点的一次全局原子切换。如果发布过程中部分节点失败，应暂停依赖新行为的客户端切换，按记录修复缺失节点或让已更新节点回到旧版。只有当新旧接口兼容时，逐节点过渡才容易控制。需要新增不兼容入口时，可采用独立注册名保留旧接口，完成客户端迁移后再清理。

加载报错时先读服务端错误：同名库已经存在且未带 REPLACE，应明确是首次安装冲突还是预期更新；其他库已有同名函数，应调整完整命名方案；引擎声明、Lua 编译或函数注册失败，应修复同一份源码。不要通过先清空所有函数库来掩盖单个库的安装问题。

保留回滚文件并定向清理

发布仓库应保存库名、源码版本、函数入口集合、目标节点与部署结果。回滚是把旧版完整源码重新加载到相同目标节点，它不会自动撤销函数以前对业务数据产生的修改。本例没有数据写入，业务函数则必须另行考虑数据兼容性。

# 恢复预先归档的旧版源码；不要把空文件当回滚文件。
redis-cli -h 127.0.0.1 -p 6379 -x FUNCTION LOAD REPLACE 

库删除后，其中注册的函数不再可供调用。集群部署和清理要覆盖相应主节点，不要留下部分分片还有入口、部分分片已经删除的混合状态。避免在共享环境使用 FUNCTION FLUSH 作为本例清理动作。

常见问题

为什么 FCALL deploy_catalog 找不到函数？

deploy_catalog 是库名；本例注册的调用名是 catalog_release。管理对象和业务入口是两个名称。

切换 Redis 数据库编号能隔离同名函数吗？

不能把库当成某个逻辑数据库内的普通数据键。应在服务范围内规划函数命名，独立环境需要独立实例或相应的部署隔离。

重新连接客户端是否需要再次加载？

函数库由服务端管理，客户端重新连接不应触发无条件重复安装。持久化恢复、复制和新节点接入属于服务部署职责，发布系统应明确管理它们。

最小部署闭环是：保存完整源码，用库名管理装载和替换，用注册函数名调用，再把同一版本覆盖到需要的主节点。更新和回滚都围绕完整库文件安排。

参考：FUNCTION LOAD 命令、Redis Functions 官方说明。