必须用redis.NewClusterClient(),因NewClient()不解析CLUSTER SLOTS、不计算CRC16 slot映射、不处理MOVED/ASK重定向,导致请求打错节点后直接报错或静默失败;Addrs为唯一必填字段,需传入至少两个在线主节点地址(如[]string{"host:port"}),且不可含redis://或DB编号。

Go 语言连接 Redis 集群必须用 redis.NewClusterClient(),否则必报 MOVED 或静默路由失败;分布式部署本身不依赖特定 Go 库,关键在服务发现、状态同步与连接容错设计。
为什么 redis.NewClient() 连 Redis 集群一定失败
单节点客户端不解析 CLUSTER SLOTS,不计算 key 的 slot(CRC16(key) mod 16384),也不处理 MOVED/ASK 响应。你发 GET user:1001,它可能打到任意节点;若该节点不负责对应 slot,就原样返回错误,且不重试、不跳转。
- 典型错误:反复出现
redis: MOVED 12345 10.0.1.5:6379,或connection refused(因连了已下线节点且拓扑未刷新) - 不是密码错、网络不通,是类型错配——集群必须用集群客户端
- 哪怕只填一个节点地址,
redis.NewClient()也当单机连,不会自动发现其他节点
redis.NewClusterClient() 初始化必须填哪些参数
Addrs 是唯一强制字段,但填法直接影响可用性。它不是“随便写一个能通的地址”,而是客户端初始化时拉取集群拓扑的起点。
-
Addrs必须是[]string{"host:port"}格式,不能带redis://,不能写数据库编号(集群不支持SELECT) - 至少填两个主节点地址,例如
[]string{"127.0.0.1:7000", "127.0.0.1:7001"};只填一个,该节点宕机或网络不通,客户端直接初始化失败 - Docker 环境别用
localhost,改用host.docker.internal或宿主机实际 IP - 避免混入从节点地址(除非明确需要读从),因为初始化阶段会尝试连所有地址,而从节点默认不响应
CLUSTER SLOTS,导致超时
Key 设计不当会导致 MGET/DEL 直接报 CROSSSLOT
Redis 集群按 slot 分片,多个 key 若落在不同 slot,批量命令就被拒绝。这不是客户端 bug,是集群协议强制限制。
- 错误写法:
MGET user:1001 user:1002—— 两个 key 哈希后大概率跨 slot - 正确做法:用哈希标签强制同 slot,例如
SET {user1001}.profile name "alice",大括号内内容参与 CRC16 计算 - 业务上需约定 key 结构,比如用户相关数据统一用
{user:id}前缀,订单用{order:id} - SCAN 类命令默认游标为 0 时也易触发跨 slot 错误;更稳妥的是先查
CLUSTER SLOTS,再对每个节点单独连单机 client 执行 SCAN
分布式部署中连接容错容易被忽略的点
集群客户端不是“连上就一劳永逸”。拓扑变更(如节点增删、主从切换)后,客户端需及时感知并更新本地 slot 映射,这依赖后台定时刷新和重定向机制。
- 务必设置
MaxRedirects: 8(默认值即可),超限说明集群异常,不是客户端问题 - 加
.SetMaxRetries(2)防止网络抖动导致重定向失败,否则一次MOVED就直接报错 - ReadOnly 默认为
false,高并发读场景下所有请求都压 master;设为true后需确认 Redis 配置了slave-read-only no或使用 Redis 6+ 并启用READONLY命令 - 测试时别只跑
SET/GET,一定要验证MGET、DEL、INCR等多 key 命令是否按预期落到同一节点
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











