Spring Boot 3 中 Redis Cluster 密码必须配置为 spring.redis.cluster.password,spring.redis.password 在集群模式下被 Lettuce 客户端忽略,否则触发 NOAUTH 错误。

Spring Boot 3 中 Redis Cluster 密码必须用 spring.redis.cluster.password,配 spring.redis.password 完全无效——这是最常导致 NOAUTH Authentication required 错误的根本原因。
为什么 spring.redis.password 在集群模式下不生效
Spring Boot 2.0+ 的 Lettuce 集群客户端明确忽略 spring.redis.password,只读取 spring.redis.cluster.password 并将其作为 AUTH 命令参数透传给每个节点。即使你把 spring.redis.password 写对了,启动日志里也看不到报错,但第一次执行 set 或 get 就会抛出 RedisCommandExecutionException: NOAUTH 或静默超时。
常见错误现象包括:
- 应用能正常启动,
RedisConnectionFactory创建成功 - 调用
redisTemplate.opsForValue().set("k", "v")报NOAUTH Authentication required - 日志中出现
MOVED重定向失败或ReadTimeoutException,实则是认证被拒后连接中断
application.yml 中的正确写法(Spring Boot 3)
Spring Boot 3 默认使用 Lettuce,且要求 spring-data-redis ≥ 3.0.0(对应 Redis 7+ 兼容性),配置必须严格按层级书写:
spring:
redis:
cluster:
nodes: 127.0.0.1:7001,127.0.0.1:7002,127.0.0.1:7003
password: myclusterpass
max-redirects: 3
timeout: 2000
lettuce:
pool:
max-active: 8
max-idle: 8
min-idle: 0
注意要点:
-
password必须嵌套在cluster:下,不能提级到redis:层 - 所有集群节点的
requirepass值必须完全一致(大小写、空格、特殊字符) - 若用
redis://URL 格式写节点(如redis://127.0.0.1:7001),URL 中的密码会被忽略,仍以cluster.password为准 -
max-redirects建议显式设为 3(默认是 5),避免因认证失败节点引发无限重定向
Java 配置类中手动构造 RedisClusterConfiguration 的风险点
有人为了“可控”选择手写 @Configuration 类并 new RedisClusterConfiguration,这反而容易绕过 Spring Boot 自动装配的密码注入逻辑:
- 如果调用
redisClusterConfiguration.setPassword(password)但传入的是@Value("${spring.redis.password}"),那就又掉进单机配置陷阱 - Lettuce 要求密码必须通过
RedisClusterConfiguration的setPassword()设置,且该对象最终要交给LettuceClientConfigurationBuilderCustomizer或直接用于构建LettuceConnectionFactory - Spring Boot 3 推荐零配置优先,除非有定制拓扑发现或 SSL 等高级需求,否则不要手动 new 配置类
验证是否真正生效的简单方法
别只看启动日志有没有异常,要真连上去测认证状态:
- 用
redis-cli -c -h 127.0.0.1 -p 7001 -a myclusterpass手动连任意节点,执行cluster nodes看是否返回完整拓扑 - 在代码里加一行测试:
redisTemplate.execute((RedisCallback<string>) con -> con.ping())</string>,成功返回PONG才算通 - 检查
RedisConnectionFactory实例的类型:如果是LettuceConnectionFactory,且其clusterConfiguration字段的password属性非 null,说明配置已加载
最容易被忽略的是 Redis 服务端配置本身:集群各节点的 redis.conf 里必须同时存在 requirepass 和 masterauth(主从同步用),且值完全一致;漏掉 masterauth 会导致从节点无法认证主节点,整个集群状态异常,此时客户端哪怕密码配对了也会行为不稳定。


















