Redis PUBSUB SHARDNUMSUB 怎样统计分片频道订阅数

如果你使用 Redis 的分片发布订阅，想知道某个分片频道当前有多少订阅者，可以直接执行 PUBSUB SHARDNUMSUB。它接受一个或多个分片频道名，返回“频道名、订阅数”的成对结果；命令本身不会把普通频道的订阅者混进来。

官方地址：https://redis.io/docs/latest/commands/pubsub-shardnumsub/

本文只讨论分片频道订阅数的读取，不把它当成整个 Redis Cluster 的全局在线人数统计。集群场景尤其要注意：命令回复只反映当前节点的 Pub/Sub 上下文。

这个子命令解决的是什么问题

PUBSUB SHARDNUMSUB 自 Redis Open Source 7.0.0 起提供，用来返回指定分片频道的订阅数。它的查询复杂度是 O(N)，这里的 N 是本次传入的分片频道数量，因此适合一次查询一组明确的频道，不适合把无限增长的频道名列表塞进一次监控请求。

分片频道对应 SSUBSCRIBE / SPUBLISH 这条 Pub/Sub 路径。不要用普通的 PUBSUB NUMSUB 去推断分片频道状态，也不要因为结果是 0 就判断频道不存在：频道没有订阅者时，返回的订阅数就是 0。

怎样查询一个或多个分片频道

命令格式很短：PUBSUB SHARDNUMSUB [shardchannel ...]。单个频道用于快速定位，多频道调用适合一次采样相关频道。

# 查询一个分片频道，返回频道名和当前订阅数
redis-cli PUBSUB SHARDNUMSUB orders

# 一次查询多个分片频道，按传入顺序读取成对结果
redis-cli PUBSUB SHARDNUMSUB orders payments notifications

返回值不是键值对象，而是交替排列的数组：偶数位置是频道名，紧接着的奇数位置是订阅数。下面的内容是返回结构示意，重点是读取方式，不代表某个线上实例的实际人数。

orders
2
payments
1
notifications
0

因此，解析客户端返回值时应按两个元素一组处理。频道名是字符串，订阅数是整数；不要只取数组下标 1，也不要把整段数组直接当成“总订阅数”。

空参数和 Redis Cluster 要怎样理解

不传任何分片频道名是合法调用，但结果为空列表。它表达的是“这次没有指定查询对象”，不是“所有分片频道都没有订阅者”。如果监控代码允许空切片直接发请求，应该在业务层把空结果标成“无采样目标”，避免和某个频道返回 0 混淆。

在 Redis Cluster 中，PUBSUB 的回复只报告当前节点的 Pub/Sub 上下文。一次命令调用得到的 3，并不等于整个集群所有节点合计 3。想做集群级看板，需要在每个相关节点分别采样，然后在应用层按频道名汇总；这一步不是 SHARDNUMSUB 自动完成的。

接入监控时的最小实践

如果只是排查一个频道，直接用 redis-cli 即可。如果要接入定时采样，建议固定频道集合、限制采样频率，并把单节点结果标记上节点身份。这样既能保持 O(N) 成本可控，也能避免把节点局部数据误报成集群全局数据。

// 这个示例展示解析“频道名、订阅数”成对结果时的边界处理。
func pairsToMap(items []any) (map[string]int64, error) {
    // 空数组表示没有查询目标，不把它当成某个频道的 0。
    if len(items) == 0 {
        return map[string]int64{}, nil
    }
    // 返回结构必须成对出现，奇数长度说明客户端映射不完整。
    if len(items)%2 != 0 {
        return nil, fmt.Errorf("invalid SHARDNUMSUB reply length: %d", len(items))
    }
    result := make(map[string]int64, len(items)/2)
    for i := 0; i 

上面的函数只说明返回结构的处理边界；实际客户端可能把整数映射为 int、int64 或字符串，应按客户端 API 做适配。若服务运行在集群中，建议把节点地址与结果一起写入采样记录。

常见问题

SHARDNUMSUB 返回 0 是不是频道不存在？

不一定。它只说明当前命令上下文里该分片频道没有订阅者；频道是否曾经被创建、是否有生产者，并不由这个数字证明。

能不能用一次调用拿到整个集群的总订阅数？

不能直接拿到。集群回复只覆盖当前节点的 Pub/Sub 上下文，需要逐节点采样后由应用层汇总。

不传频道名能不能查询所有分片频道？

不能。空参数返回空列表，不会自动枚举频道；如果需要枚举目标，应由业务侧维护可控的频道清单。

小结

记住三点：第一，使用 SHARDNUMSUB 查询分片频道而不是普通频道；第二，返回值按“频道名、整数”成对读取；第三，集群结果是当前节点视角，空参数与订阅数为 0 也要区分。把这三个边界写进监控采样代码，结果就不会被误读。