Quarkus原生应用连接Redis Cluster遇「无法连接所有节点」故障排查

1. 开启集群拓扑自动刷新 #

quarkus-redis-client默认不会主动刷新集群节点列表，当节点故障或主从切换后，客户端仍持有旧节点信息，这是导致间歇性连接失败的核心原因之一。添加以下配置强制定期刷新：

quarkus.redis.cluster.topology-refresh=true
quarkus.redis.cluster.refresh-period=10s

• topology-refresh：启用自动拓扑刷新，让客户端及时感知集群节点变化
• refresh-period：设置拓扑刷新间隔，10s是适配大多数集群变动频率的合理值

2. 优化TLS环境下的连接与重试配置 #

TLS握手耗时更长，默认超时和重试策略无法覆盖临时网络波动或节点切换窗口期，调整参数如下：

quarkus.redis.connect-timeout=3s
quarkus.redis.timeout=5s
quarkus.redis.retry.max-retry=5
quarkus.redis.retry.delay=1s
quarkus.redis.retry.multiplier=2

• 延长connect-timeout给TLS握手留足时间
• 配置指数退避重试策略，应对临时网络故障或节点切换

3. 避免故障节点误判与快速驱逐 #

默认配置下，客户端可能会快速标记临时不可用的节点为永久故障，导致可用节点被耗尽。添加以下参数调整故障检测逻辑：

quarkus.redis.cluster.node-failure-detection-timeout=30s
quarkus.redis.cluster.max-redirects=5

• node-failure-detection-timeout：延长故障节点检测超时，避免误判临时波动的节点
• max-redirects：允许更多MOVED/ASK重定向，适配集群内部主从切换

4. 启用集群故障自动重试 #

确保客户端在遇到单节点故障或集群波动时自动重试，而非直接抛出全局错误：

quarkus.redis.retry.on-cluster-down=true
quarkus.redis.retry.on-node-failure=true

这两个参数开启后，客户端会自动重试到可用节点，避免单节点故障导致应用崩溃。

5. 原生镜像构建的特殊配置 #

如果是GraalVM原生镜像部署，需确保Redis客户端的反射和资源被正确处理，否则可能出现拓扑刷新或TLS连接失败。在src/main/resources/META-INF/native-image下创建reflect-config.json，添加：

[
  {
    "name": "io.vertx.redis.client.RedisClusterConnectOptions",
    "allDeclaredConstructors": true,
    "allDeclaredMethods": true,
    "allDeclaredFields": true
  },
  {
    "name": "io.vertx.redis.client.RedisConnectOptions",
    "allDeclaredConstructors": true,
    "allDeclaredMethods": true,
    "allDeclaredFields": true
  }
]

验证与排查 #

开启DEBUG日志查看节点刷新和连接失败的具体细节：

quarkus.log.category."io.vertx.redis".level=DEBUG
quarkus.log.category."io.quarkus.redis".level=DEBUG

上述配置对齐了Redisson默认的拓扑刷新和故障转移策略，解决后可移除业务层的@Retry注解，将重试逻辑交还给客户端处理。

内容的提问来源于stack exchange，提问作者Ezop