必须用 redis.NewFailoverClient(),因其专为哨兵模式设计:它周期性向哨兵节点查询当前主节点地址(SENTINEL GET-MASTER-ADDR-BY-NAME),自动更新连接,而 NewClient() 死连初始地址、NewClusterClient() 因不支持 CLUSTER 命令会报错。

必须用 redis.NewFailoverClient(),不能用 redis.NewClient() 或 redis.NewClusterClient() —— 哨兵模式和集群模式是互斥的架构,混用必连不上主节点或静默路由到下线节点。
为什么 NewFailoverClient 是唯一正确入口
哨兵模式下,Redis 主节点地址是动态的:哨兵选举新主后,旧主可能下线、新主 IP/Port 变更。单节点客户端 redis.NewClient() 会死连初始配置的地址,一旦主切走就持续报 connection refused 或 redis: nil(实际是连错节点读不到数据);集群客户端 redis.NewClusterClient() 则会尝试解析 CLUSTER SLOTS,而哨兵集群根本不响应该命令,直接返回 ERR This instance has cluster support disabled。
只有 redis.NewFailoverClient() 会周期性向哨兵节点(不是 Redis 节点!)发起 SENTINEL GET-MASTER-ADDR-BY-NAME 查询,自动更新当前主节点地址,并在连接失败时重试哨兵列表中的下一个节点。
- 错误现象包括:
redis: nil却没报错(其实是连了从节点但没设ReadOnly: true)、timeout(连了已下线主节点且不刷新)、日志里反复出现failed to get master address - 哨兵地址填的是
SentinelAddrs,不是 Redis 的MasterName地址 —— 后者只是逻辑名,比如"mymaster",真实 IP 端口全靠哨兵返回 - 客户端不感知故障转移过程,只要哨兵集群健康,
NewFailoverClient()内部就会完成重连,应用层无须手动Close()或重建 client
SentinelAddrs 和 MasterName 怎么配才不踩坑
SentinelAddrs 必须是哨兵进程监听的地址列表,格式为 []string{"172.31.109.138:20000", "172.31.109.138:20001"},不能带 redis://,也不能写成 Redis 主节点地址(如 "172.31.109.138:6379")。MasterName 是你在 sentinel.conf 里配置的 sentinel monitor <master-name></master-name> 名称,大小写敏感,且必须与哨兵配置完全一致。
立即学习“go语言免费学习笔记(深入)”;
- 常见错误:把哨兵端口写成 Redis 端口(比如填
":6379"),结果客户端连上 Redis 实例却发SENTINEL命令,报ERR unknown command `SENTINEL` - 哨兵列表建议填至少两个,防止单个哨兵宕机导致初始化失败;但不用填全部,客户端内部会轮询可用哨兵
- 如果哨兵启用了密码(
requirepass),需在FailoverOptions中设置Password字段,否则查询主地址会认证失败
ReadOnly、DB 和 TLS 配置的关键约束
哨兵模式下,DB 字段有效(集群模式不支持 SELECT),但仅对主节点连接生效;从节点默认拒绝写命令,读请求是否能打到从节点取决于 ReadOnly 设置。注意:go-redis 的 ReadOnly 不是 Redis 的 READONLY 命令开关,而是客户端行为标记 —— 设为 true 后,Get、MGET 等只读命令才可能路由到从节点(前提是哨兵返回了可用从节点地址)。
-
ReadOnly: false(默认)→ 所有命令都打主节点,读压力全在主上,容易成为瓶颈 -
ReadOnly: true→ 读命令随机选一个可用从节点,但要求 Redis 配置slave-read-only yes(默认值),否则从节点会拒绝执行命令 -
DB只影响主节点连接,默认为0;若哨兵返回的从节点未启用对应 DB,Get可能返回redis: nil(不是错误,需显式判断) - TLS 配置需放在
FailoverOptions.MasterClientOptions和FailoverOptions.SentinelClientOptions里分别设置,不能只设一边
如何验证连接真的“稳”了
光 Ping 通不等于稳 —— Ping().Result() 成功只说明当前主节点可达,无法覆盖故障转移场景。真正验证要模拟主节点宕机:手动 redis-cli -p 6379 DEBUG sleep 30 拖住主节点,或直接 kill -9 主进程,观察客户端是否在 10–20 秒内自动恢复读写(哨兵默认 down-after-milliseconds 30000,加选举时间)。
- 关键日志线索:
master changed from 172.31.109.138:6379 to 172.31.109.139:6379出现在 hook 回调中,说明切换成功 - 务必在
FailoverOptions中传入MasterClientOptions: &redis.Options{...},否则主节点连接不会继承超时、重试等参数,故障时可能卡死 - 不要在每次请求前新建
NewFailoverClient(),它内部维护连接池和哨兵探测 goroutine,应作为长生命周期对象复用
最易被忽略的一点:哨兵模式下没有“拓扑发现”概念,客户端不会主动拉取从节点列表 —— 它只信任哨兵返回的主地址和从地址。如果你依赖 SlaveOf 关系做读写分离,必须确保哨兵配置了 sentinel down-after-milliseconds 和 sentinel parallel-syncs 合理,否则从节点状态同步延迟会导致客户端拿到过期的从节点地址。



















