最后更新：2026-10-29
适用场景：Spring Boot 3.5、Lettuce、Redis 连接失败或命令执行超时

同样是“Redis 超时”，有人连 TCP 都没有建立起来，有人已经连上，只是在等命令结果，还有人卡在客户端自己的等待队列。先把异常发生在哪一步看清，再去决定改网络、查慢命令，还是调整调用方式。

先读异常链，不急着改秒数

记录失败时刻、具体实例、Redis 地址和最内层异常。RedisConnectionFailureException 只是上层描述，后面可能跟着连接拒绝、建连超时、TLS 握手失败或认证错误。RedisCommandTimeoutException 则提示命令没有在客户端规定时间内完成，不能直接等同于“Redis 服务器执行了这么久”。

连接被拒绝时，先核对服务监听地址和端口；一直连不上时，再查 DNS、路由、防火墙和网络策略。若异常是 NOAUTH、WRONGPASS 或证书校验失败，说明排查重点已经不同。把它们统统改成十秒、三十秒超时，只会延后报错。

在应用所在网络做一次对照

在应用实例所在的机器或容器网络中，使用实际 Redis 地址测试。下面只是示意，不能直接拿开发电脑上的成功结果证明服务器也能连接：

redis-cli -h redis.internal -p 6379 PING

能收到 PONG，只证明这次连接和简单命令成功；收到认证错误，也至少说明请求已经到达了一个 Redis 服务。若部署要求 TLS，应使用它提供的 TLS 端口与可信 CA，例如：

redis-cli --tls --cacert /path/to/redis-ca.pem -h redis.internal -p 6380 PING

地址、端口和 CA 路径需替换。需要认证时按平台约定交互输入凭据，不要把密码写进文章示例、命令历史或错误日志，也不要为了通过测试关闭证书校验。

然后核对应用的有效配置。尤其留意环境变量、启动参数和 profile：本地连的是一套，生产实例实际连了另一套，这时“控制台能连”没有太大说明力。配置文件位置拿不准，可先看Spring Boot 配置文件怎么写。

分开配置建连等待与命令等待

Spring Boot 3.5 对应的属性包括 spring.data.redis.connect-timeout 和 spring.data.redis.timeout。下面的数值只用于说明两类配置，不是适用于所有业务的推荐值：

spring:
  data:
    redis:
      host: redis.internal
      port: 6379
      connect-timeout: 2s
      timeout: 3s

前者针对连接超时，后者针对读超时；具体客户端行为还要对照当前 Lettuce 版本和连接工厂设置。若项目自己声明了连接工厂或客户端配置，也要核对自动配置是否仍在生效。不要以为改了 YAML，就已经改变了正在使用的那个连接。

Spring Boot 3.5 属性文档列出了这两个属性。Spring Boot 2.x 的配置前缀与 3.x 不应混抄，升级项目要按实际版本查。

已经连上却偶发超时，继续查两边的等待

有权限时，可以查看少量慢日志条目：

SLOWLOG GET 20

这需要 Redis 管理权限或相应 ACL；托管服务按平台提供的入口查看即可。慢日志记录的是服务端执行命令的时间，不包含与客户端通信所花的时间。因此，慢日志为空，不能证明客户端不会超时。反过来，慢日志里某条命令耗时高，也要先对齐失败时段和实例，不能拿几小时前的记录解释当前请求。SLOWLOG GET 文档说明了记录的范围。

服务端重点看大集合操作、明显变大的返回值、长脚本、CPU 与持久化相关延迟。不要为了“找一个慢 key”在生产库直接跑 KEYS *；需要扫描时按数据规模和平台规范控制节奏。

客户端则看 CPU、GC、连接建立频率、连接池等待和事件循环是否被阻塞。使用 Lettuce 异步或响应式接口时，不能在其处理线程中塞入长时间阻塞操作。项目没有启用连接池，就不要先照抄一套池大小配置；共享连接、专用连接和阻塞命令的使用方式也要分清。

改完以后，用原来的失败场景复测

观察到的证据优先处理
连简单 PING 都失败地址、端口、DNS、TLS、认证与应用所在网络
服务端慢命令和超时同时出现命令复杂度、数据规模及服务端负载
服务端很快，应用仍超时客户端 CPU、GC、线程阻塞、连接等待与网络往返
只有少数实例失败对照实例配置、网络路径、部署版本和资源限制

确实需要等待更久的业务，可以在明确时延预算后调整超时，同时限制等待数量和重试次数。一次写入超时并不等于它没有在 Redis 执行；对计数、扣减等操作盲目重试，可能产生重复效果。

复测应保留原来的命令类型、数据规模与并发，比较超时次数、接口耗时和 Redis 延迟。只测一条 PING，就宣布复杂业务已经恢复，证据还不够。若问题同时伴随 Java CPU 升高，先保存客户端线程与资源证据，再对照接口 502/504 的排查链路。

参考资料

Spring Boot 3.5：Redis 配置属性
Redis：redis-cli
Redis：SLOWLOG GET
Redis：延迟问题排查

更新记录

2026-10-29：创建文章，区分连接、命令与客户端等待，并补充 TLS 和慢日志的排查边界。