Redis 作为高性能内存数据库，日常运维中经常会遇到客户端连接数异常升高、连接长时间不释放、命令执行缓慢等问题。CLIENT LIST 命令能够一次性列出当前 Redis 实例上所有已连接客户端的状态信息，是定位这些问题的第一手工具。它的输出是一组以换行分隔的记录，每条记录对应一个客户端连接，字段之间用空格分隔，包含了连接来源、空闲时间、当前执行命令、缓冲区占用等关键数据。理解这些字段的具体含义，并掌握在真实场景中筛选和分析它们的方法，可以大幅缩短连接异常和性能问题的排查时间。
一、CLIENT LIST 输出字段解析：从 addr 到 cmd 的完整含义
直接在 redis-cli 中执行 CLIENT LIST，会得到类似下面这样的输出。每一行代表一个客户端连接，字段之间用空格分隔。最常用的字段包括 id、addr、fd、name、age、idle、flags、db、sub、psub、multi、qbuf、qbuf-free、obl、oll、omem、events 和 cmd。id 是连接的唯一标识，可以配合 CLIENT KILL 使用；addr 是客户端的 IP 地址和端口，能够判断连接来源；fd 是文件描述符；name 是通过 CLIENT SETNAME 设置的连接名称，便于业务标识；age 表示连接已经建立了多少秒；idle 表示连接距离上一次执行命令已经空闲了多少秒。
flags 字段描述连接的状态属性，它的取值可以是 N（普通客户端）、M（主节点连接）、S（从节点连接）、O（监视模式客户端）、P（Pub/Sub 订阅客户端）、b（阻塞等待命令的客户端）、x（事务中的客户端）等。通过 flags 可以快速区分连接是否来自内部复制链路，还是来自外部业务订阅或阻塞命令。db 表示该客户端当前选中的数据库编号，sub 和 psub 分别表示订阅的普通频道和模式频道数量，multi 表示在 MULTI 事务中的命令队列长度，如果是 -1 则表示当前不在事务中。
redis-cli CLIENT LIST # 输出示例 id=3 addr=127.0.0.1:52314 fd=8 name= age=120 idle=0 flags=N db=0 sub=0 psub=0 multi=-1 qbuf=26 qbuf-free=20448 obl=0 oll=0 omem=0 events=r cmd=client id=14 addr=172.16.10.20:39122 fd=9 name=backend-service age=86400 idle=350 flags=N db=0 sub=0 psub=0 multi=-1 qbuf=0 qbuf-free=0 obl=0 oll=0 omem=0 events=r cmd=NULL
二、使用 CLIENT LIST 排查连接泄漏与异常客户端
连接泄漏是 Redis 运维中非常典型的问题。业务代码如果没有正确关闭连接池，或者连接池大小配置不合理，就会导致 Redis 上的连接数持续增长。通过 CLIENT LIST 输出中的 addr 字段，可以统计出每个来源 IP 建立了多少个连接。通常可以使用 grep 和 awk 等命令对输出进行聚合，例如统计每个 IP 的连接数，或者筛选出 idle 时间超过某个阈值的空闲连接。如果某台业务机器的连接数明显高于预期，很可能就是连接池配置错误或客户端未正常归还连接。
另一个常见场景是订阅连接泄漏。如果 flags 中包含 P，说明该连接处于 Pub/Sub 订阅状态。客户端订阅频道后，如果不再使用但连接没有关闭，Redis 会一直保留该连接，同时该连接会占用输出缓冲区。通过筛选 flags 中含有 P 的连接，再结合 age 和 idle 判断订阅是否仍然在被消费，可以找出废弃的订阅连接。对于长期 idle 且没有任何实际用途的连接，可以使用 CLIENT KILL 命令进行清理。下面这个命令会关闭所有来自 192.168.1.100 的客户端连接。
redis-cli CLIENT KILL ADDR 192.168.1.100:0
不过需要注意的是，CLIENT KILL 只能关闭单个连接或按地址、类型批量关闭，无法直接按照 idle 时间进行条件筛选。更精细的清理逻辑需要先从 CLIENT LIST 中解析出符合条件的 id，再逐条执行 CLIENT KILL。实际上，从 Redis 6.2 开始提供了 CLIENT KILL 的过滤选项，例如 LADDR、ID、TYPE、USER、SKIPME 等，可以组合使用，但直接按空闲时间过滤的场景仍然推荐先分析再精确关闭。
连接来源异常还可能和网络代理、健康检查等有关。有些部署会在 Redis 前面挂一层代理，代理的健康检查会频繁建立短连接，导致连接数虚高。此时可以通过 age 字段区分长连接和短连接。如果大量连接的 age 都很小，说明连接在快速创建和关闭，这通常是健康检查或连接泄露。如果 age 很大而 idle 很小，说明这些是正常的活跃长连接。通过这种对比，可以快速判断连接数升高的根本原因。
三、CLIENT LIST 的性能影响与更安全的替代方案
CLIENT LIST 命令本身会遍历当前所有客户端连接并收集状态信息，在连接数非常多的情况下，执行一次 CLIENT LIST 可能会消耗一定的 CPU 时间，并短暂占用 Redis 主线程。如果 Redis 实例已经处于高负载状态，频繁执行 CLIENT LIST 可能加重问题。因此在生产环境中，建议避免在性能紧张的实例上频繁执行该命令，可以间隔 10 秒到 30 秒执行一次，或者将输出重定向到文件中进行离线分析。
如果只是想查看当前连接的信息，而不是所有客户端，可以使用 CLIENT INFO 命令。CLIENT INFO 只返回当前执行命令的那个客户端自身的连接信息，开销极小，适合在脚本中确认自身连接状态。如果已经知道某个连接存在问题，可以结合 CLIENT GETNAME 和 CLIENT SETNAME 为连接设置业务标识，便于后续筛选。对于需要临时阻断客户端访问的场景，CLIENT PAUSE 可以暂停客户端命令执行，例如在主从切换或故障演练时保护数据一致性。
redis-cli CLIENT INFO # 输出示例 id=3 addr=127.0.0.1:52314 fd=8 name= age=120 idle=0 flags=N db=0 sub=0 psub=0 multi=-1 qbuf=26 qbuf-free=20448 obl=0 oll=0 omem=0 events=r cmd=client
有些监控系统会周期性采集 CLIENT LIST 并上报到时序数据库，这是常见的做法，但要注意采集频率不要过高。如果连接数达到几千甚至上万，CLIENT LIST 的输出会非常庞大，不仅 Redis 主线程有压力，网络传输和数据解析也会带来额外开销。此时可以考虑使用 CLIENT LIST TYPE NORMAL 等过滤条件来减少输出量，或者只采集关键指标，比如连接总数、每个 IP 的连接数、空闲连接数等。
四、结合 qbuf、obl、omem 分析慢客户端与输出缓冲区
CLIENT LIST 输出中的 qbuf、qbuf-free、obl、oll 和 omem 是分析客户端缓冲区问题的核心字段。qbuf 表示查询缓冲区的当前长度，即客户端发送过来但 Redis 尚未完整处理的命令字节数。qbuf-free 表示查询缓冲区剩余的可用空间。如果某个客户端的 qbuf 持续大于 0 或者接近缓冲区上限，说明该客户端可能在发送一个非常大的命令，例如巨型 KEYS 模式、大范围 SCAN 或者异常的数据写入，这会导致 Redis 主线程阻塞。
obl 表示输出缓冲区的普通客户端部分长度，oll 表示输出缓冲区对象列表长度，omem 表示输出缓冲区占用的内存字节数。当 Redis 向客户端返回大量数据，而客户端读取速度很慢时，输出缓冲区会不断堆积。典型场景包括使用 KEYS 命令返回海量键名、执行大范围的 MGET 或 SMEMBERS，以及 Pub/Sub 订阅客户端消费不及时。如果 omem 持续增长，甚至达到配置的输出缓冲区上限，Redis 会主动断开该客户端连接。通过观察这些字段，可以提前发现慢客户端。
redis-cli CLIENT LIST | grep -E "omem=[1-9]|obl=[1-9]"
上述命令可以快速过滤出输出缓冲区已经有积压的客户端。对于连续出现高 omem 的连接，需要检查客户端代码是否及时读取响应，是否存在同步阻塞读取但处理逻辑过慢的情况。除了应用侧优化，Redis 也提供了 client-output-buffer-limit 配置来限制普通客户端、从节点客户端和 Pub/Sub 客户端的输出缓冲区大小。当缓冲区超过限制时，Redis 会强制断开连接，避免个别慢客户端拖垮整个实例。
在实际排查中，CLIENT LIST 提供的字段并不是孤立的。比如一个连接既有高 idle 又有高 omem，很可能是订阅客户端长时间没有消费数据；一个连接 omem 正常但 qbuf 很大，则可能是正在接收超大请求。将 addr、age、idle、flags、qbuf、obl、omem 和 cmd 结合起来看，才能还原一个客户端连接的真实状态。生产环境中，建议将 CLIENT LIST 的采集和分析写成脚本，定期输出异常连接报告，这样可以更早发现连接泄漏、慢客户端和异常命令。
最后要提醒的是，CLIENT LIST 返回的信息是瞬时快照，连接状态随时可能变化。它适合作为排查线索，而不是精确的实时监控指标。若要持续观察连接趋势，应当结合监控系统的连接数曲线，并在异常时刻使用 CLIENT LIST 深入分析。正确使用 CLIENT LIST，能够让 Redis 运维从被动救火转向主动预防，这也是每个 Redis 使用团队都值得掌握的技能。
Redis CLIENT LIST客户端连接连接泄漏修改时间：2026-08-28 10:53:19