Files
agent-skills/skills/g3fo-docs/references/middleware/redis/deploy.md
T

25 KiB
Raw Blame History

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 主节点(可写的那台),不是哨兵本身。流程简述如下:

  1. 判定主节点下线
    每个哨兵定期探测 Redis 主节点。当某个哨兵认为主节点 主观下线(SDOWN) 后,会向其他哨兵询问;当达到 quorum 个哨兵都认为主节点不可达时,主节点被判定为 客观下线(ODOWN)。

  2. 选举 Sentinel 领导者
    哨兵之间通过 Raft 式选举选出一个 Leader,由它来执行后续故障转移(只会有唯一一个 Sentinel 在执行 failover)。

  3. 选出新的 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 主机 + 两台哨兵且两台哨兵都存活时,若一直没选出新主,可按下面逐项查。

  1. 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,也就不会触发选举。常见原因:网络分区、或两台哨兵到原主节点的网络表现不一致。
  2. 是否有可提升的从节点
    新主是从**当前从节点(replica)**里选出来的;若哨兵认为没有可用从节点,就不会选出新主。

    • 在两台哨兵上任选一台执行:
      redis-cli -h <哨兵IP> -p 26379 -a <密码> SENTINEL slaves mymaster
      
    • 看列表是否为空、或从节点是否被标成 s_down/o_down。若从节点也被判下线或复制链路断开,哨兵不会提升它。
  3. 法定人数与哨兵一致性
    执行(在两台哨兵上都跑一次):

    redis-cli -h <哨兵IP> -p 26379 -a <密码> SENTINEL ckquorum mymaster
    
    • 若提示 quorum 未满足,说明当前“认为主节点下线”的哨兵数不足,不会触发故障转移。
  4. quorum 配置是否过大
    若当时部署时按 3 台哨兵配了 quorum=2,现在只剩 2 台,理论上 2 台都同意即可达到 quorum=2。但若误配成 quorum=3,则 2 台永远达不到 3,不会触发客观下线和选举。检查每台哨兵的 sentinel.conf 里 sentinel monitor mymaster ... 最后一个数字是否为 2(2 台哨兵时建议为 2)。

  5. 等待时间
    主节点需在 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> 检查当前哨兵数量是否满足法定人数

七、注意事项与最佳实践

注意:

  1. 脑裂保护:建议配置 min-replicas-to-write 1 和 min-replicas-max-lag 10,确保主库至少有 1 个正常的从库时才允许写入,防止网络分区导致的数据丢失。
  2. Docker 网络:在容器环境下,务必配置 replica-announce-ip 和 sentinel announce-ip,否则哨兵可能会记录容器内部 IP 导致客户端无法连接。
  3. 持久化平衡:推荐开启混合持久化(AOF + RDB),并设置 appendfsync everysec 以平衡性能与安全性。
  4. 权限细化:生产环境建议将 /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,却写不进去”:

  1. 200 已被降级为副本
    故障转移后,192.168.3.200 可能已经执行了 REPLICAOF 指向新主,自身变为只读副本。此时 SENTINEL masters 里可能仍显示 ip 192.168.3.200(视图未刷新或不同哨兵收敛有先后),但连上 200 执行写会报 READONLY。

  2. 应看“当前主节点”而非仅看 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),说明新主已切换,应连该地址写。

  3. 在 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 在异常情况下写入了错误的主从关系。

处理步骤(人工指定主从):

  1. 选定一台作为唯一 master(示例以 192.168.3.230 为主,端口按实际为准)
    在该节点上执行:

    redis-cli -h 192.168.3.230 -p 6379 -a <密码> REPLICAOF NO ONE
    

    执行后该节点成为唯一可写主节点。

  2. 将另一台设为该主的从节点(示例为 192.168.3.200 作为 230 的从)
    在从节点上执行(端口与上一步一致):

    redis-cli -h 192.168.3.200 -p 16379 -a <密码> REPLICAOF 192.168.3.230 6379
    
  3. 校验

    • 在主节点上执行 ROLE,应看到 master。
    • 在从节点上执行 ROLE,应看到 slave,且 master 为刚指定的主节点地址与端口。
  4. 哨兵
    Sentinel 会通过心跳发现新的主从拓扑;若长时间未更新,可在当前主节点所在机器重启该机 Sentinel,或按需执行 SENTINEL failover(拓扑已正确时一般无需执行)。

注意:端口需与现网一致(如 200 使用 16379、230 使用 6379 时,上述命令中的端口要对应修改)。


参考资料:Redisson 官方配置文档