超时问题主因是混淆spring.redis.timeout（命令执行超时）与lettuce.pool.max-wait（获取连接等待时间）；前者建议设5000ms防抖动，后者禁用-1、生产设2000–3000ms，且必须小于timeout值。

检查 spring.redis.timeout 和 lettuce.pool.max-wait 是否混淆

很多人把命令执行超时和连接获取超时当成一回事，结果调大 timeout 却发现 RedisCommandTimeoutException 还是照常抛。关键要分清：spring.redis.timeout 控制的是单条命令（如 GET、SET）的执行等待上限；而 lettuce.pool.max-wait 是从连接池拿连接时的阻塞等待时间。

• timeout: 5000 合理，低于 2000 容易在网络抖动时误判
• max-wait: -1 表示无限等待（慎用），生产环境建议设为 2000 或 3000
• 若日志里出现 Could not get a resource from the pool，优先查 max-wait 和连接池大小

确认 pingBeforeActivateConnection(true) 是否生效

Lettuce 默认不验证连接有效性，空闲连接被防火墙或 NAT 设备静默断开后，下次取出来直接发命令就会超时。光配 test-on-borrow=true 没用，因为 Lettuce 的默认实现不触发它。

Redis Skill - 高性能缓存管理

Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。

下载

• 必须通过自定义 LettuceConnectionFactory 启用：ClientOptions.builder().pingBeforeActivateConnection(true)
• 如果 Redis 配了密码，pingBeforeActivateConnection 会失败——确保 RedisURI 中已含 auth 信息（比如 redis://:password@host:6379）
• 搭配 topologyRefreshOptions 使用更稳妥，尤其在集群或哨兵场景下

验证 Redis 服务端是否开启 protected-mode no 和 bind 0.0.0.0

本地能连、部署后连不上？大概率是 Redis 服务端配置拦住了。Lettuce 报错里带 Unable to connect to xxx:6379，但错误根源不在客户端。

• 检查 redis.conf：确认 protected-mode no（否则只允许本地 loopback 连接）
• bind 行要么注释掉，要么显式写成 bind 0.0.0.0（别留 bind 127.0.0.1）
• 改完记得重启 Redis：sudo systemctl restart redis-server
• 用 redis-cli -h your_ip ping 在应用服务器上直连验证，绕过 Spring Boot

排查中间网络设备是否静默关闭空闲连接

即使服务端、客户端配置全对，云主机、K8s Service、SLB 或家用路由器都可能在 60–300 秒无流量后主动断开 TCP 连接。此时连接池里的连接仍是“活着”的引用，但底层 socket 已失效。

• 最直接证据：超时发生在首次请求之后的某次请求（比如启动后 2 分钟第一次读缓存正常，第 3 分钟开始报 RedisCommandTimeoutException）
• 解决方案不是加长超时，而是让连接保活：pingBeforeActivateConnection(true) + enablePeriodicRefresh（建议周期 ≤120 秒）
• 别依赖系统级 tcp_keepalive，Lettuce 的 PING 是应用层心跳，更可控

真正卡住人的地方，往往不是 timeout 值设多大，而是没意识到 Lettuce 的连接验证机制默认关闭，也没想到 Redis 服务端那两行配置能直接堵死所有远程连接。