redis-connector: lua-resty-redis 的连接工具

安装

如果您尚未设置 RPM 仓库订阅，请 注册。然后您可以继续以下步骤。

CentOS/RHEL 7 或 Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-redis-connector

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-redis-connector

要在 NGINX 中使用此 Lua 库，请确保已安装 nginx-module-lua。

本文档描述了 lua-resty-redis-connector v0.11.0，发布于 2021 年 7 月 13 日。

---

这是用于 lua-resty-redis 的连接工具，方便且可靠地直接或通过 Redis Sentinel 连接到 Redis 主机。

概述

在本地主机上快速简单的认证连接到数据库 2：

local redis, err = require("resty.redis.connector").new({
    url = "redis://[email protected]:6379/2",
}):connect()

更详细的配置，包含超时和默认密码：

local rc = require("resty.redis.connector").new({
    connect_timeout = 50,
    send_timeout = 5000,
    read_timeout = 5000,
    keepalive_timeout = 30000,
    password = "mypass",
})

local redis, err = rc:connect({
    url = "redis://127.0.0.1:6379/2",
})

-- ...

local ok, err = rc:set_keepalive(redis)  -- 使用 keepalive 参数

将所有配置保存在一个表中，以便根据需要轻松创建/关闭连接：

local rc = require("resty.redis.connector").new({
    connect_timeout = 50,
    send_timeout = 5000,
    read_timeout = 5000,
    keepalive_timeout = 30000,

    host = "127.0.0.1",
    port = 6379,
    db = 2,
    password = "mypass",
})

local redis, err = rc:connect()

-- ...

local ok, err = rc:set_keepalive(redis)

connect 可用于覆盖在 new 中提供的一些默认值，这些值仅与此连接相关。

local rc = require("resty.redis.connector").new({
    host = "127.0.0.1",
    port = 6379,
    db = 2,
})

local redis, err = rc:connect({
    db = 5,
})

DSN 格式

如果存在 params.url 字段，则将解析该字段以设置其他参数。任何手动指定的参数将覆盖 DSN 中给出的值。

注意：这是自 v0.06 起的行为变化。之前，DSN 值会优先考虑。

直接连接 Redis

直接连接 Redis 的格式为：

redis://USERNAME:PASSWORD@HOST:PORT/DB

USERNAME、PASSWORD 和 DB 字段是可选的，其他所有组件都是必需的。

使用用户名需要 Redis 6.0.0 或更高版本。

通过 Redis Sentinel 连接

通过 Redis Sentinel 连接时，格式如下：

sentinel://USERNAME:PASSWORD@MASTER_NAME:ROLE/DB

同样，USERNAME、PASSWORD 和 DB 是可选的。ROLE 必须是 m 或 s，分别表示主/从。

在版本高于 5.0.1 的 Redis 中，Sentinel 可以选择要求其自己的密码。如果启用，请在 sentinel_password 参数中提供此密码。在 Redis 6.2.0 及更高版本中，您可以使用 sentinel_username 参数传递用户名。

还必须提供一个 sentinels 表。例如：

local redis, err = rc:connect{
    url = "sentinel://mymaster:a/2",
    sentinels = {
        { host = "127.0.0.1", port = 26379 },
    },
    sentinel_username = "default",
    sentinel_password = "password"
}

代理模式

如果通过代理服务（例如 Twemproxy）连接到 Redis，请启用 connection_is_proxied 参数。这些代理通常仅支持有限的 Redis 命令子集，即不需要状态且不影响多个键的命令。数据库和事务也不受支持。

代理模式将在连接时禁用切换到数据库。未支持的命令（默认为 Twemproxy 不支持的命令）将立即返回 nil, err，而不是发送到代理，这可能导致连接中断。

在将连接添加到 keepalive 池时，不会发送 discard。

禁用的命令

如果配置为命令表，则命令方法将被替换为一个立即返回 nil, err 的函数，而不将命令转发到服务器。

默认参数

{
    connect_timeout = 100,
    send_timeout = 1000,
    read_timeout = 1000,
    keepalive_timeout = 60000,
    keepalive_poolsize = 30,

    -- ssl, ssl_verify, server_name, pool, pool_size, backlog
    -- 参见: https://github.com/openresty/lua-resty-redis#connect
    connection_options = {},

    host = "127.0.0.1",
    port = "6379",
    path = "",  -- unix socket 路径，例如 /tmp/redis.sock
    username = "",
    password = "",
    sentinel_username = "",
    sentinel_password = "",
    db = 0,

    master_name = "mymaster",
    role = "master",  -- master | slave
    sentinels = {},

    connection_is_proxied = false,

    disabled_commands = {},
}

API

• new
• connect
• set_keepalive
• Utilities
  • connect_via_sentinel
  • try_hosts
  • connect_to_host
  • sentinel.get_master
  • sentinel.get_slaves

new

语法: rc = redis_connector.new(params)

创建 Redis Connector 对象，用给定的参数覆盖默认参数。如果失败，则返回 nil 和描述错误的字符串。

connect

语法: redis, err = rc:connect(params)

根据提供的 params 尝试创建连接，回退到 new 中给出的默认值或预定义的默认值。如果无法建立连接，则返回 nil 和描述原因的字符串。

请注意，此处给出的 params 不会更改连接器自身的配置，仅用于更改此特定连接操作。因此，以下参数在 connect 中给出时没有意义。

• keepalive_poolsize
• keepalive_timeout
• connection_is_proxied
• disabled_commands

set_keepalive

语法: ok, err = rc:set_keepalive(redis)

尝试根据在 new 中给出的超时和池大小参数，将给定的 Redis 连接放入 keepalive 池中。

这允许应用程序释放资源，而无需跟踪应用程序范围内的 keepalive 设置。

返回 1，如果出错，则返回 nil 和描述错误的字符串。

工具

以下方法通常不需要，但如果需要自定义接口可能会有用。

connect_via_sentinel

语法: redis, err = rc:connect_via_sentinel(params)

通过首先访问 params.sentinels 表中提供的 Sentinel，查询 params.master_name 和 params.role，返回 Redis 连接。

try_hosts

语法: redis, err = rc:try_hosts(hosts)

按顺序尝试提供的主机，并返回第一个成功的连接。

connect_to_host

语法: redis, err = rc:connect_to_host(host)

尝试连接到提供的 host。

sentinel.get_master

语法: master, err = sentinel.get_master(sentinel, master_name)

给定一个已连接的 Sentinel 实例和一个主名称，将返回当前的主 Redis 实例。

sentinel.get_slaves

语法: slaves, err = sentinel.get_slaves(sentinel, master_name)

给定一个已连接的 Sentinel 实例和一个主名称，将返回注册的从 Redis 实例列表。

GitHub

您可以在 nginx-module-redis-connector 的 GitHub 仓库 中找到有关此模块的其他配置提示和文档。