注意：说明：
注意：腾讯云通过 VPC IP 代理层统一屏蔽了 Redis 底层架构的复杂性（分片/高可用）。客户端访问腾讯云 Redis 实例时，无需配置集群或哨兵模式，而是像连接单节点 Redis 一样，直接访问腾讯云提供的统一入口（VPC IP）。
一、Lettuce 客户端设计缺陷
从 Spring Boot 2.x 开始，Lettuce 取代 Jedis 成为默认的 Redis 客户端。Lettuce 的默认配置在标准 Redis 部署中可行，但与腾讯云 VIP 的透明高可用架构存在兼容性鸿沟。必须通过强制启用 keepAlive 和 tcpUserTimeout 参数，使客户端连接池能及时响应后端切换，否则将导致故障转移后客户端持续不可用。具体信息，如下表所示。
| 故障类型 | 业务场景 | Lettuce 版本 | 核心问题 |
| 主动切换 | 兼容版本升级、代理版本升级、数据迁移 | Lettuce 6.1.05之前版本 | 默认不启用 TCP Keepalive（探测空闲连接是否存活），导致客户端连接池无法感知后端 VIP 的切换。旧连接仍被保留在池中，即使服务端已完成切换，客户端仍会持续使用无效连接抛出错误。 |
| 被动切换 | 物理机异常宕机 | Lettuce 6.3.0之前版本 | 未配置 TCP_USER_TIMEOUT 参数，当网络闪断或节点宕机时，操作系统可能长时间（默认 ≥ 30分钟）保持半开连接。客户端连接池无法及时回收这些"僵尸连接"，造成持续报错。 |
二、推荐配置方案（Lettuce 6.3.0+）
请确保你的项目 pom.xml 或 build.gradle 中 Lettuce 版本不低于6.3.0。从该版本开始，引入了 SocketOptions.KeepAliveOptions 和 SocketOptions.TcpUserTimeoutOptions 专属构建器。如果在低版本中使用此代码，会导致编译报错或找不到类的异常。在单机连接模式（Standalone）初始化 Redis 客户端时，请参考以下代码：
SocketOptions socketOptions = SocketOptions.builder() .keepAlive(SocketOptions.KeepAliveOptions.builder() // 两次 keepalive 间的时间间隔 .idle(Duration.ofSeconds(TCP_KEEPALIVE_TIME)) // 连接空闲多久开始 keepalive .interval(Duration.ofSeconds(TCP_KEEPALIVE_TIME/3)) // keepalive 几次之后断开连接 .count(3) // 是否开启保活连接 .enable() .build()) .tcpUserTimeout(SocketOptions.TcpUserTimeoutOptions.builder() // 解决服务端rst导致的长时间超时问题 .tcpUserTimeout(Duration.ofSeconds(TCP_USER_TIMEOUT)) .enable() .build()) // tcp 连接超时设置 .connectTimeout(Duration.ofMillis(redisConnectTimeout)) .build();