如何在Spring Boot项目中集成Redis集群连接配置？

作者：袖梨 2026-08-24

Spring Boot 集成 Redis 集群无需手写配置类，只需正确引入 spring-boot-starter-data-redis 依赖、在 application.yml 中严格按格式配置 spring.redis.cluster.nodes（逗号分隔的 host:port 列表）、设置 password 和 max-redirects，并确保节点网络可达且集群拓扑健康。

Spring Boot 项目集成 Redis 集群，不需要手写 JedisCluster 或 RedisClusterConfiguration，最新 spring-boot-starter-data-redis 自带 Lettuce 原生支持集群模式，只要 YAML 配置写对、依赖齐、节点可达，就能自动初始化 RedisConnectionFactory 和 RedisTemplate。

application.yml 中 cluster.nodes 格式必须严格正确

这是最常踩的坑：节点列表不能带空格、不能用引号包裹、不能漏掉端口、不能混用 HTTP 协议前缀。

spring.redis.cluster.nodes 的值是逗号分隔的 host:port 字符串，例如：192.168.1.101:6379,192.168.1.102:6379,192.168.1.103:6379
如果用了密码，必须配 spring.redis.password（Lettuce 会自动应用到所有节点）
max-redirects 建议设为 3～5，太小会导致重定向失败报 ClusterRedirectException，太大可能掩盖拓扑异常
别配 spring.redis.host 或 spring.redis.port —— 它们和 cluster 模式冲突，存在时 Spring Boot 会优先走单机逻辑

依赖里不要同时引入 jedis 和 lettuce

Lettuce 是 Spring Boot 2.0+ 默认 Redis 客户端，线程安全、支持响应式、原生兼容集群；Jedis 是阻塞式客户端，需额外管理连接池，且 JedisCluster 不被 Spring Data Redis 自动装配。

只保留 spring-boot-starter-data-redis 即可（它已含 Lettuce）
显式引入 jedis 会导致类路径冲突，启动时抛 NoUniqueBeanDefinitionException 或静默降级为单机模式
如真要用 Jedis，必须排除 Lettuce：<exclusion><groupId>io.lettuce</groupId><artifactId>lettuce-core</artifactId></exclusion>，再手动配 JedisConnectionFactory

集群健康检查失败时先验证节点连通性

Spring Boot 启动时报 Unable to connect to Redis Cluster 或反复重试后超时，大概率不是配置问题，而是网络或 Redis 服务本身未就绪。

用 redis-cli -c -h 192.168.1.101 -p 6379 -a yourpass 手动连任一节点，执行 cluster nodes 看是否返回完整拓扑
确认所有节点都开启了 cluster-enabled yes，且 cluster-config-file 路径可写、内容未损坏
防火墙要放行所有节点间通信端口（不仅是客户端访问端口，还有集群总线端口 = 客户端端口 + 10000，如 6379 → 16379）
Lettuce 默认启用拓扑刷新，但首次发现失败后会缓存错误 30 秒，改配置后需重启应用，不能只 reload

多 Redis 集群场景下避免手动 Bean 冲突

一个应用要连多个 Redis 集群（比如订单集群 + 用户集群），最新 Starter 无法满足 —— 它只认一套 spring.redis.* 配置。

硬编码多个 @Bean 容易出错：比如两个 RedisTemplate 的序列化器不一致、连接工厂复用导致连接混用
推荐用 multi-redis-spring-boot-starter（Maven Central 可用），支持按前缀分组配置：redis.order.cluster.nodes、redis.user.cluster.nodes
它的核心机制是绕过 Spring Boot 的自动装配，用 @ConfigurationProperties 绑定自定义前缀，并为每个集群生成独立的 LettuceConnectionFactory 实例
注意：该 Starter 不兼容 spring.redis.* 全局配置，原有配置要迁移到新前缀下，否则会被忽略

真正卡住的地方往往不是 YAML 写法，而是集群节点之间握手失败、密码不一致、或 Lettuce 版本与 Redis 服务器版本不匹配（比如 Redis 7.2 需 Lettuce 6.3+）。建议先用 redis-cli --cluster check 验证集群状态，再动 Spring Boot 配置。