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 錯誤。