25 KiB
Redis Sentinel 高可用架构部署与运维手册
一、概述
1.1 核心功能
Redis Sentinel(哨兵)是 Redis 的高可用解决方案。其核心目标是实现主从切换的自动化,确保系统在主节点故障时能够自动选举新的主节点并恢复服务。
1.2 适用场景
- 生产环境下的 Redis 高可用需求。
- 需要自动故障转移(Failover)的分布式系统。
- 读写分离架构。
1.3 前置条件
- 运行环境:Docker & Docker Compose。
- 镜像版本:推荐使用 Redis 8.4.0 及以上版本。
- 网络规划:所有节点需网络互通,且需明确各宿主机的外部 IP。
二、环境准备
在所有节点(主节点、从节点、哨兵节点)上执行目录初始化及权限设置。
2.1 目录结构配置
# 创建配置、数据、日志目录
mkdir -p /data/redis/{conf,data,logs}
# 权限初始化(针对 Redis 容器默认用户 999)
chown -R 999:999 /data/redis
chmod -R 750 /data/redis
三、部署流程
3.1 Docker 服务编排
使用 Docker Compose 部署 Redis 服务及 Sentinel 节点。
docker-compose.yml 示例:
version: '3.8'
services:
# Redis 节点容器
redis:
image: redis:8.4.0
container_name: redis
restart: always
ports:
- "6379:6379"
volumes:
- /etc/localtime:/etc/localtime
- /etc/timezone:/etc/timezone
- /data/redis/conf/redis.conf:/etc/redis/redis.conf
- /data/redis/data:/data
- /data/redis/logs:/var/log/redis
command: redis-server /etc/redis/redis.conf
networks:
- redis-net
# Sentinel 节点容器
redis-sentinel:
image: redis:8.4.0
container_name: redis-sentinel
restart: always
ports:
- "26379:26379"
volumes:
- /etc/localtime:/etc/localtime
- /etc/timezone:/etc/timezone
- /data/redis/conf/sentinel.conf:/etc/redis/sentinel.conf
- /data/redis/logs:/var/log/redis
command: redis-sentinel /etc/redis/sentinel.conf
networks:
- redis-net
networks:
redis-net:
driver: bridge
四、核心配置说明
4.1 Redis 服务端配置 (redis.conf)
# 基础配置
bind 0.0.0.0
# 需被远程连接,关闭这配置
protected-mode no
port 6379
# 指定广播地址,即使 Docker 内部获取到的是 172.x,也强制告诉 Sentinel 我是 ${REDIS_MASTER_IP}
replica-announce-ip ${REDIS_MASTER_IP}
replica-announce-port 6379
# Docker中禁止后台运行(由容器管理)
daemonize no
pidfile /var/run/redis.pid
logfile /var/log/redis/redis.log
# 容器内数据目录(对应宿主机/data/redis/data)
dir /data
# 密码配置(建议修改为自己的密码)
requirepass afe123456
# 允许从节点同步时使用的密码
masterauth afe123456
# 持久化配置(按需调整,默认开启RDB)
# 当满足 “900 秒(15 分钟)内发生至少 1 次写操作” 时,触发 RDB 持久化(将内存中的数据快照写入磁盘)
save 900 1
save 300 10
save 60 10000
# 开启 RDB 文件的压缩功能
rdbcompression yes
# 指定 RDB 快照文件的名称
dbfilename dump.rdb
# 主从复制配置(AP1是主节点,无需配置replicaof)
# 开启无盘同步(减少磁盘IO)
repl-diskless-sync yes
# 无盘同步的延迟时间(单位:秒,默认值为 5)
repl-diskless-sync-delay 5
# 复制积压缓冲区(动态扩容,Redis 8.4默认支持)
repl-backlog-size 1mb
# 其他优化配置
# 内存满时淘汰策略
maxmemory-policy allkeys-lru
# 1. 开启 AOF 持久化
appendonly yes
# 2. 指定 AOF 文件名(Redis 7+ 这是一个目录名的一前缀)
appendfilename "appendonly.aof"
# 3. 开启混合持久化 (核心配置)
# 在 AOF 重写时,会先写入 RDB 格式的快照,再追加增量指令
aof-use-rdb-preamble yes
# 4. 刷盘策略 (性能与安全的平衡)
# 每秒刷盘一次,意味着死机最多丢失 1 秒的数据
appendfsync everysec
# 5. 重写触发机制 (防止文件无限膨胀)
# 当 AOF 文件比上次重写后大小增长 100% 且文件大于 64MB 时触发重写
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb
notify-keyspace-events AE
从节点添加配置
# 指定广播地址,即使 Docker 内部获取到的是 172.x,也强制告诉 Sentinel 我是 ${REDIS_SLAVE_IP}
replica-announce-ip ${REDIS_SLAVE_IP}
replica-announce-port 6379
# 核心:指定主节点(AP1的IP和端口)
replicaof ${REDIS_MASTER_IP} 6379
# 从节点只读(默认开启,避免误写)
replica-read-only yes
以下为生产环境推荐的核心配置项:
| 配置项 | 说明 | 推荐值 |
|---|---|---|
bind |
绑定 IP 地址 | 0.0.0.0 |
protected-mode |
保护模式 | no |
port |
监听端口 | 6379 |
replica-announce-ip |
宣告外部 IP(解决 Docker NAT 问题) | 宿主机实际 IP |
requirepass |
服务访问密码 | 自定义强密码 |
masterauth |
主从同步授权密码 | 与 requirepass 一致 |
appendonly |
开启 AOF 持久化 | yes |
aof-use-rdb-preamble |
开启混合持久化 | yes |
注意: 在从节点配置中,必须包含
replicaof <master-ip> 6379以建立主从关系。
4.2 哨兵配置 (sentinel.conf)
# 基础配置
bind 0.0.0.0
protected-mode no
port 26379
# 强制向其他哨兵和客户端宣告自己的外部IP,从节点需要修复对应自主机IP
sentinel announce-ip ${REDIS_MASTER_IP}
sentinel announce-port 26379
# Docker中禁止后台运行
daemonize no
logfile /var/log/redis/sentinel.log
dir /tmp
# 监控主节点(名称mymaster,主节点IP=AP1的IP,端口6379,quorum=2)
sentinel monitor mymaster ${REDIS_MASTER_IP} 6379 2
# 主节点密码(与Redis主节点一致)
sentinel auth-pass mymaster afe123456
# 故障检测超时时间(30秒,可调整)
sentinel down-after-milliseconds mymaster 30000
# 故障转移时,最多1个从节点同时同步新主节点(避免带宽占用过高)
sentinel parallel-syncs mymaster 1
# 故障转移超时时间(180秒)
sentinel failover-timeout mymaster 180000
# 禁止Sentinel在故障转移后自动重配置主节点(Docker环境下无需开启)
sentinel deny-scripts-reconfig yes
哨兵节点用于监控主节点状态并协调切换。
| 配置项 | 说明 | 示例值 |
|---|---|---|
sentinel monitor |
监控主节点(名称、IP、端口、法定人数) | mymaster ${REDIS_MASTER_IP} 6379 2 |
sentinel auth-pass |
主节点访问密码 | mymaster afe123456 |
sentinel down-after-milliseconds |
故障判定超时时间(毫秒) | 30000 |
sentinel failover-timeout |
故障转移超时时间 | 180000 |
sentinel announce-ip |
宣告哨兵外部 IP | 宿主机实际 IP |
4.3 哨兵数量与 Master 选举
如何选出新的 Redis Master(故障转移)
这里的「Master」指 Redis 主节点(可写的那台),不是哨兵本身。流程简述如下:
-
判定主节点下线
每个哨兵定期探测 Redis 主节点。当某个哨兵认为主节点 主观下线(SDOWN) 后,会向其他哨兵询问;当达到 quorum 个哨兵都认为主节点不可达时,主节点被判定为 客观下线(ODOWN)。 -
选举 Sentinel 领导者
哨兵之间通过 Raft 式选举选出一个 Leader,由它来执行后续故障转移(只会有唯一一个 Sentinel 在执行 failover)。 -
选出新的 Redis Master
Leader 在当前存活的从节点中选一个提升为新主,选择规则通常为:- 若配置了
replica-priority(哨兵侧为sentinel replica-priority),优先选优先级最高且可达的从节点; - 否则按复制偏移量优先选数据最新的从节点;
- 再按
runid字典序等做 tie-break。
选好后向该从节点下发REPLICAOF NO ONE,使其成为新主,其余从节点改为复制新主。
- 若配置了
所以:“选出 master 节点” = 由 Sentinel Leader 在从节点里按优先级/复制进度选一个,并执行提升为主。
是否一定要三台哨兵以上?
| 哨兵数量 | quorum 典型值 | 说明 |
|---|---|---|
| 1 台 | 1 | 可以触发故障转移,但哨兵单点故障则无人做 failover,不推荐生产。 |
| 2 台 | 1 或 2 | quorum=1:能 failover,但两台意见不一致时可能脑裂;quorum=2:需两台都同意才 failover,任一台宕机则永远达不到 2,无法触发故障转移。 |
| 3 台 | 2 | 至少 2 台同意才客观下线并执行 failover;允许 1 台哨兵宕机仍可完成选举与切换,生产推荐最少 3 台 + quorum=2。 |
| 5 台 | 3 | 可容忍 2 台哨兵同时宕机。 |
结论:
- 不是“必须大于 3 台”,但 1 台无高可用、2 台难以兼顾安全与可用,因此 至少 3 台哨兵 + quorum=2 是常见最小生产配置,这样既能选出新 master,又能在挂掉 1 台哨兵时继续工作。
quorum 在配置里即 sentinel monitor mymaster <ip> <port> <quorum> 的最后一个数字,例如:
sentinel monitor mymaster 192.168.3.200 6379 2
表示至少 2 个哨兵认为主节点下线,才会触发客观下线和后续的 Master 选举与故障转移。
两哨兵存活却未选出主节点时的排查
当前是两台 Redis 主机 + 两台哨兵且两台哨兵都存活时,若一直没选出新主,可按下面逐项查。
-
quorum 是否已达到
客观下线(ODOWN)需要至少 quorum 个哨兵认为主节点下线,才会进入故障转移。- 若配置是
sentinel monitor mymaster ... 2,则两台哨兵都必须认为主节点不可达。 - 在两台哨兵上分别执行,看主节点是否已被判为客观下线(
flags里是否有o_down):redis-cli -h <哨兵1_IP> -p 26379 -a <密码> SENTINEL master mymaster redis-cli -h <哨兵2_IP> -p 26379 -a <密码> SENTINEL master mymaster - 若只有一台认为 down,另一台仍认为 master 存活,则不会 ODOWN,也就不会触发选举。常见原因:网络分区、或两台哨兵到原主节点的网络表现不一致。
- 若配置是
-
是否有可提升的从节点
新主是从**当前从节点(replica)**里选出来的;若哨兵认为没有可用从节点,就不会选出新主。- 在两台哨兵上任选一台执行:
redis-cli -h <哨兵IP> -p 26379 -a <密码> SENTINEL slaves mymaster - 看列表是否为空、或从节点是否被标成
s_down/o_down。若从节点也被判下线或复制链路断开,哨兵不会提升它。
- 在两台哨兵上任选一台执行:
-
法定人数与哨兵一致性
执行(在两台哨兵上都跑一次):redis-cli -h <哨兵IP> -p 26379 -a <密码> SENTINEL ckquorum mymaster- 若提示 quorum 未满足,说明当前“认为主节点下线”的哨兵数不足,不会触发故障转移。
-
quorum 配置是否过大
若当时部署时按 3 台哨兵配了quorum=2,现在只剩 2 台,理论上 2 台都同意即可达到 quorum=2。但若误配成 quorum=3,则 2 台永远达不到 3,不会触发客观下线和选举。检查每台哨兵的sentinel.conf里sentinel monitor mymaster ...最后一个数字是否为 2(2 台哨兵时建议为 2)。 -
等待时间
主节点需在 down-after-milliseconds(如 30000)内一直被判定不可达,才会主观下线,再经 quorum 达成客观下线。刚宕机后需至少等够这段时间再看是否选出新主。
小结:两哨兵存活仍不选主,多半是 (1) quorum 未达成(两台对主节点状态看法不一致)或 (2) quorum 配成 3,或 (3) 从节点被哨兵判为不可用。先查 SENTINEL master mymaster 的 flags、SENTINEL slaves mymaster 和 SENTINEL ckquorum mymaster,再对照上述几条处理。
五、客户端集成(Redisson)
在 Spring Boot 应用中,使用 Redisson 实现哨兵模式的连接:
spring:
redis:
redisson:
config: |
sentinelServersConfig:
masterName: "mymaster" # Sentinel 里监控主库的名字(sentinel monitor <name> ...)
sentinelAddresses: # Sentinel 节点地址列表(redis://host:port)
- "redis://${REDIS_MASTER_IP}:26379"
- "redis://${REDIS_SLAVE_IP}:26379"
- "redis://${REDIS_SENTINEL_3_IP}:26379"
# --- 认证(Redis 6+ ACL 也可用 username)---
password: "afe123456" # Redis 主从节点密码(requirepass / ACL 密码)
sentinelPassword: "afe123456" # Sentinel 密码(requirepass / ACL 密码);若与 password 相同也可省略
# --- DB ---
database: ${app.redis-database:0} # 选择 DB(0~15,取决于你的 redis 配置)
# --- 启动检查 / 发现(单哨兵宕机不影响业务必读)---
checkSentinelsList: false # 建议 false:启动/刷新时不强制校验“全部”哨兵,任一只哨兵宕机不会导致客户端整体不可用(默认 true 会连所有哨兵,一个不通就报错)
sentinelsDiscovery: true # 是否自动发现更多 sentinel(默认 true;Docker/NAT 环境可考虑关掉避免“拓扑污染”)
dnsMonitoringInterval: 5000 # DNS 变更监控间隔 ms;-1 表示禁用(对域名方式接入有用)
# --- 读写/订阅模式 ---
readMode: "MASTER" # 读策略:SLAVE / MASTER / MASTER_SLAVE
subscriptionMode: "MASTER" # 订阅(pubsub)连接使用节点:SLAVE / MASTER
checkSlaveStatusWithSyncing: true # 检查 slave 的 master-link-status=ok(默认 true)
# --- 负载均衡(可选,默认 RoundRobin)---
# 注意:下面这种 !<class> 写法需要 YAML 标签支持(Redisson 原生 YAML 支持)
loadBalancer: !<org.redisson.connection.balancer.RoundRobinLoadBalancer> {}
# --- 连接池(重要:这些是“每个节点”的池大小)---
masterConnectionMinimumIdleSize: 24 # 每个 master 最小空闲连接数(默认 24)
masterConnectionPoolSize: 64 # 每个 master 最大连接数(默认 64)
slaveConnectionMinimumIdleSize: 24 # 每个 slave 最小空闲连接数(默认 24)
slaveConnectionPoolSize: 64 # 每个 slave 最大连接数(默认 64)
# --- 订阅连接池(pubsub)---
subscriptionConnectionMinimumIdleSize: 1 # 订阅连接最小空闲数(默认 1)
subscriptionConnectionPoolSize: 50 # 订阅连接最大连接数(默认 50)
subscriptionsPerConnection: 5 # 每条订阅连接允许的订阅数上限(默认 5)
subscriptionTimeout: 7500 # 订阅超时 ms(默认 7500)
# --- 超时与重试 ---
idleConnectionTimeout: 10000 # 连接空闲多久后可被回收 ms(默认 10000)
connectTimeout: 10000 # 建连超时 ms(默认 10000)
timeout: 6000 # 命令响应超时 ms(默认 3000,从成功发送命令后开始计时)
retryAttempts: 4 # 命令发送失败重试次数(默认 4)
# --- 连接保活 ---
pingConnectionInterval: 30000 # 定期 PING 检测死连接 ms;0 关闭(默认 30000)
keepAlive: false # TCP keepAlive(默认 false)
tcpNoDelay: true # TCP_NODELAY(默认 true)
# --- 故障 slave 处理 ---
failedSlaveReconnectionInterval: 3000 # slave 断线后重连尝试间隔 ms(默认 3000)
failedSlaveNodeDetector: !<org.redisson.client.FailedConnectionDetector> {}
threads: 16 # Redisson 业务线程池(默认 16;监听/远程服务等)
nettyThreads: 32 # Netty IO 线程(默认 32;0=CPU*2)
transportMode: "NIO" # NIO / EPOLL / KQUEUE(默认 NIO)
protocol: "RESP2" # RESP2 / RESP3(默认 RESP2)
# 编解码器(默认 Kryo5Codec;你用 JsonJacksonCodec 也可以)
codec:
class: "org.redisson.codec.JsonJacksonCodec"
# 分布式锁看门狗(默认 30000ms;无 leaseTimeout 的锁依赖它续期)
lockWatchdogTimeout: 30000
# 其他通用项(按需)
lazyInitialization: false # true=首次用到才连接;false=启动即连接
useThreadClassLoader: true # 解决部分容器 ClassNotFound 问题
keepPubSubOrder: true # PubSub 消息是否保持到达顺序
useScriptCache: true # Lua 脚本缓存
# 下面这些是高级项/按需再开:
valkeyCapabilities: [] # 例如 ["REDIRECT"]
lockWatchdogBatchSize: 100
checkLockSyncedSlaves: true
slavesSyncTimeout: 1000
reliableTopicWatchdogTimeout: 600000
minCleanUpDelay: 5
maxCleanUpDelay: 1800
cleanUpKeysAmount: 100
六、运维常用命令
6.1 哨兵管理命令
详细的 Redis 常用命令及 Sentinel 运维操作请参考:Redis 常用命令使用指南
通过 redis-cli 连接哨兵端口(默认 26379)执行:
| 命令 | 功能描述 |
|---|---|
SENTINEL masters |
列出所有被监控的主节点状态 |
SENTINEL master <name> |
查看指定主节点的详细信息 |
SENTINEL slaves <name> |
查看指定主节点的从节点列表 |
SENTINEL sentinels <name> |
列出除当前节点外的其他哨兵实例 |
SENTINEL get-master-addr-by-name <name> |
获取当前有效的主节点 IP 和端口 |
SENTINEL failover <name> |
手动强制触发故障转移 |
SENTINEL reset <pattern> |
重置配置,清除过期节点信息 |
SENTINEL ckquorum <name> |
检查当前哨兵数量是否满足法定人数 |
七、注意事项与最佳实践
注意:
- 脑裂保护:建议配置
min-replicas-to-write 1和min-replicas-max-lag 10,确保主库至少有 1 个正常的从库时才允许写入,防止网络分区导致的数据丢失。- Docker 网络:在容器环境下,务必配置
replica-announce-ip和sentinel announce-ip,否则哨兵可能会记录容器内部 IP 导致客户端无法连接。- 持久化平衡:推荐开启混合持久化(AOF + RDB),并设置
appendfsync everysec以平衡性能与安全性。- 权限细化:生产环境建议将
/data/redis目录权限进一步收紧,仅允许特定 UID 访问。
八、单哨兵宕机不影响业务(Redisson 配置)
8.1 现象与原因
当只停止一个哨兵节点时,若出现:
No route to host: 192.168.3.110/192.168.3.110:26379(其中 110 为已停的哨兵)- 或
RedisReadonlyException: READONLY You can't write against a read only replica(写到了已变为 replica 的旧 master)
主要原因是 Redisson 的以下行为:
| 配置项 | 默认值 | 导致“单哨兵挂则全挂”的原因 |
|---|---|---|
| checkSentinelsList | true |
启动或周期性刷新时会对配置中的每一个哨兵执行校验/连接;任一哨兵不可达(如 110 已停)会触发异常或阻塞,导致客户端无法正常从其余哨兵获取当前 master,进而整体不可用或拿到过期拓扑。 |
RedisReadonlyException 通常表示已经发生过故障转移(当前写到的 192.168.3.200 已被降为 replica),而客户端因上述原因无法从存活的哨兵刷新到新 master,仍向旧主写,从而报只读。
8.2 推荐配置(单哨兵宕机不影响业务)
在 Nacos/应用配置中,将 Redisson 的哨兵相关配置改为:
sentinelServersConfig:
masterName: "mymaster"
sentinelAddresses:
- "redis://192.168.3.230:26379"
- "redis://192.168.3.200:26379"
- "redis://192.168.3.110:26379"
# 关键:单哨兵宕机时仍可从其余哨兵获取 master,不影响业务
checkSentinelsList: false # 不强制校验“全部”哨兵,任一只不可达不会拖垮客户端
sentinelsDiscovery: true # 按需保留;Docker/NAT 环境若出现拓扑混乱可改为 false
要点:
- checkSentinelsList: false:不再要求能连上配置里的每一个哨兵,只要有一个哨兵可用即可获取 master 并刷新拓扑,单哨兵停机不会导致业务不可用。
- 保留多个
sentinelAddresses:多个哨兵仍可做高可用,只是客户端不会因“其中一个连不上”而整体失败。
8.3 为什么 SENTINEL masters 显示 200 却无法写入?
SENTINEL masters 列出的是哨兵当前记录的主节点信息,但在以下情况下会出现“查到的是 200,却写不进去”:
-
200 已被降级为副本
故障转移后,192.168.3.200 可能已经执行了REPLICAOF指向新主,自身变为只读副本。此时SENTINEL masters里可能仍显示ip 192.168.3.200(视图未刷新或不同哨兵收敛有先后),但连上 200 执行写会报READONLY。 -
应看“当前主节点”而非仅看 masters 表
用下面命令取的是当前可写主节点,比SENTINEL masters更贴近实际:redis-cli -h 192.168.3.230 -p 26379 -a afe123456 SENTINEL get-master-addr-by-name mymaster若返回的是另一台(例如 192.168.3.xxx),说明新主已切换,应连该地址写。
-
在 200 上自检角色
直连 200(你环境里 Redis 端口为 16379):redis-cli -h 192.168.3.200 -p 16379 -a afe123456 ROLE若返回
slave,说明 200 已是副本,只能读不能写;写请求应发往get-master-addr-by-name返回的那台。
小结:查到是 200 却不能写,多半是 200 已是 replica。用 SENTINEL get-master-addr-by-name mymaster 确认当前主,并连该主写;应用侧在 checkSentinelsList: false 且能连上任意存活哨兵时会自动刷新到新主。
8.4 故障转移后的核对
若已出现 s_down,o_down 或 role-reported: slave,说明哨兵已做过故障转移。建议在仍存活的哨兵上确认当前主节点:
redis-cli -h 192.168.3.230 -p 26379 -a afe123456 SENTINEL get-master-addr-by-name mymaster
应用在能连上任意存活哨兵且 checkSentinelsList: false 时,会通过拓扑刷新自动指向新 master,无需改配置。
8.5 双节点均为 slave(复制环)的排查与处理
当两台 Redis 主机在 ROLE 下均显示为 slave,且互相把对方当作 master 时,形成复制环:没有真正的主节点,所有写请求都会报 READONLY。
典型表现(示例 IP/端口可替换为实际环境):
- 192.168.3.200:16379 执行
ROLE→slave,master 指向 192.168.3.230:6379 - 192.168.3.230:6379 执行
ROLE→slave,master 指向 192.168.3.200:16379
常见原因:多次故障转移、手动改过 replicaof、或 Sentinel 在异常情况下写入了错误的主从关系。
处理步骤(人工指定主从):
-
选定一台作为唯一 master(示例以 192.168.3.230 为主,端口按实际为准)
在该节点上执行:redis-cli -h 192.168.3.230 -p 6379 -a <密码> REPLICAOF NO ONE执行后该节点成为唯一可写主节点。
-
将另一台设为该主的从节点(示例为 192.168.3.200 作为 230 的从)
在从节点上执行(端口与上一步一致):redis-cli -h 192.168.3.200 -p 16379 -a <密码> REPLICAOF 192.168.3.230 6379 -
校验
- 在主节点上执行
ROLE,应看到master。 - 在从节点上执行
ROLE,应看到slave,且 master 为刚指定的主节点地址与端口。
- 在主节点上执行
-
哨兵
Sentinel 会通过心跳发现新的主从拓扑;若长时间未更新,可在当前主节点所在机器重启该机 Sentinel,或按需执行SENTINEL failover(拓扑已正确时一般无需执行)。
注意:端口需与现网一致(如 200 使用 16379、230 使用 6379 时,上述命令中的端口要对应修改)。
参考资料:Redisson 官方配置文档