必须用redis.NewFailoverClient连接哨兵,不能用NewClient直连地址,否则绕过哨兵失去故障转移能力;NewClient会将哨兵端口26379误作Redis数据端口,导致执行SET/GET时返回ERR unknown command。

必须用 redis.NewFailoverClient,不能用 redis.NewClient 直连地址——否则哨兵形同虚设,主节点宕机后立刻断连。
为什么 NewClient 连 Sentinel 地址会失败
因为 redis.NewClient 试图把 Sentinel 当成 Redis 实例来用,而 Sentinel 只响应 SENTINEL 类管理命令(如 SENTINEL GET-MASTER-ADDR-BY-NAME),不处理 SET、GET 等数据命令。你传进去的 Addr: "127.0.0.1:26379" 会被客户端当成 Redis 数据端口,连接后发 SET 就收到 ERR unknown command 或直接断开。
本质区别:
- Sentinel 是监控服务,端口默认
26379,只做发现和通知 - Redis 实例是数据服务,端口默认
6379,才真正执行业务命令
FailoverOptions 关键字段怎么填才生效
填错任意一个关键字段,客户端初始化就静默失败或后续无法切主——日志里反复出现 failed to resolve master 就是典型信号。
-
MasterName必须和sentinel monitor配置项完全一致(大小写敏感),例如配置文件里是sentinel monitor mymaster 127.0.0.1 6379 2,这里就得填"mymaster" -
SentinelAddrs填的是哨兵地址列表(host:port),不是 Redis 实例地址;至少写一个,但建议全写(如[]string{"10.0.1.10:26379", "10.0.1.11:26379"}),避免单点失效 -
Password是 Redis 实例密码(即requirepass),不是 Sentinel 的认证密码;如果 Sentinel 也启了认证(少见),得额外设SentinelPassword -
DB字段有效,可指定数据库编号;Username仅在 Redis 6+ ACL 场景下生效,且需同时配Username和SentinelUsername(二者独立)
本地开发连不上?先查这三件事
90% 的“连不上”问题不在 Go 代码,而在环境配置。尤其 Docker 容器内运行时容易踩坑。
- Sentinel 配置里
protected-mode yes没关,或者bind没包含客户端网段(比如只绑了127.0.0.1,但 Go 程序跑在容器里,实际走的是宿主机 IP) - Redis 实例的
requirepass和 Sentinel 的requirepass是两套配置:只给 Redis 设密码,却没在FailoverOptions.Password里填,就会卡在认证环节 - Sentinel 配置中漏了
sentinel resolve-hostnames yes(尤其在 Kubernetes 或 DNS 解析场景下),导致它返回的主节点地址是主机名而非 IP,Go 客户端无法直连
怎么验证哨兵链路真的在工作
client.Ping(ctx).Err() 成功只代表当前连上了某个节点,不等于哨兵已成功发现主节点或能响应故障转移。更可靠的验证方式是:
- 启动客户端后立刻执行一次写操作:
client.Set(ctx, "health_check", "ok", 0).Err(),成功说明已连上可用主节点 - 手动 kill 主 Redis 进程,观察日志是否出现
+switch-master事件,并确认后续Set不报错 - 检查
client.Options().Addr的值是否随故障转移动态更新(注意:该字段只读,反映当前实际连接地址)
真正的难点从来不在初始化那一行代码,而在于哨兵配置与网络可达性之间的隐式耦合——它不报错,但就是不切换主节点,这种静默失效最耗时间。


















