Redis Sentinel 配置文件和配置项注解手册大全¶

文档概览¶

• Latest Redis version: 8.2.x
• sentinel.conf: https://github.com/redis/redis/blob/8.2.1/sentinel.conf

GENERAL¶

protected-mode¶

@引入版本: 4.0.x

@配置语法

# @Since: 4.0.x
# bind 127.0.0.1 192.168.1.1
# protected-mode no

# @Since: 7.0.x
protected-mode no

@官方参考

默认情况下，哨兵（sentinel）模式中保护模式是禁用的。哨兵可以从本地回环地址以外的其他接口访问。请确保通过防火墙或其他方式将哨兵实例与外部网络隔离。

例如，你可以使用以下方法之一：

protected-mode no

sentinel port¶

此哨兵实例将运行的端口号。

@引入版本: 2.6.x

@配置语法

# port <sentinel-port>

# Default:
port 26379

sentinel daemonize¶

@引入版本: 5.0.x

@配置语法

daemonize no

@官方参考

默认情况下，Redis 哨兵不会以守护进程方式运行。如果需要，请设置为 'yes'。

请注意，当以守护进程方式运行时，Redis 会将进程 ID 写入 /var/run/redis-sentinel.pid 文件中。

sentinel pidfile¶

@引入版本: 5.0.x

@配置语法

pidfile /var/run/redis-sentinel.pid

@官方参考

当以守护进程方式运行时，Redis 哨兵默认会将进程 ID 文件写入 /var/run/redis-sentinel.pid。你可以在此处指定一个自定义的 pid 文件路径。

sentinel loglevel¶

指定服务器的日志详细级别。

@引入版本: 7.2.x

@配置语法

loglevel notice

@可选项

debug：大量信息，适用于开发/测试。 verbose：很多信息，但很少有用，不过不像 debug 级别那么冗杂。 notice：默认，适度详细，生产环境可能需要的级别。 warning：仅记录非常重要或关键的消息。 nothing：不记录任何日志

sentinel logfile¶

@引入版本: 5.0.x

@配置语法

logfile ""

@官方参考

指定日志文件名。也可以使用空字符串，强制 Sentinel 将日志输出到标准输出。注意，如果使用标准输出记录日志但同时启用了守护进程模式（daemonize），日志将被重定向到 /dev/null。

sentinel syslog-enabled¶

@引入版本: 7.2.x

@配置语法

# syslog-enabled no

@官方参考

要启用将日志记录到系统日志（syslog），只需将 syslog-enabled 设置为 yes，并可根据需要选择性地调整其他 syslog 参数。

syslog-ident¶

指定用于 syslog 的标识符（identity）。

@引入版本: 7.2.x

@配置语法

# syslog-ident sentinel

syslog-facility¶

指定 syslog 设施（facility）。必须为 USER 或 LOCAL0 至 LOCAL7 之间的值。

@引入版本: 7.2.x

@配置语法

# syslog-facility local0

sentinel announce-ip¶

@引入版本: 3.0.x

@配置语法

sentinel announce-ip `<ip>`
sentinel announce-port `<port>`

@官方参考

上述两个配置指令在如下环境中非常有用：由于 NAT 的存在，哨兵（Sentinel）可以通过非本地地址从外部网络访问。

当提供了 announce-ip 时，哨兵在用于传播自身存在的 HELLO 消息中，将声明指定的 IP 地址，而不是像通常那样自动检测本地地址。

同样，当提供了有效且非零的 announce-port 时，哨兵将宣布指定的 TCP 端口。

这两个选项不必同时使用。如果仅提供了 announce-ip，哨兵将宣布指定的 IP 地址，并使用 "port" 选项中指定的服务器端口。如果仅提供了 announce-port，哨兵将宣布自动检测到的本地 IP 地址和指定的端口。

示例：

# sentinel announce-ip 1.2.3.4

sentinel dir¶

@引入版本: 3.0.x

@配置语法

# dir <working-directory>
dir /tmp

@官方参考

每个长期运行的进程都应具有明确定义的工作目录。Redis 哨兵（Sentinel）在启动时切换到 /tmp 目录，是避免进程干扰诸如卸载文件系统等管理任务的最简单做法。

sentinel monitor¶

@引入版本: 2.6.x

@配置语法

# sentinel monitor <master-name> <ip> <redis-port> <quorum>
sentinel monitor mymaster 127.0.0.1 6379 2

@官方参考

告诉哨兵（Sentinel）监控该主节点，并且只有当至少 <quorum> 个哨兵节点同意时，才将其判定为 O_DOWN（客观下线）状态。

请注意，无论 ODOWN 的法定数量（quorum）如何设定，哨兵在发起故障转移（failover）前，必须获得大多数已知哨兵节点的选举支持，因此在少数派情况下无法执行故障转移。

从节点（replicas）会自动被发现，因此你无需以任何方式手动指定从节点。哨兵自身会重写此配置文件，通过添加额外的配置项来加入从节点。另外，当某个从节点被提升为新的主节点时，配置文件也会被自动重写。

Note: 主节点名称不应包含特殊字符或空格。有效字符集为 A-z、0-9 以及三个字符 ".-_"。

sentinel auth-pass¶

@引入版本: 2.6.x

@配置语法

# sentinel auth-pass <master-name> <password>

# sentinel auth-pass mymaster MySUPER--secret-0123passw0rd

@官方参考

设置用于与主节点和从节点进行身份验证的密码。当你所监控的 Redis 实例设置了密码时，此配置非常有用。

请注意，主节点密码同样会被用于从节点。因此，如果你想使用哨兵来监控这些实例，就无法为主节点和从节点设置不同的密码。

不过，你可以将未启用身份验证的 Redis 实例与需要身份验证的实例混合使用（前提是所有需要密码的实例使用相同的密码），因为在未开启身份验证的 Redis 实例中，AUTH 命令不会产生任何效果。

示例：

# sentinel auth-pass <master-name> <password>
# sentinel auth-pass mymaster MySUPER--secret-0123passw0rd

sentinel auth-user¶

@引入版本: 6.0.x

@配置语法

sentinel auth-user `<master-name>` `<username>`

@官方参考

这在需要向具备 ACL（访问控制列表）功能的实例进行身份验证时非常有用，即运行 Redis 6.0 或更高版本的情况。当仅提供 auth-pass 时，哨兵实例将使用旧的 AUTH <pass> 方式进行身份验证；当同时提供了用户名时，则会使用 AUTH <user> <pass> 方式进行认证。

在 Redis 服务端，为哨兵实例提供最低限度访问权限的 ACL 应按以下方式配置：

#     user sentinel-user >somepassword +client +subscribe +publish \
#                        +ping +info +multi +slaveof +config +client +exec on

sentinel down-after-milliseconds¶

@引入版本: 2.6.x

@配置语法

# sentinel down-after-milliseconds <master-name> <milliseconds>
sentinel down-after-milliseconds mymaster 30000

@官方参考

主节点（或任何连接的从节点或哨兵）需要不可达（即连续无法对 PING 命令做出可接受的回复）多少毫秒，才会被判定为 S_DOWN 状态（主观下线）。

默认值为 30 秒。

sentinel acl¶

@引入版本: 6.2.x

@配置语法

#   user <username> ... acl rules ...

@官方参考

从 Redis 6.2 开始，哨兵（Sentinel）模式支持 ACL 功能，更多详细信息请参考 Redis 官方网站：https://redis.io/topics/acl。

哨兵的 ACL 用户按以下格式定义：

#   user <username> ... acl rules ...

例如：

#   user worker +@admin +@connection ~* on >ffa9203c493aa99

有关 ACL 配置的更多信息，请参考 Redis 官方网站 https://redis.io/topics/acl 以及 Redis 服务器配置模板 redis.conf。

sentinel acllog-max-len¶

@引入版本: 6.2.x

@配置语法

acllog-max-len 128

@官方参考

ACL 日志用于记录与 ACL 相关的命令执行失败和认证事件。ACL 日志有助于排查因 ACL 限制而导致的命令失败问题。ACL 日志存储在内存中，可通过 ACL LOG RESET 命令释放所占用的内存。请在下方定义 ACL 日志中每条日志的最大长度。

acllog-max-len 128

sentinel aclfile¶

@引入版本: 6.2.x

@配置语法

# aclfile /etc/redis/sentinel-users.acl

@官方参考

使用外部 ACL 文件。

除了在本文件中配置用户外，还可以使用一个独立的文件来列出用户。这两种方法不能混合使用：如果在此处配置了用户的同时又启用了外部 ACL 文件，服务器将拒绝启动。

外部 ACL 用户文件的格式与 redis.conf 文件中描述用户的格式完全相同。

sentinel requirepass¶

@引入版本: 6.0.x

@配置语法

# requirepass <password>

@官方参考

你可以配置哨兵（Sentinel）本身要求密码验证。但需要注意的是，启用此功能后，哨兵会尝试使用相同的密码向组内所有其他哨兵进行身份验证。因此，你需要为同一组中的所有哨兵配置相同的 requirepass 密码。更多详细信息，请参考以下文档：https://redis.io/topics/sentinel

NOTE: 从 Redis 6.2 开始，requirepass 是构建在 ACL 系统之上的兼容层。该选项的作用仅仅是为默认用户设置密码。客户端仍可像以往一样使用 AUTH <password> 进行认证，或根据新协议更明确地使用 AUTH default <password> 进行认证：两种方式均有效。

sentinel-user¶

@引入版本: 6.2.x

@配置语法

# sentinel sentinel-user <username>

@官方参考

建议新配置文件使用独立的认证机制：对传入连接使用 ACL 进行认证控制，对传出连接使用 sentinel-user 和 sentinel-pass 进行认证控制。

requirepass 与 aclfile 选项及 ACL LOAD 命令不兼容，如果使用了后者，requirepass 将被忽略。

sentinel-pass¶

@引入版本: 6.2.x

@配置语法

# sentinel sentinel-pass <password>

@官方参考

你可以配置哨兵使用特定的用户名与其他哨兵进行身份验证。

这是哨兵与其他哨兵进行身份验证时使用的密码。如果未配置 sentinel-user，哨兵将使用默认用户 'default' 和 sentinel-pass 进行认证。

sentinel parallel-syncs¶

@引入版本: 2.6.x

@配置语法

# sentinel parallel-syncs <master-name> <numreplicas>

@官方参考

在故障转移期间，可以同时重新配置多少个从节点指向新的主节点。如果你使用从节点来处理查询，建议使用较低的数值，以避免在与主节点同步时，所有从节点几乎同时变得不可用。

sentinel parallel-syncs mymaster 1

sentinel failover-timeout¶

@引入版本: 2.6.x

@配置语法

# sentinel failover-timeout <master-name> <milliseconds>

@官方参考

指定故障转移超时时间（单位为毫秒）。该参数在多个方面被使用：

• 当某个哨兵对同一主节点进行过一次故障转移尝试后，再次尝试重新启动故障转移所需等待的时间，是故障转移超时时间的两倍。

• 当哨兵检测到某个从节点正在复制错误的主节点时，需要等待故障转移超时时间后，才会强制该从节点与正确的主节点进行同步。

• 用于取消一个已开始但尚未产生任何配置变更（例如，被提升的从节点尚未确认执行 SLAVEOF NO ONE）的故障转移流程。

• 故障转移过程中，等待所有从节点被重新配置为新主节点副本的最长时间。即使超过此时间，哨兵最终仍会重新配置这些从节点，但可能不再严格按照 parallel-syncs 所指定的并行进度进行。

默认值为 3 分钟。

sentinel failover-timeout mymaster 180000

SCRIPTS EXECUTION¶

sentinel notification-script 和 sentinel reconfig-script 用于配置脚本，这些脚本会在发生故障转移后被调用，以通知系统管理员或重新配置客户端。脚本执行时遵循以下错误处理规则：

• 如果脚本以退出码 "1" 结束，系统将在稍后重试执行（最多重试次数目前设定为 10 次）。
• 如果脚本以退出码 "2" 或更高的值结束，则不再重试执行。
• 如果脚本因接收到信号而终止，其行为与退出码为 1 的情况相同。
• 脚本的最长运行时间为 60 秒。超过此限制后，脚本将被 SIGKILL 信号强制终止，并进行重试执行。

NOTIFICATION SCRIPT¶

sentinel notification-script¶

@引入版本: 2.6.x

@配置语法

# sentinel notification-script <master-name> <script-path>

@官方参考

在生成 WARNING 级别（例如 -sdown、-odown 等）的任何哨兵事件时，调用指定的通知脚本。该脚本应通过电子邮件、短信或任何其他消息系统通知系统管理员，被监控的 Redis 系统出现了问题。

脚本将被传入两个参数调用：第一个是事件类型，第二个是事件描述。

如果提供了此选项，则该脚本必须存在且具有可执行权限，哨兵才能正常启动。

示例：

# sentinel notification-script mymaster /var/redis/notify.sh

CLIENTS RECONFIGURATION SCRIPT¶

sentinel client-reconfig-script¶

@引入版本: 2.6.x

@配置语法

# sentinel client-reconfig-script <master-name> <script-path>

@官方参考

当主节点由于故障转移而发生变化时，可以调用一个脚本来执行特定于应用程序的任务，以通知客户端配置已更改，主节点的地址已发生变化。

以下参数将被传递给该脚本：

# <master-name> <role> <state> <from-ip> <from-port> <to-ip> <to-port>
#
# <state> is currently always "failover"
# <role> is either "leader" or "observer"

参数 from-ip、from-port、to-ip、to-port 用于传递原主节点的地址和新选举出的从节点（现为主节点）的地址。

该脚本应具备抵御多次调用的能力（即具有幂等性）。

示例：

# sentinel client-reconfig-script mymaster /var/redis/reconfig.sh

SECURITY¶

sentinel deny-scripts-reconfig¶

@引入版本: 5.0.x

@配置语法

sentinel deny-scripts-reconfig yes

@官方参考

默认情况下，SENTINEL SET 命令将无法在运行时更改 notification-script 和 client-reconfig-script。这样可以避免一个简单的安全问题，即客户端可能将脚本设置为任意程序，并通过触发故障转移来执行该程序。

REDIS COMMANDS RENAMING¶

SENTINEL rename-command¶

@引入版本: 5.0.x

@DEPRECATED: 7.2.x

@配置语法

# SENTINEL rename-command mymaster CONFIG GUESSME

@官方参考

有时，Redis 服务器会将某些对哨兵（Sentinel）正常工作至关重要的命令重命名为难以猜测的字符串。这种情况在将 Redis 作为服务提供的场景中很常见，服务提供商不希望客户通过管理控制台以外的方式重新配置实例，例如 CONFIG 和 SLAVEOF 命令就经常被重命名。

在这种情况下，可以告知哨兵使用不同的命令名称来代替默认名称。例如，如果主节点 "mymaster" 及其关联的从节点都将 CONFIG 命令重命名为 GUESSME，则可以使用以下配置：

# SENTINEL rename-command mymaster CONFIG GUESSME

设置此配置后，每次哨兵需要使用 CONFIG 命令时，都会改用 GUESSME。请注意，命令名称的大小写并不需要严格匹配，因此在上述示例中写成 config guessme 是等效的。

也可以使用 SENTINEL SET 命令在运行时进行此项配置。

若要将某个命令恢复为其原始名称（即撤销重命名），只需将该命令重命名为其自身即可：

# SENTINEL rename-command mymaster CONFIG CONFIG

HOSTNAMES SUPPORT¶

SENTINEL resolve-hostname¶

@引入版本: 6.2.x

@配置语法

SENTINEL resolve-hostnames no

@官方参考

通常情况下，哨兵（Sentinel）仅使用 IP 地址，并要求在 SENTINEL MONITOR 命令中指定 IP 地址。同时，也要求 Redis 的 replica-announce-ip 配置项仅指定 IP 地址。

你可以通过启用 resolve-hostnames 来开启对主机名的支持。请注意，你必须确保 DNS 配置正确，并且 DNS 解析不会引入过长的延迟。

SENTINEL announce-hostnames¶

@引入版本: 6.2.x

@配置语法

SENTINEL announce-hostnames no

@官方参考

当启用 resolve-hostnames 时，哨兵在向用户、配置文件等暴露实例信息时，仍然会使用 IP 地址。如果你想在公告时保留主机名，请在下方启用 announce-hostnames。

SENTINEL announce-hostnames no

master-reboot-down-after-period¶

@引入版本: 7.0.x

@配置语法

SENTINEL master-reboot-down-after-period mymaster 0

@官方参考

当 master_reboot_down_after_period 设置为 0 时，哨兵在收到主节点返回的 -LOADING 响应时不会执行故障转移。这是 7.0 版本之前唯一支持的行为。否则，哨兵将使用此值作为时间（单位为毫秒），表示在主节点重启后，愿意接受 -LOADING 响应的时长，超过该时间后才会进行故障转移。