Golang搭建Redis集群环境教程

本文深入剖析了使用Golang搭建和连接Redis集群测试环境的常见陷阱与关键实践，强调集群必须满足3主3从共6节点的最低要求才能正常握手，指出Go客户端必须使用`redis.NewClusterClient`而非单机客户端，并需传入至少2–3个可连通的主节点地址（禁用localhost，Docker中应使用`host.docker.internal`或服务名），同时提醒读者避开`KEYS`/`SCAN`等跨slot命令、正确处理MOVED重定向、谨慎配置Docker网络及集群端口，真正将调试重心从“代码逻辑”转向“环境真实性验证”，帮助开发者快速定位90%以上连不上集群的根本原因——不是代码写错了，而是集群压根没跑起来或配置未生效。

用 go-redis/redis 连 Redis 集群前，先确认集群是否真在跑

很多测试环境连不上，不是代码写错了，是根本没启动 Redis 集群，或者只起了单节点当集群用。Redis 集群必须至少 6 个节点（3 主 3 从）才能完成握手，少一个就 CLUSTER NODES 显示 fail，go-redis 会直接报 redis: cluster has no slots assigned 或卡在初始化。

实操建议：

• 用 redis-cli --cluster create 启动集群，别手写 redis.conf 拼集群配置
• 启动后立刻执行 redis-cli -c -p 7000 CLUSTER NODES，确保输出里有至少 3 个 master 且状态为 connected
• Go 侧不要用 redis.NewClient，必须用 redis.NewClusterClient，否则它会当单机连，路由失败也不报错，只静默 fallback 到第一个节点
• 连接时加 .SetMaxRetries(2)，避免网络抖动导致 MOVED 重定向失败

redis.NewClusterClient 的 Addr 参数不能只填一个地址

集群客户端不是“连上一个节点就能自动发现其他节点”，它依赖初始节点返回的 CLUSTER SLOTS 结果做本地 slot 映射。如果只传一个地址，而这个节点恰好宕了或网络不通，客户端就起不来——不会自动轮询列表里的下一个。

实操建议：

• Addrs 字段必须传至少 2–3 个节点地址，例如 []string{"127.0.0.1:7000", "127.0.0.1:7001", "127.0.0.1:7002"}
• 地址要带端口，不能省略；IP 尽量用宿主机可解析的（Docker 里别用 localhost，改用 host.docker.internal 或实际 IP）
• 不要在 Addrs 里混入从节点地址（除非明确需要读从），因为 go-redis 默认只往 master 写，但初始化阶段仍会尝试连所有地址——从节点不响应 CLUSTER SLOTS 会导致初始化超时

测试时用 SET 和 GET 没问题，但 KEYS、SCAN 会失败

Redis 集群不支持跨 slot 的全局命令。KEYS * 被直接拒绝，报错 CROSSSLOT Keys in request don't hash to the same slot；SCAN 默认游标为 0 时也常触发类似错误，因为客户端不知道该往哪个节点发。

实操建议：

• 测试数据分布，用带哈希标签的 key：SET {user1001}.profile name "alice"，大括号内内容决定 slot，同一业务数据强制落在同个节点
• 遍历要用 SCAN + CLIENT SETNAME 配合，但更稳妥的是：对每个节点单独连单机 client，执行 SCAN（需先用 CLUSTER SLOTS 查出各节点负责的 slot 范围）
• 单元测试里别 mock 整个集群行为，而是 mock redis.Cmdable 接口，重点覆盖 MOVED 和 ASK 重定向逻辑

Docker Compose 跑集群时，network_mode: host 容易让 Go 测试连错

本地开发常用 network_mode: host 让容器复用宿主机网络，看似省事，但 Go 程序里写的 127.0.0.1:7000 在容器内其实指向容器自己的 loopback，不是宿主机的 Redis 节点。

实操建议：

• Docker Compose 中显式定义自定义 network，并用 service 名作为 host（如 redis-node-1:7000），Go 代码里也用这个名
• 如果必须用 host 模式，Go 测试进程得和 Redis 容器在同一网络命名空间下（比如用 docker run --network host 启动测试），而不是在 IDE 里直接 go test
• 启动后加一行日志：fmt.Printf("connecting to %+v\n", cfg.Addrs)，确认实际连接地址和你预期一致

集群配置最耗时间的地方，往往不在 Go 代码，而在确认每个 Redis 进程的 cluster-enabled yes 是否生效、cluster-config-file 是否被多个实例共用、以及防火墙有没有拦掉集群总线端口（默认比服务端口大 10000，如 7000 的服务端口对应 17000 的集群端口）。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~