Redis CLIENT LIST 怎样按连接名筛选客户端
来源:17golang原创
时间:2026-11-16 18:59:24 101浏览 收藏
Redis 的 CLIENT LIST 可以列出当前连接,但它并不提供按连接名直接过滤的 NAME 参数。实用做法是:客户端建立连接后先用 CLIENT SETNAME 写入稳定名称,再读取 CLIENT LIST,在应用侧匹配每行里的 name 字段。
官方地址:https://redis.io/docs/latest/commands/client-list/
这样既不会把不存在的服务端语法当成 Redis 命令,也能保留连接的地址、空闲时间、数据库和客户端标志等排查信息。
先确认 CLIENT LIST 支持哪些过滤条件
当前命令语法是 CLIENT LIST [TYPE 。也就是说,Redis 服务端可以按客户端类型或连接 ID 缩小结果集,但不能直接写成 CLIENT LIST NAME worker-api。
# TYPE 和 ID 是服务端支持的过滤项;NAME 不是合法参数
redis-cli CLIENT LIST TYPE normal
redis-cli CLIENT LIST ID 42
# 下面的 NAME 写法会触发语法错误,不要把它当成可用命令
# redis-cli CLIENT LIST NAME worker-api
如果只需要查看单个已知连接,优先使用 ID;如果需要找一组由名称标记的连接,就读取列表后在客户端侧筛选。

用 CLIENT SETNAME 给连接写入可识别名称
CLIENT SETNAME connection-name 的作用是设置当前连接名称,复杂度为 O(1)。连接池场景下,名称最好包含服务、用途和实例标识,例如 order-api:cache:01,不要让所有连接都使用一个无法区分的短名称。
# 先给当前连接设置名称,名称会出现在 CLIENT LIST 的 name 字段
redis-cli CLIENT SETNAME order-api:cache:01
# 当前连接可用 GETNAME 读取回名称
redis-cli CLIENT GETNAME
需要注意,名称属于连接状态:连接断开、连接池重新创建物理连接后,必须由连接初始化钩子再次设置。名称为空时,列表中通常表现为 name=,不能把缺少名称误判成 Redis 没有该连接。
读取 CLIENT LIST 并按 name 字段过滤
命令返回多行文本,每行是空格分隔的字段,例如 id、addr、age、idle、db、flags 和 name。字段值可能包含转义形式,解析时不要简单地按空格切成固定下标。
import redis
def find_clients_by_name(client: redis.Redis, wanted: str) -> list[dict[str, str]]:
# CLIENT LIST 返回每个连接一行文本,按空白拆成 key=value 字段
rows = []
for line in client.execute_command("CLIENT", "LIST").splitlines():
fields = {}
for part in line.split():
# 忽略异常字段,避免一行脏数据让整个排查命令失败
if "=" not in part:
continue
key, value = part.split("=", 1)
fields[key] = value
# name 为空或缺失时都不匹配目标名称
if fields.get("name") == wanted:
rows.append(fields)
return rows
client = redis.Redis(host="127.0.0.1", port=6379, decode_responses=True)
matches = find_clients_by_name(client, "order-api:cache:01")
for item in matches:
# 只输出排查所需字段,避免把整行连接信息写入普通日志
print(item.get("id"), item.get("addr"), item.get("db"), item.get("idle"))
这段代码把“获取连接”和“按名称筛选”拆开,返回结果仍保留原始字段,便于后续根据 id 做进一步处理。生产环境中应通过受控的管理员连接执行,避免把连接列表暴露给普通业务请求。

名称筛选的三个边界
| 场景 | 现象 | 处理方式 |
|---|---|---|
| 连接未设置名称 | name 为空或没有有效值 | 在连接初始化时统一执行 CLIENT SETNAME |
| 多个连接复用同名 | 一次筛选返回多条记录 | 把名称设计为服务、用途、实例的组合,并继续查看 id 与 addr |
| 连接池重建连接 | 旧连接有名称,新连接没有名称 | 在每次新建物理连接后重新设置名称,不要只在进程启动时设置一次 |
如果名称中包含空格或特殊字符,优先选择不含空格的约定格式,并交给客户端库的参数编码处理。不要通过拼接未经处理的名称生成管理命令。
结论与常见问题
Redis CLIENT LIST 的正确思路是:用 TYPE 或 ID 做服务端过滤,用 CLIENT SETNAME 建立连接标签,再由客户端解析 name 字段完成按名筛选。这样得到的结果既能按业务名称定位,也能保留连接 ID 和地址用于后续排查。
CLIENT LIST 能不能直接按 NAME 过滤?
不能。官方语法提供的是 TYPE 和 ID;NAME 需要在客户端侧读取列表后比较。
为什么设置了名称却查不到?
常见原因是设置名称的连接与查询列表的连接不是同一条物理连接,或连接池重建后没有重新设置名称。
名称相同的连接怎样继续区分?
让筛选结果保留 id、addr、db 和 idle,再结合应用实例信息定位;不要只依赖名称。
-
311 收藏
-
483 收藏
-
379 收藏
-
172 收藏
-
464 收藏
-
239 收藏
-
331 收藏
-
421 收藏
-
184 收藏
-
209 收藏
-
406 收藏
-
135 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习