Lettuce 是目前 Spring Boot 2.x 及以上版本默认的 Redis 客户端，它使用 Netty 作为底层网络通信框架。Netty 为了提高性能大量使用堆外内存，也就是直接内存，这部分内存不受 JVM 堆管理，而是通过引用计数机制由程序手动释放。一旦使用 Lettuce 时连接创建、命令发送或响应处理环节出现引用计数遗漏，就会造成直接内存泄漏。本文将围绕启动阶段和运行阶段常见的内存持续增长现象，分析泄漏来源，并给出可以直接使用的排查命令和修复配置。

一、泄漏的典型表现与常见误判

使用 Lettuce 的应用出现内存泄漏时，最直观的表现是进程占用的物理内存持续上升，但通过 jmap 查看堆内存并没有明显增长。这是因为泄漏发生在堆外内存区域，不受 JVM 垃圾回收器管理。很多初学者只盯着堆内存曲线，发现一切正常后便误以为应用没有内存问题，结果物理内存不断被吃掉，最终触发操作系统的 OOM Killer。

另一个常见现象是控制台或日志中反复出现 io.netty.util.internal.OutOfDirectMemoryError，提示 failed to allocate 16777216 byte(s) of direct memory。这种报错说明 Netty 在申请直接内存时已经无法从操作系统获得足够空间。需要注意的是，它不是普通的 JVM 堆内存溢出，调大 -Xmx 参数并不能解决，因为堆内存和堆外内存是两套独立的分配区域。

新手容易把问题归因于 Redis 服务端，或者盲目调大 JVM 堆内存，但这两种做法都无法解决堆外内存泄漏。真正需要关注的是 Lettuce 客户端连接的创建次数与关闭行为。连接对象底层持有 Netty Channel 和 EventLoopGroup，如果只把连接引用置空而不调用关闭方法，这些底层资源不会主动释放。

二、从 Netty 引用计数看 Lettuce 泄漏根源

Netty 的 ByteBuf 使用引用计数来管理内存，当计数归零时才会被回收。Lettuce 在收发 Redis 命令时创建 ByteBuf，如果连接被强制关闭、线程中断或客户端异常退出，某些 ByteBuf 可能没有被 release。这类问题在高并发场景下更容易暴露，因为瞬时大量的命令请求会同时分配很多缓冲区，一旦释放路径出现疏漏，泄漏速度会非常快。

具体到 Lettuce，有两个容易忽视的泄漏点：一是 StatefulRedisConnection 没有关闭。Lettuce 的连接对象底层持有 Netty Channel 和 EventLoopGroup，如果只把连接引用置空而不调用 close 方法，Channel 不会主动释放。二是在高并发下重复创建 RedisClient 和连接，而没有使用连接池或共享连接，导致大量 Channel 和缓冲区同时存活。下面是一段典型的错误写法。

// 错误示例：每次请求都新建客户端和连接，且不关闭
RedisClient client = RedisClient.create("redis://127.0.0.1:6379");
StatefulRedisConnection<String, String> connection = client.connect();
RedisCommands<String, String> commands = connection.sync();
commands.set("key", "value");
// 方法结束后 connection 和 client 都没有关闭，直接内存会被一直占用

上面的代码在循环或并发场景下会迅速耗尽直接内存。即使不触发异常，也会让进程 RSS 不断增长。要理解这个问题，需要知道 RedisClient.create 每次都会创建新的 Netty 资源，而 client.connect() 又会建立新的 Channel。如果不执行 close()，这些资源只会在对象被 GC 回收时才有可能释放，但 Netty 的堆外内存并不完全依赖 GC，漏掉 release 就变成了永久占用。

三、定位 Lettuce 内存泄漏的实用方法

要确认是否发生直接内存泄漏，可以先观察 JVM 的堆外内存使用情况。JDK 提供的 jcmd 命令可以查看直接内存占用，执行方式如下。

jcmd <pid> VM.native_memory summary

注意输出中的 Direct Buffer 部分，如果它的值持续增大且不回落，就说明堆外内存存在泄漏嫌疑。还可以在启动参数中加入 Netty 的泄漏检测级别，让 Netty 在日志中输出泄漏对象创建时的调用栈，这是定位问题最有效的手段之一。

java -Dio.netty.leakDetection.level=paranoid -jar app.jar

paranoid 级别会产生一定性能开销，适合测试或灰度环境使用。日志中如果出现 LEAK: ByteBuf.release() was not called before it's garbage-collected，就能直接锁定未释放的缓冲区。也可以使用 -XX:MaxDirectMemorySize=512m 限制直接内存上限，让泄漏更快暴露，避免把物理内存耗尽。这样即使存在泄漏，也能在系统完全不可用前捕获到明确的错误信息。

四、可行的修复方案与配置建议

针对连接生命周期引起的泄漏，最直接的修复方式是复用连接或使用连接池。Spring Boot 项目可以通过 Lettuce 连接池配置减少连接频繁创建，下面是一份推荐配置。

spring:
  redis:
    host: 127.0.0.1
    port: 6379
    lettuce:
      pool:
        max-active: 16
        max-idle: 8
        min-idle: 2
        max-wait: 2000ms
      shutdown-timeout: 200ms

连接池会复用连接，降低 Channel 创建频率。如果业务代码手动创建 Lettuce 连接，务必在 finally 块中关闭连接和客户端。对于响应式 API，要注意使用 Disposable 或 doFinally 释放资源。下面给出使用 try-with-resources 的正确写法。

// 正确示例：使用 try-with-resources 自动关闭连接
try (RedisClient client = RedisClient.create("redis://127.0.0.1:6379")) {
    try (StatefulRedisConnection<String, String> connection = client.connect()) {
        RedisCommands<String, String> commands = connection.sync();
        commands.set("key", "value");
    }
}

另外，在应用启动时尽量只创建一个 RedisClient 或者使用 Spring 管理的 Bean，避免全局多处各自创建客户端。对于 Netty 原生资源，可以通过设置 io.netty.leakDetection.acquireAndReleaseOnly=true 简化检测，但生产环境不建议。升级 Lettuce 版本也能修复一些旧版本在异常路径下未释放 ByteBuf 的问题。

五、从架构层面避免类似问题

内存泄漏不仅是编码问题，也涉及客户端使用模式。对于高并发系统，建议将 Redis 操作封装为单例服务，统一管理连接池和关闭钩子。Spring Boot 已经帮我们完成了大部分工作，但在自定义 Lettuce 配置时要注意不要重复创建 LettuceConnectionFactory，否则会出现多套连接池和 EventLoopGroup，既浪费资源又增加泄漏概率。

同时，给 JVM 设置合理的直接内存上限是保护系统的必要手段。不要把 MaxDirectMemorySize 设置得和物理内存一样大，否则泄漏发生时系统可能在 OOM Killer 介入前就变得不可用。一般建议设置为堆内存的四分之一到二分之一，具体数值可以根据 Redis 命令的大小和并发量调整。

通过规范连接关闭、启用泄漏检测、限制直接内存并结合版本升级，Lettuce 相关的内存泄漏问题基本可以得到控制和修复。新手在排查时可以先判断堆内存是否增长，再观察直接内存和 Netty 日志，避免走弯路。只要理解了 Netty 的引用计数机制和 Lettuce 的连接生命周期，这类问题就不会再成为难以定位的疑难杂症。