lua-resty-redis-cluster-fast

# 版本兼容性

本文同时保留旧实现的安装和使用说明，并补充 lua-resty-redis-cluster-fast-1.31.8 新版 1.0.2 的说明。这里的“新版”指使用独立动态模块的实现；其他 Nginx 系列的旧实现即使软件包版本号相同，也应使用旧版说明。

新版不支持更老的 Nginx。使用旧版 OpenResty 时，请继续使用对应的旧版私有库；不要安装新版 1.0.2。升级到新版时，需要同时升级 OpenResty 并更新 Nginx 配置。

# 与开源库的性能比较

在一个典型的 Redis Cluster 并发读取应用场景中，lua-resty-redis-cluster-fast 的吞吐量达到开源 lua-resty-redis-cluster（2026-11-05 最新版）的 7.14 倍，提升 613.8%。

性能比较采用相同 Lua 并发的共享连接模式，物理连接数不同。实际提升取决于业务负载、连接配置和部署环境。

# 前提条件

• 安装软件包要求用户具有 root 权限

• 机器必须能够访问以下的域名以下载软件包和 GPG 秘钥：

  • https://openresty.org
  • https://pkg2.openresty.com

  你可以通过执行以下命令验证域名可访问性：

  curl https://openresty.org/package/pubkey.gpg
  curl https://pkg2.openresty.com/xray-priv-libs/
  

# 配置软件包仓库

将 CLIENT_TOKEN 替换为订阅邮件中的有效 Token。先下载仓库配置脚本，再按照所用实现选择以下步骤。这些命令只配置仓库，不会安装私有库软件包。

curl -o get-xray-priv-lib-repo.sh https://pkg2.openresty.com.cn/scripts/get-xray-priv-lib-repo.sh

新旧实现都需要配置 OpenResty 开源软件仓库，以便安装 OpenResty 及其依赖。

# OpenResty 1.31.8.x 新版实现的仓库

新版继续使用现有的 coro-hiredis-nginx-module 仓库，该仓库提供 lua-resty-redis-cluster-fast-1.31.8 软件包。配置这个仓库不会安装 coro-hiredis-nginx-module 软件包。

sudo bash get-xray-priv-lib-repo.sh -l coro-hiredis-nginx-module -t CLIENT_TOKEN

新版不需要安装 coro-nginx-module 或 coro-hiredis-nginx-module 软件包，也不需要加载它们的 Nginx 动态模块。

# 旧版实现的仓库

使用匹配的旧版软件包时，需要配置以下两个私有仓库：

sudo bash get-xray-priv-lib-repo.sh -l coro-nginx-module -t CLIENT_TOKEN

sudo bash get-xray-priv-lib-repo.sh -l coro-hiredis-nginx-module -t CLIENT_TOKEN

# 安装

# 针对 OpenResty-1.21.4.x

使用 yum 的系统，执行以下命令安装私有库：

sudo yum install --disablerepo="*" --enablerepo="coro-nginx-module,coro-hiredis-nginx-module" -y lua-resty-redis-cluster-fast-1.21.4

使用 dnf 的系统，执行以下命令安装私有库：

sudo dnf install --disablerepo="*" --enablerepo="coro-nginx-module,coro-hiredis-nginx-module" -y lua-resty-redis-cluster-fast-1.21.4

使用 apt 的系统，执行以下命令安装私有库：

sudo apt-get install -y lua-resty-redis-cluster-fast-1.21.4

# 针对 OpenResty 1.25.3.x

使用 yum 的系统，执行以下命令安装私有库：

sudo yum install --disablerepo="*" --enablerepo="coro-nginx-module,coro-hiredis-nginx-module"  -y lua-resty-redis-cluster-fast-1.25.3

使用 dnf 的系统，执行以下命令安装私有库：

sudo dnf install --disablerepo="*" --enablerepo="coro-nginx-module,coro-hiredis-nginx-module" -y lua-resty-redis-cluster-fast-1.25.3

使用 apt 的系统，执行以下命令安装私有库：

sudo apt-get install -y lua-resty-redis-cluster-fast-1.25.3

# 针对 OpenResty 1.27.1.x

使用 yum 的系统，执行以下命令安装私有库：

sudo yum install --disablerepo="*" --enablerepo="coro-nginx-module,coro-hiredis-nginx-module" -y lua-resty-redis-cluster-fast-1.27.1

使用 dnf 的系统，执行以下命令安装私有库：

sudo dnf install --disablerepo="*" --enablerepo="coro-nginx-module,coro-hiredis-nginx-module" -y lua-resty-redis-cluster-fast-1.27.1

使用 apt 的系统，执行以下命令安装私有库：

sudo apt-get install -y lua-resty-redis-cluster-fast-1.27.1

# 针对 OpenResty 1.31.8.x

新版软件包名为 lua-resty-redis-cluster-fast-1.31.8，提供 RPM 和 DEB 软件包，使用和配置方式一致。新版要求 OpenResty 1.31.8.1 或更新的同系列版本。安装前应先配置 OpenResty 开源软件仓库，以便包管理器解析所需依赖。新版不依赖旧实现使用的 coro 动态模块软件包。

以下命令安装软件仓库中可用的版本。升级到新版 1.0.2 后，请使用“新版使用”中的配置；此前的旧实现仍使用“旧版使用”中的配置。

使用 yum 的系统，执行以下命令安装私有库：

sudo yum install -y lua-resty-redis-cluster-fast-1.31.8

使用 dnf 的系统，执行以下命令安装私有库：

sudo dnf install -y lua-resty-redis-cluster-fast-1.31.8

使用 apt 的系统，执行以下命令安装私有库：

sudo apt-get install -y lua-resty-redis-cluster-fast-1.31.8

# 安装 OpenResty

新版应选择包含 Nginx 1.31.8 的 OpenResty 1.31.8.x 软件包，最低版本为 1.31.8.1。使用旧版私有库时，应选择与该库匹配的 OpenResty 系列。安装或升级前，先查询软件仓库中的完整版本号，再安装匹配的版本，避免动态模块与 OpenResty 不兼容。

根据使用的包管理器查询可用版本：

将 VERSION 替换为查询结果中与所选私有库匹配的完整版本号。

# 使用

请根据所安装软件包的实现选择以下配置。

# 新版使用

本节适用于新版 1.0.2 和 Nginx 1.31.8。旧实现的配置和示例保留在“旧版使用”一节。

# 新版 Nginx 配置

在 nginx.conf 的 main 上下文中加载软件包提供的动态模块：

load_module /usr/local/openresty/nginx/modules/ngx_redis_cluster_module.so;

新版使用此模块替代旧实现所需的两个 coro 模块，无需为本库配置 coro_preload 或 coro_stack_size。如果其他私有库仍使用这些模块或指令，请保留它们所需的配置。

软件包将 Lua 字节码模块安装到 /usr/local/openresty/site/lualib。使用标准 OpenResty 软件包的默认搜索路径即可加载；自定义 lua_package_path 时，需要保留默认路径（;;）或包含 /usr/local/openresty/site/lualib/?.ljbc。Nginx worker 的运行用户需要具有读取这些文件以及所需 TLS 证书和私钥文件的权限。

# 新版 Lua 示例

新版唯一支持的入口是 require "resty.redis.cluster.fast"。升级时，请将此前使用的 require "resty.redis.cluster" 改为该入口。以下是一个完整的 nginx.conf 示例：

load_module /usr/local/openresty/nginx/modules/ngx_redis_cluster_module.so;

worker_processes auto;
error_log logs/error.log;
events {
    worker_connections 1024;
}

http {
    server {
        listen 8080;

        location /test {
            content_by_lua_block {
                local redis = require "resty.redis.cluster.fast"
                local red = redis:new()
                red:set_timeouts(1000, 1000, 1000)

                local ok, err = red:connect("127.0.0.1", 6379, {
                    cluster = "cluster",
                    other_nodes = {
                        { "127.0.0.1", 6380 },
                        { "127.0.0.1", 6381 },
                        { "127.0.0.1", 6382 },
                    },
                    pool_size = 8,
                    connection_count = 3,
                    no_slaves = true,
                })
                if not ok then
                    ngx.say("failed to connect: ", err)
                    return
                end

                ok, err = red:set("dog", "an animal")
                if err ~= nil then
                    red:close()
                    ngx.say("failed to set dog: ", err)
                    return
                end

                local res, err = red:get("dog")
                if err ~= nil then
                    red:close()
                    ngx.say("failed to get dog: ", err)
                    return
                end

                ngx.say("dog: ", res == ngx.null and "not found" or res)

                ok, err = red:set_keepalive()
                if not ok then
                    red:close()
                    ngx.say("failed to set keepalive: ", err)
                end
            }
        }
    }
}

# 新版连接参数和行为

connect(host, port, options_table) 的 cluster 仍为必填字符串，other_nodes 仍使用 {host, port} 数组作为备用入口节点。新版支持 TCP 和 TLS，不支持 Unix domain socket。如果入口节点或集群返回的节点地址使用域名，需要配置可解析这些域名的 Nginx resolver。

TLS 与 ACL 认证示例（路径、主机名和 password 变量应替换为实际配置）：

local ok, err = red:connect("redis.example.com", 8000, {
    cluster = "orders-tls",
    username = "orders-app",
    password = password,
    ssl = true,
    ssl_ca_cert = "/etc/redis/ca.crt",
    ssl_server_name = "redis.example.com",
    ssl_verify_name = "redis.example.com",
    no_slaves = true,
})

为兼容早期接口，新版还接受 serv_list = {{ip = host, port = port}, ...} 形式的备用入口节点；未设置 no_slaves 时，可以使用别名 no_slave = true 或 no_slave = 1。

# 认证与返回值

认证和 TLS 设置适用于入口节点、发现的主节点和副本、重定向目标以及订阅连接。连接初始化和拓扑发现需要允许 PING 和 CLUSTER SLOTS 命令；RESP3 需要 HELLO，副本读取需要 READONLY。在 connect() 中配置的凭据不正确时，连接会失败。

也可以在不带凭据的连接上调用 red:auth(password) 或 red:auth(username, password)。成功时返回 "OK"，为当前客户端隔离会话，并将凭据用于之后的节点连接。Redis 认证错误返回 nil, err，保留之前的凭据；连接或初始化失败也返回 nil, err。未认证时，受保护的命令返回 Redis 的 NOAUTH 错误。密码可以是空字符串或包含二进制数据；使用相同密码的不同用户仍有各自的连接和权限。

普通命令的状态回复返回字符串，整数回复返回数字，Redis 空值返回 ngx.null。Redis 错误、连接或传输失败均返回 nil, err；数组、流水线或 EXEC 回复中的 Redis 错误仍表示为 {false, err}。RESP3 的布尔值 false 在没有错误字符串时是有效结果。升级之前使用 false, err 的实现时，应将 res == false 一类错误判断改为检查 err ~= nil，并单独处理 ngx.null。

# 连接生命周期与超时

普通命令可在同一个 Nginx worker 内共享物理连接。connection_count 默认 3，连续命令会轮询选择连接，包括同一个 Lua 客户端发出的连续命令；每个流水线批次为每个目标节点选择一条连接，并推进一次轮询。连接按需建立，失效或过期的共享连接在下次轮到时替换；设置为 1 可使用单连接复用。pool_size 小于 connection_count 时，空闲连接可能在下一轮使用前被回收。

连接池按节点、集群名称、认证、协议、TLS、connection_count、max_pending 和订阅缓冲区上限等设置隔离；超时、入口节点和路由策略不单独创建物理连接池。连接总数还受 worker 数、目标节点数及独占会话数影响。不要在并发操作间共享同一个 Lua 客户端对象。

达到 max_pending 上限时，调用会在读取超时范围内等待，超时后返回 nil, "pending queue full"；读取超时为 0 时，等待没有时间上限。此限制与空闲连接数和并发 Lua 客户端数不同。

set_keepalive() 释放当前客户端对所有已访问节点连接的引用，成功返回 1 并关闭 Lua 对象；兼容传入的两个参数会被忽略。close() 同样释放引用，成功返回 1，仅在没有其他客户端使用物理连接时关闭它。释放后，连接操作（包括 get_reused_times()）返回 nil, "closed"。成功的 connect() 可以重新打开对象，重新连接失败则保持关闭状态。处于订阅、MONITOR、WATCH 或事务状态的客户端不能调用 set_keepalive() 归还连接。

set_timeouts(connect_ms, send_ms, read_ms) 分别控制 TCP/TLS 建连、发送命令和等待回复的超时，默认均为 60000 毫秒。set_timeout(ms) 同时设置三个阈值，0 禁用对应超时。这些是独立的无活动超时：建连或发送耗时不占用下一阶段的预算，相关 I/O 进展会重置对应计时。在共享连接上，仅当前请求自身数据的发送进展会重置其发送超时；前一个请求的发送进展不会延长它的等待。拓扑发现还会在入口节点连接的总预算内使用发送和读取超时。

超时值必须是 0 至 2147483647 的整数毫秒数。非法数值返回 nil, "invalid timeout"，或由 set_timeouts() 指出非法阶段，例如 "invalid read_timeout"，原有超时设置保持不变。成功设置超时不返回值，不应以返回值是否为真来判断成功。

阻塞命令、事务、WATCH、订阅以及修改连接状态的命令使用独占连接。CLIENT SETNAME、HELLO 等连接设置会保留，供同一节点上的后续命令和流水线使用；释放客户端时会丢弃修改过的连接，避免后续使用者继承会话状态。

WAIT 和 WAITAOF 沿用前一条命令的物理连接，因为确认针对的是该连接上发送的写入。它们不会重新连接或切换到空闲连接来获取确认，也不覆盖其他轮询连接或整个集群的写入。共享连接时，它们还可能等待其他客户端此前的写入；等待中的 WAIT 可能延迟共享该连接的其他命令。

# 流水线与事务

新版支持 init_pipeline()、commit_pipeline() 和 cancel_pipeline()，回复顺序与命令顺序一致，但不保证不同节点间的执行顺序或整个流水线的原子性。MGET、MSET、DEL、EXISTS、UNLINK 和 TOUCH 可以拆分处理跨 slot 的键，可能部分成功；同一 slot 的键则作为单条 Redis 命令发送，保留其原子性和写入前的完整参数验证。包含写命令的流水线使用主节点。

AUTH、HELLO（包括不带 AUTH 的 HELLO）、RESET、WAIT 和 WAITAOF 在流水线中形成有序边界：前面的请求完成后才执行这些命令，后续请求使用执行后的会话状态。成功的 HELLO 协议变更（包括在 EXEC 中执行）也用于之后的节点连接；失败的 HELLO、取消流水线或事务中止、丢弃不会改变之前的协议设置。

事务与 WATCH 使用独占连接，事务中的键必须属于同一个 hash slot；可使用相同的 hash tag，例如 order:{42}:state 和 order:{42}:version。不能在普通流水线中启动事务或放入订阅命令。

multi() 立即发送 MULTI，之后的命令返回 Redis 的排队确认或即时命令错误。首个带键命令确定执行节点；此前无键命令的未执行队列会在需要时转移到该节点，并保留排队时的错误。WATCH 连接保持在已选节点，UNWATCH、EXEC 和 DISCARD 完成后允许连接复用。事务中的 AUTH 只有在 EXEC 成功执行该命令后才更新凭据；DISCARD 或事务中止会保留之前的凭据。

首次 WATCH 在独占的主节点连接上跟随 MOVED 和 ASK 重定向，成功后，后续 WATCH 保持在该连接。取消尚未收到确认的 WATCH 时，该连接不会再被复用。大写、混合大小写、add_commands() 或 send_req() 调用同样遵守事务和订阅限制。

# 订阅、MONITOR 与 RESET

订阅使用独立连接，读取超时会保留订阅状态。Redis 会确认每个取消订阅参数，包括未知或重复名称；确认与消息保持接收顺序，在最后一个已知订阅消失后仍可通过 read_reply() 读取，读取超时不会丢弃尚未到达的确认。

订阅期间执行普通命令或普通命令流水线时，继续使用当前订阅连接，并遵守 Redis 对相应协议的命令限制。普通命令获取自己的回复，订阅消息仍通过 read_reply() 读取。取消普通命令或读取超时只会丢弃该命令的迟到回复，不会结束订阅，也不会将迟到回复交给后续命令。MONITOR 状态会拒绝普通流水线，并保留监控连接。

如果排队回复超过配置上限，连接会关闭，队列会清空，read_reply() 持续返回 nil, "pub/sub buffer limit exceeded"，直到重新连接。应用需要重新连接并订阅。字节数包括回复容器、字符串和队列条目，不包括内存分配器开销或当前正在解析的回复；读取回复会释放对应预算。

新版支持 Redis 7 分片 Pub/Sub 的 ssubscribe、sunsubscribe 和 spublish，其中 ssubscribe 和 spublish 按频道的 hash slot 路由。分片频道与同名的普通频道或模式相互独立。已订阅的客户端保持在当前服务器；订阅不同节点的频道时应使用不同 Lua 客户端。订阅命令的 MOVED、CROSSSLOT 等 Redis 错误会保留现有消息流，首次订阅可以跟随重定向。

monitor() 在独占连接上启动命令流，read_reply() 返回观察到的命令字符串，读取超时保留消息流。使用 reset() 或 close() 停止监控。MONITOR 连接不能执行其他命令或归还空闲池，MONITOR 也不能放入流水线或事务。

成功的 RESET 结束订阅、MONITOR 和 WATCH，清除客户端保存的认证信息并恢复 RESP2。受密码保护的服务需要重新调用 auth()；要同时认证并启用 RESP3，可调用 hello(3, "AUTH", username, password)。失败的 RESET 或 HELLO 会保留现有消息流。RESP2 的订阅命令限制仍然适用，RESP3 允许在订阅期间执行 AUTH；认证和协议控制命令获取自己的回复，待处理订阅消息仍可通过 read_reply() 读取。

# 故障恢复与重试

连接故障后，普通操作会通过仍可用的入口节点或已知节点尝试刷新路由。同一 worker 共享刷新操作，每次最多尝试三个节点，并轮换候选节点。刷新预算由配置的连接超时确定，上限为 3000 毫秒；连接超时为 0 时仍使用 3000 毫秒。候选节点的连接、发送和读取超时从剩余预算中分配，持续 I/O 可能延长总耗时。一次刷新完成后，至少间隔 100 毫秒才会再次尝试。

刷新发现不同节点时，读取操作或已确认未发送的命令可以重试一次。可能已发送的写操作或部分执行的写流水线不会自动重放，刷新后的路由用于后续操作；应用应处理返回错误，避免无条件重试造成重复写入。事务、订阅和其他修改连接状态的操作不会以这种方式迁移。

完整 API 说明见英文手册。

# 旧版使用

以下保留旧实现的配置和接口说明，适用于匹配的旧版软件包。新版 1.0.2 请使用上面的“新版使用”一节。

# Nginx 配置

在使用前需要在配置文件 nginx.conf 中需要添加以下这些配置项，用以加载 lua-resty-redis-cluster-fast 相关的动态模块。

    ...

    load_module "/usr/local/openresty-coro-nginx-module/lib/ngx_http_coro_module.so";
    load_module "/usr/local/openresty-coro-nginx-module/lib/ngx_http_coro_hiredis_module.so";

    http {
        coro_preload /usr/local/openresty-plus/hiredis/lib/libhiredis.so;

        coro_stack_size  32768;
        ...
    }

# Lua 接口

除了 connect 和 set_keepalive 接口发生了变化，该库的其他接口和开源的 lua-resty-redis 保持一致，以下是一个简单的例子：

    load_module "/usr/local/openresty-coro-nginx-module/lib/ngx_http_coro_module.so";
    load_module "/usr/local/openresty-coro-nginx-module/lib/ngx_http_coro_hiredis_module.so";

    http {
        coro_preload /usr/local/openresty-plus/hiredis/lib/libhiredis.so;
        coro_stack_size  32768;

        server {
            location /test {
                # need to specify the resolver to resolve the hostname
                resolver 8.8.8.8;

                content_by_lua_block {
                    local redis = require "resty.redis.cluster.fast"
                    local red = redis:new()

                    red:set_timeouts(1000, 1000, 1000) -- 1 sec

                    -- connect via ip address directly
                    local ok, err = red:connect("127.0.0.1", 6379, {
                        cluster = "cluster",
                        other_nodes = {
                            { "127.0.0.1", 6380 },
                            { "127.0.0.1", 6381 },
                            { "127.0.0.1", 6382 },
                        },
                        no_slaves = true
                    })

                    if not ok then
                        ngx.say("failed to connect: ", err)
                        return
                    end

                    ok, err = red:set("dog", "an animal")
                    if not ok then
                        ngx.say("failed to set dog: ", err)
                        return
                    end

                    ngx.say("set result: ", ok)

                    local res, err = red:get("dog")
                    if not res then
                        ngx.say("failed to get dog: ", err)
                        return
                    end

                    if res == ngx.null then
                        ngx.say("dog not found.")
                        return
                    end

                    ngx.say("dog: ", res)

                    local ok, err = red:set_keepalive()
                    if not ok then
                        ngx.say("failed to set keepalive: ", err)
                        return
                    end
                }
            }
        }
    }

connect 和 set_keepalive 接口的说明如下：

# connect

TODO：目前不支持 unix domain socket 和 SSL.

syntax: ok, err = red:connect(host, port, options_table)

连接到 Redis 入口节点所监听的主机和端口。在实际连接到远程后端之前，该方法将始终查找连接池中由该方法的先前调用创建的匹配的空闲连接。

options_table 参数是一个 Lua table，包括这些参数：

• cluster

  为正在使用的 Redis 集群连接池指定一个自定义名称，这是一个必填字段。

• pool_size

  指定连接池的大小，默认是 128。

• other_nodes

  指定可以连接的其他 Redis 节点，当与入口节点的连接失败时，它将尝试连接到其他节点。

  other_nodes 参数是一个 Lua 表，用于保存多个节点的配置信息，例如：

  {
      { "127.0.0.1", 6379 },
      { "127.0.0.1", 6380 },
      { "127.0.0.1", 6381 },
  }
  

• no_slaves

  是否禁止从 Redis slave 节点读取数据，默认为 false。

# set_keepalive

syntax: ok, err = red:set_keepalive()

为了兼容开源的 lua-resty-redis 库的 set_keepalive(max_idle_timeout, pool_size) 方法，我们仍然允许传入两个参数，但我们会忽略传入的参数。

将当前 Redis 连接放入到 cosocket 连接池中。

只在你要调用 close 方法的地方调用此方法。调用此方法将立即把当前的 Redis 对象变成 closed 状态。除 connect() 外，对当前对象的任何后续操作都将返回 closed 错误。