Redis CLIENT LIST TYPE 怎样筛选连接类型

Redis 的 CLIENT LIST 默认返回客户端连接的状态和统计信息；如果只想排查某一种连接，可以加上 TYPE 过滤器。它支持 normal、master、replica 和 pubsub 四种类型，过滤发生在 Redis 返回客户端列表时，而不是把连接名称模糊匹配成某一类。

需要按连接类别筛选时，给 CLIENT LIST 追加 TYPE 和类型值即可；如果还要定位少数连接，再组合 ID。空结果和命令错误要分开记录。

官方地址：https://redis.io/docs/latest/commands/client-list/

本文只讨论查看连接，不执行断开连接或修改服务端配置。需要留意的是，示例中的地址、客户端 ID 和字段值都是说明用的占位内容，不代表某个线上实例的真实输出。

先分清：CLIENT LIST 返回的是连接记录

CLIENT LIST 返回一组文本格式的客户端记录，每条记录包含连接 ID、地址、连接名称、空闲时间、当前数据库、订阅数以及客户端标志等字段。它适合回答“现在有哪些连接、连接来自哪里、是否处于订阅状态”这类排查问题。

TYPE 过滤的是 Redis 识别出的客户端类型，不是 name 字段，也不是客户端发送的最后一条命令。比如，给连接设置了名称 worker-a，不会因此让它自动变成 master 或 replica 类型。

TYPE 的四种值分别代表什么

normal 是普通客户端连接，应用请求、运维工具和大多数未处在特殊复制或发布订阅角色中的连接通常落在这一类。master 和 replica 用来区分复制相关的客户端角色；pubsub 则用于发布订阅连接。

这里的分类服务于连接排查，不应被当成业务用户、连接池名称或权限角色。尤其是 pubsub 连接可能长期保持打开状态，排查连接数量时应把它和普通请求连接分开看。

只按连接类型筛选

最直接的用法是在 CLIENT LIST 后面加 TYPE 和类型值。下面的命令以普通客户端为例：

# 只查看 Redis 当前识别为普通客户端的连接
redis-cli CLIENT LIST TYPE normal

# 只查看发布订阅连接；空结果表示当前没有匹配记录
redis-cli CLIENT LIST TYPE pubsub

命令返回的每行通常由空格分隔的 key=value 字段组成。读取时应该按字段名解析，而不要把“第几个空格字段”写死，因为不同 Redis 版本可能追加字段。字段值中如果出现转义内容，也不能简单地按业务名称猜测含义。

官方文档还说明，TYPE 的取值是固定集合；拼写错误不会变成“返回全部”，而会得到语法错误。排查脚本应把命令错误和合法但为空的结果分开处理。

TYPE 和 ID 可以组合使用

当类型过滤后仍有多条记录，可以先从结果中的 id 字段挑出目标连接，再通过 ID 缩小查询范围。ID 接受一个或多个客户端 ID，组合过滤时需要同时满足给出的条件。

# 先按类型筛选，示例中的 42 和 57 只是占位客户端 ID
redis-cli CLIENT LIST TYPE normal

# 在普通客户端范围内只取指定 ID，减少后续人工阅读量
redis-cli CLIENT LIST TYPE normal ID 42 57

这个组合适合“先发现连接类别，再定位少数连接”的人工排查。它不等于锁定连接：客户端可能在两次查询之间断开并重连，新的连接会得到新的 ID。需要持续观察时，应把查询时间、连接 ID 和关键字段一起记录，而不是只保存一行文本。

脚本读取时处理空结果和错误

如果把查询接入巡检脚本，至少要区分三种情况：命令执行失败、命令成功但没有匹配连接、命令成功并返回多条连接。下面的 Python 示例只展示解析和分类思路，不连接或操作任何真实 Redis 实例。

def parse_client_list(text: str) -> list[dict[str, str]]:
    # 每行是一条连接记录，字段采用 key=value 形式。
    records = []
    for line in text.splitlines():
        fields = {}
        for token in line.split():
            # 没有等号的片段不当作字段，避免解析异常污染结果。
            if "=" not in token:
                continue
            key, value = token.split("=", 1)
            fields[key] = value
        if fields:
            records.append(fields)
    return records

def classify_result(raw_text: str, command_error: Exception | None = None) -> str:
    # 命令错误和“没有匹配连接”必须分开记录。
    if command_error is not None:
        return "command-error"
    if not raw_text.strip():
        return "empty-match"
    return "matched"

# 调用方应显式传入客户端返回文本，并保留原始错误信息。
result = parse_client_list(raw_text)
state = classify_result(raw_text, command_error)

真实客户端库可能直接把结果映射成结构化对象，也可能仍然返回文本。无论哪种形式，都应保留连接 ID、地址、名称和类型判断所需字段。权限不足、网络断开或 Redis 返回语法错误都属于命令错误，不能误报成“当前没有连接”。

排查连接时的几个边界

第一，CLIENT LIST 的时间复杂度与客户端连接数量相关，不能在高频请求路径里无条件轮询。第二，结果是某个时刻的观察值，不是连接生命周期的稳定快照；如果要做趋势分析，应在应用层按固定周期采样并聚合。

第三，CLIENT LIST 能告诉你连接记录及其状态字段，但不能单独证明某个业务请求正在运行，也不能替代应用日志、连接池指标或复制状态命令。第四，执行该命令需要相应权限，生产环境应使用最小权限的运维账号，并避免把返回中的地址、用户名或连接名称直接暴露到公共日志。

选择表与常见问题

TYPE 能按客户端名称筛选吗？

不能。TYPE 只接受文档规定的客户端类型；如果要按名称排查，应读取返回记录中的 name 字段并在应用侧过滤，不能把名称作为 TYPE 值。

TYPE normal 返回空结果是不是 Redis 故障？

不一定。它可能表示当前没有匹配的普通连接，也可能是脚本没有正确读取结果。只有在命令本身返回错误时，才应按执行失败处理。

ID 可以长期代表同一个应用实例吗？

不能把它当成永久身份。客户端断开后重新连接会得到新的连接记录，持续追踪应结合地址、名称、采样时间和应用侧标识。

实际使用时，我会先用 TYPE 缩小连接类别，再用字段和 ID 做一次性定位，最后把周期采样交给指标系统。这样可以避免把客户端类型、业务身份和连接时刻混成一个概念。