Spring Boot 3.0 默认用 Lettuce 连 Redis 集群,只需正确配置 spring.redis.cluster.nodes(纯 host:port、逗号分隔)、spring.redis.cluster.max-redirects(建议等于 master 数),并确保无 spring.redis.host 冲突,即可自动连接成功,无需 Java 配置类。

Spring Boot 3.0 默认用 Lettuce 连 Redis 集群,只要 spring.redis.cluster.nodes 格式对、spring.redis.cluster.max-redirects 设了、没混进 spring.redis.host,就能连上——不需要写任何 Java 配置类,也不需要手动 new LettuceConnectionFactory。
spring.redis.cluster.nodes 必须是纯 host:port 列表,不能带协议或空格
这是启动失败最常卡住的地方。Lettuce 的解析器只接受逗号分隔的 host:port 字符串,其他格式全被忽略或报错。
- ✅ 正确:
192.168.1.101:6379,192.168.1.102:6379,192.168.1.103:6379 - ❌ 错误:
redis://192.168.1.101:6379(含协议)、192.168.1.101:6379 , 192.168.1.102:6379(含空格)、localhost:6379(DNS 不稳时解析失败) - ⚠️ 所有节点必须是集群中可互相发现的 master 节点,不能只填部分 slave;用
redis-cli -c -h 192.168.1.101 -p 6379 -a yourpass cluster nodes确认返回里有多个master且状态为connected
必须显式配置 spring.redis.cluster.max-redirects
Lettuce 默认 max-redirects=0,意味着收到 MOVED/ASK 响应时直接抛 RedisCommandExecutionException,而不是自动跳转。这不是连接失败,而是路由能力被禁用了。
- 建议值设为集群中 master 节点数,例如 3 主 3 从就配
spring.redis.cluster.max-redirects=3 - 值太大(比如设成 10)不会提升成功率,反而让重试耗尽超时时间后才失败
- 这个参数在 Spring Boot 3.x 里仍有效,
spring.redis.cluster.command-timeout已废弃,别用
密码、超时、连接池参数前缀不能写错
Spring Boot 对不同配置项使用不同命名空间,写错前缀等于没配,且无提示。
- 密码统一走
spring.redis.password(所有节点共用同一密码,不能含逗号或空格) - 超时统一用
spring.redis.timeout(单位毫秒,建议 ≥2000,避免网络抖动触发重定向失败) - 连接池只对 Lettuce 生效:
spring.data.redis.lettuce.pool.max-idle=50;spring.redis.jedis.pool.*在 Spring Boot 3.0 中无效,除非你主动排除 Lettuce 并引入 Jedis - 绝对不要同时存在
spring.redis.host和spring.redis.cluster.nodes——前者会让 Spring Boot 自动降级为单机模式
依赖只留 spring-boot-starter-data-redis,别碰 Jedis
Spring Boot 3.0 的自动配置完全围绕 Lettuce 构建,Jedis 不仅不被支持,还会引发冲突。
- 检查
pom.xml:只保留spring-boot-starter-data-redis,它已内置lettuce-core - 如果误加了
jedis,启动时可能报NoUniqueBeanDefinitionException,或静默退化为单节点连接 - 真要换 Jedis?必须显式排除 Lettuce:
<exclusion><groupid>io.lettuce</groupid><artifactid>lettuce-core</artifactid></exclusion>,再手动配JedisConnectionFactory,但失去响应式支持和自动集群路由
最容易被忽略的是:集群健康 ≠ 配置正确。即使 application.yml 全对,只要任意一个节点防火墙未开、protected-mode yes 未关、或 cluster-enabled no,Spring Boot 启动时就会卡在连接池初始化,日志里只有反复重试和 timeout,而不是明确的配置错误提示。


















