直接配置spring.redis.cluster.nodes即可连接redis集群,但节点格式必须为host:port(如127.0.0.1:7001),禁用redis://、空格及localhost;需设置spring.redis.cluster.max-redirects(建议等于master数),并删除被忽略的spring.redis.host/port。

直接配 spring.redis.cluster.nodes 就能连上集群,但节点列表写错、格式不规范或漏关键配套参数,90% 的连接失败都发生在这里。
节点地址必须用 host:port 格式,不能带 redis:// 或空格
常见错误是复制了其他文档里的示例,比如写成 redis://localhost:7001 或 127.0.0.1 : 7001(中间有空格)。Spring Boot 的 RedisClusterConfiguration 解析器只认纯 host:port 形式:
- ✅ 正确:
127.0.0.1:7001,127.0.0.1:7002,127.0.0.1:7003 - ❌ 错误:
redis://127.0.0.1:7001、127.0.0.1:7001 , 127.0.0.1:7002、localhost:7001(部分 DNS 不稳定环境会解析失败) - ⚠️ 注意:所有节点必须是可互相发现的 master 节点(非仅 slave),且集群已通过
redis-cli --cluster create正确构建并进入ok状态
必须配 spring.redis.cluster.max-redirects,否则跨节点操作直接报错
Redis 集群客户端收到 MOVED 或 ASK 重定向响应时,需要知道最多尝试几次。不设这个值,Lettuce 默认为 0,意味着拒绝重定向 —— 表现为 RedisCommandExecutionException: MOVED 或 ASK 异常。
- 建议值设为集群 master 节点数,例如 6 个 master 就设
spring.redis.cluster.max-redirects=6 - 该值不是越大越好:超过实际跳转深度会导致无意义等待,超时后仍失败
- 若用 Jedis(需显式引入
jedis依赖),它默认支持重定向,但 Spring Boot 2.3+ 默认用 Lettuce,所以这个配置不可省
密码、超时、连接池参数要分清作用域,混用会静默失效
Spring Boot 自动配置对不同客户端使用不同前缀,写错前缀等于没配:
- 密码统一走
spring.redis.password(集群所有节点必须相同,且不能含逗号、空格、斜杠等分隔符) - 超时统一用
spring.redis.timeout(socket 级,建议 ≥2000ms,避免网络抖动触发误判) - 连接池只对 Lettuce 有效:用
spring.data.redis.lettuce.pool.*,比如spring.data.redis.lettuce.pool.max-idle=100;Jedis 的池配置是spring.redis.jedis.pool.*,但 Spring Boot 2.3+ 不再自动装配 Jedis,除非你手动排除 Lettuce 并引入 Jedis 依赖 -
spring.redis.cluster.command-timeout已被废弃(Spring Boot 3.x 起移除),应改用spring.redis.timeout
最容易被忽略的是:集群模式下 spring.redis.host 和 spring.redis.port 会被完全忽略,哪怕它们存在也不会报错 —— 这会让开发者误以为配置生效了,实则连的是单机 fallback 地址(如果启用了 fallback)。务必删掉这两项,只保留 cluster.nodes 及其配套参数。











