Spring Boot 集成 Redis 实战配置：从连接池到分布式锁的避坑指南

Redis 的 Spring 配置这件事，我在不少项目里都见过同一种现象：大家都以为在 yml 里塞几行 spring.data.redis.host、spring.data.redis.port 就算“配好了”，结果一上生产就暴露问题——缓存数据变成 \xac\xed\x00\x05 开头的乱码、连接池被打爆、分布式锁偶尔失效。Redis 的 Spring 配置从来不是“填个地址端口”那么简单，它是一条从连接工厂、序列化器、缓存管理器到分布式锁的完整链路，每一环都藏着坑。这篇博文我会从我实际踩过的角度出发，把这条链路从头到尾拆开讲一遍，适合所有用 Spring Boot 接 Redis 的开发者，尤其是刚把 RedisTemplate 跑通就以为万事大吉的新手。

先说个总的原则：配置 Redis 之前，得先搞清楚它在你项目里扮演什么角色。角色不同，配置的侧重点完全不一样。

1. 配置前先想清楚：你的 Redis 到底承载什么角色

很多人打开 yml 就开写，但在动手之前，建议先回答一个问题：Redis 在你的系统里到底是干嘛的？这个问题的答案，决定了你后面所有配置的走向。

1.1 三种典型角色，对应完全不同的配置重点

我把自己做过的项目按 Redis 的用途分成了三类，每一类的配置侧重点都不同：

一是纯缓存场景，比如热点接口数据的缓存、登录用户 Session 的缓存。这类场景最核心的问题是：序列化方式是否合理、TTL 是否设置得当、缓存穿透和雪崩怎么防。配置的重心在 RedisTemplate 的序列化器选择、CacheManager 的 TTL 策略上。

二是分布式锁场景，比如订单秒杀、库存扣减、定时任务的互斥执行。这类场景最核心的问题是：连接是否足够稳定、加锁和释放锁的操作是否原子、锁超时之后怎么办。配置的重心在连接池参数、锁实现方式（自己写还是用 Redisson）上。

三是会话共享或消息队列场景，比如多实例部署时把 Session 存到 Redis，或者用 Redis 做轻量级消息队列。这类场景最核心的问题是：序列化是否跨语言兼容、连接超时和重试策略是否合理。配置的重心在 RedisConnectionFactory 的超时参数和重试机制上。

只有把场景定下来，你才知道自己到底需要关注哪部分配置。我看过太多人不管三七二十一，先贴一套网上找的配置再说，结果在自己的业务形态下根本不合适。典型的例子是：明明只是单机缓存，却照搬了一套分布式锁专用的大连接池参数，白白浪费内存。

1.2 客户端选型：Lettuce 和 Jedis，谁是默认最稳的

Spring Boot 2.x 之后，默认的 Redis 客户端从 Jedis 换成了 Lettuce，这个变化很多人只当成了“依赖里自动带上了”，没真正理解背后的差异。

Jedis 是阻塞式 I/O，每个 Jedis 实例对应一个底层 Socket 连接。它的核心问题是：在多线程环境下，如果一个连接被多个线程共享，线程之间会互相阻塞；如果每个线程一条连接，又会导致连接数量居高不下。Spring Boot 1.x 时代用 Jedis，连接池参数调不好，高出并发下经常把 Redis 服务端的连接数打满。

Lettuce 基于 Netty 实现，采用的是共享连接模型：多个线程复用同一条连接，通过多路复用技术同时收发请求。这意味着同样的并发量下，Lettuce 需要的连接数远少于 Jedis。我在生产环境实测过，原来 Jedis 池要配 50 条连接才能扛住的流量，切到 Lettuce 后 20 条就稳稳的。那为什么 Lettuce 默认还不建议把连接池开得太大？因为连接本身就是资源，连接数越多，Redis 服务端的线程调度和内存开销越大。Lettuce 的池化参数，重点在于控制“高水位”，而不是追求连接数量。

所以除非你的项目是 Spring Boot 1.x 老版本没得选，否则建议直接用 Lettuce，不用刻意换回 Jedis。另外吐槽一句：网上很多教程还在让你配 spring.redis.jedis.pool 那一套参数，在 Spring Boot 3.x 里这些数据源前缀都已经换成了 spring.data.redis，照着老博客抄容易踩版本坑。

2. 连接池与连接工厂配置：稳定性的第一条生命线

不管你的 Redis 是单机、哨兵还是集群，连接层面的配置是所有后续逻辑的地基。连接配不稳，RedisTemplate 再优雅也是空中楼阁。

2.1 连接池参数到底怎么填，别直接抄网上的模板

Spring Boot 3.x 下，标准的 Redis 配置前缀长这样：

yaml复制spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      password: your_password
      timeout: 3s
      lettuce:
        pool:
          max-active: 8
          max-idle: 8
          min-idle: 0
          max-wait: -1ms

这几个参数是大家抄得最勤快的，但也是理解最浅的。逐个说清楚：

max-active：连接池最大连接数。这个值不是越大越好，而是应该按业务并发量估算。我常用的估算方法是：假设单次 Redis 操作耗时 t 毫秒，单连接每秒能处理大约 1000 / t 个请求，那么系统的 QPS 除以单连接吞吐量，再乘以一个冗余系数（一般 1.5~2 就行），就是比较合理的 max-active。举个例子，假设你的接口 QPS 是 1000，单次 Redis 操作 1ms，单连接吞吐约 1000 QPS，那理论上一条连接就够，但为了应对突发和慢查询，配 4~8 就非常充裕了。我看过有人把 max-active 配到 200，然后连着 Redis 的连接数居高不下，服务端内存报警，这就是典型的“没搞懂参数含义”。

max-idle：最大空闲连接数。这个参数控制的是连接池里最多保留多少条“闲置”连接。闲置连接太多，本身也是资源占用。一般让 max-idle 和 max-active 相同没毛病，避免频繁创建和销毁连接。

min-idle：最小空闲连接数。这是 Lettuce 连接池里最容易误解的参数——它只对长期存在的空闲连接有意义，控制的是连接池下限。可以把 min-idle 设成 0，因为频繁重连的开销远低于维护一堆空闲连接的内存开销。如果你的服务对“首请求延迟”敏感（比如内网网关调用 Redis 做鉴权），那 min-idle 可以设为 2~4，让连接预热存留。

max-wait：从连接池获取连接的最大等待时间。这个是排查“Redis 连接超时”类问题的关键。我建议一定不要图省事配成 -1ms（无限等待），否则当连接池耗尽时，你的接口不是快速失败，而是全部卡在等待队列里，最后表现为整条链路大面积超时，定位起来非常痛苦。线上建议配 200~500ms，让业务在连接池不够用时快速失败，配合降级逻辑，比无限等待好得多。

注意：spring.data.redis.timeout 是连接池获取不到连接时的报错时间，还是命令执行超时时间？实际上它是 Lettuce 的读写超时时间，控制单次命令执行的最长等待。这个参数建议根据你的业务耗时定，普通缓存场景 3s 够用，但如果是批量 pipeline 操作，建议放宽到 5s~10s。

2.2 多环境配置：密码、哨兵与集群的接入方式

配连接的时候，最容易出现事故的就是多环境混用。我的习惯是：yml 里只放本地和开发环境的占位符，生产环境的敏感信息一律用配置中心或环境变量注入。代码里不要出现任何明文密码。

单机模式很简单，上面那段就是。哨兵模式和集群模式则是另一套连法：

yaml复制spring:
  data:
    redis:
      timeout: 5s
      sentinel:
        master: mymaster
        nodes:
          - 192.168.1.10:26379
          - 192.168.1.11:26379

yaml复制spring:
  data:
    redis:
      timeout: 5s
      cluster:
        nodes:
          - 192.168.2.10:6379
          - 192.168.2.11:6379
          - 192.168.2.12:6379
      lettuce:
        cluster:
          refresh:
            adaptive: true
            period: 30s

集群模式下 adaptive: true 这行配置值得点一下：它开启了 Lettuce 的自适应拓扑刷新。集群的节点信息不是一成不变的，如果某个主节点挂了，哨兵或集群管理工具做了故障转移，Lettuce 需要拿到最新的节点拓扑。不开这个配置，就默认在连接失败时刷新，但刷新本身有延迟，期间请求会持续失败。开了之后，Lettuce 会周期性探测并刷新拓扑，减少故障转移窗口内的不可用时间。这种细节，文档里容易漏，但线上很关键。

我踩过一个相关的坑：当时用哨兵模式，主节点切换后连续报 RedisConnectionFailureException，排查半天发现就是没开拓扑刷新。从此之后凡是涉及哨兵和集群，这行配置必加。

3. RedisTemplate 序列化配置：乱码根源与解法

如果说连接池是地基，那序列化器就是管道本身。管线接得不对，数据进进出出全是问题。RedisTemplate 的序列化配置，是网上教程最容易敷衍过去的环节，也是线上乱码的第一大来源。

3.1 默认序列化器：JdkSerializationRedisSerializer 的三大坑

Spring Boot 在没做任何序列化配置时，RedisTemplate 的 key 和 value 默认采用 JdkSerializationRedisSerializer。这个默认选择让你“天然能跑”，但也埋了三个坑：

第一，数据可读性极差。存进 Redis 的数据是 \xac\xed\x00\x05t\x00\x0bkey-name 这种 JDK 序列化二进制格式，用 Redis 客户端肉眼根本没法看。你想排查问题，只能拿工具连上去 dump 一堆乱码。

第二，跨语言兼容性差。JDK 序列化只有 Java 能反序列化，如果系统里同时有 Python、Go 或 Node.js 服务需要共享这份数据，直接没得玩。我看到有些项目表面上是微服务架构，但缓存里全是 JDK 序列化的字节流，其他语言的服务根本没法消费。

第三，存储膨胀明显。JDK 序列化的体积通常是 JSON 序列化的 2~3 倍，明明一个 userId=123，能给你膨胀成几百字节。数据量一大，Redis 内存分分钟报警。

在 Spring Data Redis 里，如果要指定 RedisTemplate 的序列化方式，最标准的做法是自定义一个配置类，手动构造 RedisTemplate Bean。我下面的配置基本是生产级模板，直接抄了改一下就行：

java复制@Configuration
public class RedisConfig {

    @Bean
    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory) {
        RedisTemplate<String, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(connectionFactory);

        // key 采用 String 序列化，保证可读性
        StringRedisSerializer stringSerializer = new StringRedisSerializer();
        // value 采用 JSON 序列化，方便跨语言
        GenericJackson2JsonRedisSerializer jsonSerializer =
                new GenericJackson2JsonRedisSerializer();

        template.setKeySerializer(stringSerializer);
        template.setHashKeySerializer(stringSerializer);
        template.setValueSerializer(jsonSerializer);
        template.setHashValueSerializer(jsonSerializer);

        template.afterPropertiesSet();
        return template;
    }
}

这段代码里有几个细节值得展开：

• key 用 String：Redis 的 key 本质上是字节数组，但为了人在 Redis Desktop Manager 这类可视化管理工具里能直接看懂，key 必须用 StringRedisSerializer。这也是为什么我不建议 key 用什么复杂对象——key 最好永远是业务能读懂的字符串。

• value 用 GenericJackson2JsonRedisSerializer 而不是 Jackson2JsonRedisSerializer：这俩只差一个词，但含义天差地别。Jackson2JsonRedisSerializer(Object.class) 反序列化时无法知道对象的真实类型，要么强转报错，要么丢失类型信息。而 GenericJackson2JsonRedisSerializer 会在 JSON 里带上 @class 字段，比如 {"@class":"com.example.User","name":"xx"}，反序列化时就能还原真实类型。代价是多了个 @class 字段，增加了几个字节的存储，换来的是正确性和跨语言的兼容性，值。

• Hash 的 key 和 value 也要分别设置：很多人只设置了 KeySerializer 和 ValueSerializer，忘了 HashKeySerializer 和 HashValueSerializer，导致 opsForHash() 写入的数据还是走默认 JDK 序列化，绕了一圈又掉回坑里。代码里四个序列化器一定要全设。

序列化器选型我整理了一个对比表，方便你按需选择：

3.2 为什么推荐 StringRedisTemplate 做专用工具

除了自定义 RedisTemplate，Spring Data Redis 还内置了 StringRedisTemplate：它默认就是 key 和 value 都用 StringRedisSerializer。如果你的业务本质上是操作字符串（比如验证码、计数、接口幂等标记），直接用 StringRedisTemplate 更省心，连配置类都不用写，Spring Boot 自动装配里早就帮你准备好这个 Bean 了。

那什么时候用自定义的 RedisTemplate<String, Object>，什么时候用 StringRedisTemplate？我的经验是：能存字符串的尽量存字符串。序列化为 JSON 字符串再存，读取时再手动 JSON.parseObject，比依赖 RedisTemplate 的反序列化器更可控，出问题也好排查。特别是在团队里，别人看到你存进去的是一段可读的 JSON，比看到一堆二进制字节流友善太多。

不过如果你确实需要在应用层直接透出对象序列化的便捷性（比如缓存一张表里的用户对象，不想每次手动序列化），那就上自定义 RedisTemplate + GenericJackson2JsonRedisSerializer，这也是上面那段配置存在的意义。

实操心得：GenericJackson2JsonRedisSerializer 反序列化时如果目标类不在 ObjectMapper 的可见范围内，可能抛 InvalidDefinitionException。这通常发生在目标对象是内部类或者没默认构造函数的场景。解决办法是给目标类加无参构造器，或者把类提为顶层类。这个坑我在缓存一个带 @Builder 的 DTO 时踩过，@Builder 默认生成的构造器是包级私有的，GJackson 序列化器拿不到，导致反序列化瞬间报错。后来给 DTO 显式加了个 @NoArgsConstructor 才解决。

4. 把 Spring Cache 接到 Redis 上：缓存治理的正确打开方式

配置完 RedisTemplate，另一个高频操作是把 Spring Cache 的默认缓存实现从本地 ConcurrentHashMap 切到 Redis 上，这样 @Cacheable、@CacheEvict 这些注解才能真正共享到多实例环境里。这一节我们专门讲 CacheManager 的配置和缓存治理。

4.1 CacheManager 与 @Cacheable 的联动配置

Spring Cache 的抽象层在 Spring Boot 3.x 里默认用的是 RedisCacheManager。你往 RedisCacheManager 里注册多少个缓存名，就决定了 @Cacheable(cacheNames = "user") 能落多少套缓存。比较优雅的做法是给不同缓存名配置不同的 TTL，而不是所有缓存共用一套默认过期时间。

下面的配置是我常用的方案：注册三个缓存名，并给它们分别设置不同的 TTL。

java复制@Configuration
public class CacheConfig {

    @Bean
    public RedisCacheManagerBuilderCustomizer redisCacheManagerBuilderCustomizer() {
        return builder -> {
            Map<String, RedisCacheConfiguration> cacheConfigurations = new HashMap<>();
            // 基础数据缓存，10 分钟过期
            cacheConfigurations.put("user", RedisCacheConfiguration.defaultCacheConfig()
                    .entryTtl(Duration.ofMinutes(10))
                    .serializeKeysWith(RedisSerializationContext.SerializationPair
                            .fromSerializer(new StringRedisSerializer()))
                    .serializeValuesWith(RedisSerializationContext.SerializationPair
                            .fromSerializer(new GenericJackson2JsonRedisSerializer())));

            // 热点配置缓存，2 小时过期
            cacheConfigurations.put("config", RedisCacheConfiguration.defaultCacheConfig()
                    .entryTtl(Duration.ofHours(2))
                    .serializeValuesWith(RedisSerializationContext.SerializationPair
                            .fromSerializer(new GenericJackson2JsonRedisSerializer())));

            // 实时性要求高的临时缓存，30 秒过期
            cacheConfigurations.put("token", RedisCacheConfiguration.defaultCacheConfig()
                    .entryTtl(Duration.ofSeconds(30))
                    .serializeValuesWith(RedisSerializationContext.SerializationPair
                            .fromSerializer(new GenericJackson2JsonRedisSerializer())));
            builder.withInitialCacheConfigurations(cacheConfigurations);
        };
    }
}

这里用 RedisCacheManagerBuilderCustomizer 而不是直接重写 CacheManager Bean，是为了保证不破坏 Spring Boot 自动装配好的连接工厂。你在自定义配置类里重写 CacheManager 时，如果手工 new 出来的 RedisCacheManager 没绑好连接工厂，缓存会自动退化成空操作——写缓存没报错，但读缓存永远 miss。这种故障最磨人，因为业务不炸，只是性能越来越差。所以我强烈推荐用 customizer 的姿势，别手欠去重写整个 CacheManager Bean。

另外，Spring Cache 的缓存 key 默认有一种 SimpleKeyGenerator 生成的 key：如果你 @Cacheable 方法没有参数，key 是空串，有参数则拼接参数值。这种 key 可读性也不理想。稳妥做法是给缓存注解显式指定 key：

java复制@Cacheable(value = "user", key = "#userId")
public User getUserById(Long userId) {
    // ...
}

这样 key 就是 user::123 这种格式，用可视化工具一眼就能定位到具体数据行。

4.2 Redis 缓存治理：key 统一规范、TTL 差异化、三兄弟的防范

缓存配好了，还得学会“治”。我在线上碰到过不少缓存事故，总结下来，缓存治理要做三件事：

一是 key 命名规范。强烈建议全团队约定 业务域:业务名:参数 的三段式结构，比如 order:detail:10086、user:info:9527。好处是排查时能用 keys order:* 快速看全貌，避免冲突。这一点在 Spring Cache 里用 cacheName 天然契合：@Cacheable(value = "order:detail", key = "#orderId")。

二是差异化 TTL。缓存永远不要用统一的过期时间。热点数据短 TTL，基础数据长 TTL，临时校验码超短 TTL。为什么？假设所有缓存都是 10 分钟过期，到了过期时刻，所有 Redis 的 key 同时被淘汰。如果这时候来一波流量，所有的缓存全部拼命回源——这就是“雪崩”的雏形。合理的做法是给每个缓存域设置错开的过期时间，并在基础值上再加一个随机抖动，比如 10 分钟 + 随机 0~60 秒，让失效时间相互错开。

三是三兄弟的防范。缓存穿透（查询不存在的 key，导致每次都要打 DB）、缓存击穿（一个热点 key 过期瞬间，大量请求同时打到 DB）、缓存雪崩（大量 key 同时失效），这三兄弟在 Spring Cache 里光靠注解不好全部防住。我的经验是：

部分缓存穿透可以靠“缓存空值”解决：把不存在的查询结果也缓存一个短 TTL 的空对象，比如 60 秒。在 Spring Cache 里实现这个不复杂，但要在 @Cacheable 方法里对 null 做特殊处理，逻辑稍微有点绕。

更强的方案是引入本地热点缓存（Caffeine 之类），把极高频访问的 key 直接在 JVM 内内存命中，Redis 只在本地缓存 miss 时才兜底。这样即使 Redis 挂了几秒，热数据也能本地兜住。不过这只针对有明显热点 key 的系统才有意义，没有热点的情况下，引入两层缓存反而徒增复杂度。

实操心得：我不太建议新人一上来就给缓存配置上“布隆过滤器 + 多级缓存”全家桶。先把 Redis 缓存本身的 TTL 配置、key 规范、缓存空值这三件事做对，已经能规避掉绝大多数常见缓存事故。布隆过滤器适合 key 规模巨大且热点极分散的场景，那是另一套复杂度，等到真遇到再引入也不迟。

5. 分布式锁的落地配置与坑

如果你用 Redis 不只是做缓存，那接下来大概率会碰到分布式锁。锁的实现方案直接受连接配置影响，而且一些细节在没上生产前真的想不到。

5.1 自己用 RedisTemplate 实现锁，核心是原子性

用 RedisTemplate 手写分布式锁，网上一搜一大把，但版本之间有不少差异。最核心的加锁代码是这一行：

java复制setIfAbsent(key, value, timeout, TimeUnit.MILLISECONDS);

注意不能用先 setnx 再 expire 两步走。两步之间一旦应用挂掉，锁没有过期时间就永远不释放，后面所有拿锁的请求全部死锁。setIfAbsent 是在 Redis 底层用一条 SET 带 NX 和 EX 参数完成的原子操作，所以必须用它。

释放锁也是个容易出细节问题的地方：不能只 delete(key) 完事。如果有线程 A 拿到锁，执行时间超过了锁的超时时间，锁自动释放了；线程 B 又拿到了同一把锁；这时候 A 执行完毕回来，一个 delete 就把 B 的锁给删了。正确做法是先判断 value 是否是自己设置的标识（比如 UUID），确认是自己的锁再删除，而且这判断和删除也要原子化，用 Lua 脚本：

java复制private static final String UNLOCK_LUA =
        "if redis.call('get', KEYS[1]) == ARGV[1] then " +
        "return redis.call('del', KEYS[1]) " +
        "else return 0 " +
        "end";

public void unlock(String key, String requestId) {
    DefaultRedisScript<Long> script = new DefaultRedisScript<>(UNLOCK_LUA, Long.class);
    redisTemplate.execute(script, Collections.singletonList(key), requestId);
}

这段脚本我用了很多年，建议直接存下来。它解决的是“只能删自己的锁”这一个问题，光是这一条，就能防住一大类误删锁导致的重入问题。

手写锁的另一个问题是锁超时。如果业务执行时间预估不准，锁过了期限自动释放，其他线程就能进来，临界区就等于裸奔了。解决办法一是把锁超时设得足够长（一般建议是业务最大耗时的 3 倍以上）；二是自己实现“续期”线程，每隔一段时间检查锁还在不在自己手里，在的话就重置过期时间。我自己手写过续期逻辑，代码量不大但边界情况多，后来发现 Redisson 把这套东西封装好了，就转投 Redisson 了。如果你团队里允许引入第三方依赖，我更推荐 Redisson。

5.2 Redisson 是更省心的选择，但参数也得配对

Redisson 提供的分布式锁用起来体感好很多，主要是它内置了看门狗（Watchdog）续期机制：默认锁超时 30 秒，每 10 秒自动续一次期，业务用完释放锁，看门狗就不会再续。这个机制解决的就是“业务没执行完锁就到期”的问题，比手写的续期线程要成熟得多。

Redisson 的 Spring Boot 集成很简单，引入依赖并配置客户端即可：

kotlin复制implementation("org.redisson:redisson-spring-boot-starter:3.23.5")

yaml复制spring:
  data:
    redis:
      redisson:
        config: |
          singleServerConfig:
            address: redis://127.0.0.1:6379
            password: null
            connectionPoolSize: 8
            idleConnectionTimeout: 10000

但 Redisson 也不是无脑用就行。有几个参数我建议重视：

• lockWatchdogTimeout：看门狗超时时间，默认 30000ms，一般不用改，但如果业务确实有长任务，可以适当调到 60000ms 左右。
• connectionMinimumIdleSize：最小空闲连接数，默认是 32，这在低并发下有点浪费，建议调小到 8 或 16。
• retryAttempts：获取锁失败时的重试次数，默认 3 次，如果并发竞争激烈，可以适当调大，但注意这会增加阻塞时间。
• retryInterval：重试间隔，默认 1000ms，如果锁竞争极其频繁，可以调大到 2000ms。

另外，不要忽略 Redisson 的锁在 RedisException 时的降级策略。Redisson 在锁获取失败时默认抛 RLockException，如果业务里没有 try-catch 处理，异常会直接抛给前端，表现为“系统繁忙”。线上建议在锁外层包一层 try-catch，拿不到锁就快速失败，别让用户无限等待。

注意：主从或者哨兵架构下的分布式锁天然有“脑裂”风险。Redisson 的看门狗也好、锁本身也好，在没有特殊配置（如 redLock）的情况下不能保证绝对安全。如果业务对锁的安全性要求极高（扣库存、转账），建议要么选 Redisson 的 RedLock 模式（代价是性能下降），要么干脆用数据库唯一索引或者 ZooKeeper。我亲自经历过一次主从切换后两个线程同时拿到锁的事故，从那以后在资金类场景就不再完全信任 Redis 锁了。

6. 常见问题排查：连接超时、乱码、连接池告警

经历过前面这些配置，Redis 大概率能稳定跑一阵子了，但线上问题千奇百怪。这里分享三个我真正在项目里排查过的典型问题，每个都花费了不小功夫。

6.1 我踩过的坑和具体排查过程

问题一：客户端连不上 Redis，报大量 Connection refused 或 Read timed out

排查步骤我一般按这个顺序来：

第一步，先在本机用 redis-cli -h <host> -p <port> ping，看 Redis 服务能否正常返回 PONG，排除服务本身挂掉。有时候是 Redis 的 maxclients 被连接数打满，redis-cli 也连不进去，这时候要在 Redis 侧看 INFO clients 和 CONFIG GET maxclients。

第二步，如果是服务端连接数被打满，用 netstat -tan | grep :6379 | wc -l 看 ESTABLISHED 连接数。如果连接数远超 Redis 的 maxclients，那问题几乎可以确定是客户端连接池参数配得过大，或者连接没有正常归还。

第三步，检查是否配置了正确的 spring.data.redis.timeout。曾经有个案例，Lettuce 报错很慢，接口卡了十几秒才返回失败，最后发现 timeout 配的是 3000ms，不是 3s，命令执行超时全被放大。换个思路：timeout 的值应该是“网络往返 + Redis 命令执行 + 反序列化”的总耗时，在跨机房部署时尤其要把网络 RTT 算进去。

问题二：缓存数据在 Redis Desktop Manager 里全是一堆 \xac\xed 开头的乱码

这个症状基本是序列化器没配置导致的 100%。用可视化工具看还勉强能忍，但不光可读性差，还直接导致跨语言消费困难。我当时的处理是先确认代码里是否自定义了 RedisTemplate 的 Bean，确认方法很简单：在任意 Service 里打印 redisTemplate.getKeySerializer() 和 redisTemplate.getValueSerializer()，看是不是 JdkSerializationRedisSerializer。如果是，按第 3 节的方法重写 RedisTemplate 配置。

紧接着要处理存量垃圾数据：写一个清理脚本，扫描所有 key 前缀命中旧缓存域的 key，逐个确认后删除。当时发现有些 key 是 \xac\xed 开头的，有些 key 里嵌了业务字段——全乱了。清除之后，再重新写入就是可读的 JSON 了。

问题三：连接池告警 RedisCommandTimeoutException，但 Redis 压力很小

这个坑后来定位到是 Lettuce 的默认命令超时时间和业务执行时间不匹配。当时有个接口要批量查几千个 key，用的是 pipeline，单条命令很快，但整个 pipeline 在服务端排队执行，总耗时超过了默认的 60 秒——其实不是超时，是 pipeline 整体执行时间太长，把每条命令的超时时间消耗完了。解决方案有两种：一是对长 pipeline 场景单独调大 lettuce.shutdown-timeout 或者连接级 timeout；二是把大批量 pipeline 拆成小批量，每批几百个，降低单次提交的耗时。我当时用拆分方案，既避开了超时，也避免了 Redis 服务端长命令阻塞。

还有一次遇到的是连接池连接数持续增长、不释放。后来发现代码里 RedisTemplate 是从 @Autowired 注入的，但业务里还有手动 new RedisTemplate() 的地方，等于绕过 Spring 容器管理，连接工厂的池化参数完全没生效，每个线程都各自建连接。这个排查了半天，最后统一入口强制注入容器里的 RedisTemplate 解决。

6.2 检查清单速查表

我把自己平时排查 Redis 相关问题的流程整理成了下面这张速查表，遇到故障可以先对着过一遍：

最后一个小技巧：排查 Redis 连接问题时，redis-cli --latency 可以直接看到客户端到 Redis 的网络延迟。如果你调用链路过长，这个命令能立刻暴露是跨机房网络问题还是 Redis 本身性能问题。我曾经用它把一次“Redis 变慢”的锅从 Redis 身上摘下来，最后发现是虚拟机网络带宽打满了，这个工具在性能排查时是真的好用。

配置 Redis 这件事，说实话没有一套“万能模板”能直接适用所有项目。我在不同的业务形态里反复调整过连接池参数、序列化器、缓存 TTL，最后得出的体会是：配置要跟着业务形态走。连接池不用贪大，能扛住峰值并留有安全余量就行；序列化器尽量用可读且跨语言的 JSON；缓存 TTL 务必错峰；分布式锁能上 Redisson 就别自己手写。这套组合拳打下来，Redis 的稳定性会比大多数项目的默认配置高出一大截。如果你在配置过程中遇到了什么奇特的坑，欢迎交流，我这边还有一抽屉实战踩坑记录没写完。