三、命令说明
CLUSTER NODES 返回当前集群的节点配置信息，输出为文本格式，每行代表一个节点。
四、返回值格式
每行节点信息的字段以空格分隔，结构如下：
<node-id> <ip:port@cport[,hostname]> <flags> <master-id> <ping-sent> <pong-recv> <config-epoch> <link-state> <slot> <slot> … <slot>
字段含义：
| 字段 | 说明 |
| node-id | 节点唯一标识（40字符十六进制字符串） |
| ip:port@cport | 节点客户端连接地址和集群总线端口 |
| flags | 节点标志，逗号分隔（如 myself,master、slave） |
| master-id | 若为副本节点，则为其主节点 ID；主节点显示为 – |
| ping-sent | 当前活跃 PING 消息发送的 Unix 毫秒时间戳，无挂起 PING 则为0 |
| pong-recv | 最后一次收到 PONG 的 Unix 毫秒时间戳 |
| config-epoch | 节点的配置纪元编号 |
| link-state | 集群总线连接状态：connected 或 disconnected |
| slot | 该节点负责的哈希槽编号或范围（如 0-5460），副本节点无此字段 |
五、执行示例
127.0.0.1:6379> CLUSTER NODES
返回值示例：
4c5bef442ee294489c57cdd1**************** 10.0.0.5:6379@16379 myself,master – 0 1691234567000 1 connected 0-5460a1b2c3d4e5f6a7b8c9d0e1f2**************** 10.0.0.5:6379@16379 master – 0 1691234567000 2 connected 5461-10922f0e1d2c3b4a5f6e7d8c9b0a1**************** 10.0.0.5:6379@16379 master – 0 1691234567000 3 connected 10923-16383
六、Flags 常见标志
| 标志 | 含义 |
| myself | 当前连接的节点自身 |
| master | 主节点 |
| slave | 副本节点 |
| fail? | 疑似故障状态（PFAIL），节点在多数主节点视图中不可达 |
| fail | 已确认故障状态（FAIL），集群已对该节点进行故障转移 |
| handshake | 握手阶段节点，尚未完成加入流程 |
| noaddr | 地址未知 |
| nofailover | 从节点进入 takeover 状态 |
| noflags | 无任何标志 |
八、命令说明
CLUSTER SLOTS 返回哈希槽到节点的映射关系，以数组形式输出每个槽位范围及其对应节点。
注意：说明：
注意：CLUSTER SLOTS 命令自 Redis 7.0.0 / Valkey 7.0 起已标记为弃用（deprecated），推荐使用 CLUSTER SHARDS 命令替代。详见下方 CLUSTER SHARDS 说明。
九、返回值格式
返回一个嵌套数组，每个元素代表一个槽位范围的映射信息：
| 序号 | 内容 | 说明 |
| 1 | 起始槽位 | 整数，槽位范围起始编号（含） |
| 2 | 结束槽位 | 整数，槽位范围结束编号（含） |
| 3 | 主节点信息 | 数组：[IP, 端口, 节点 ID] |
| 4 | 第一个副本信息 | 数组：[IP, 端口, 节点 ID] |
| 5+ | 后续副本信息 | 数组：[IP, 端口, 节点 ID]（若有多副本） |
十、执行示例
127.0.0.1:6379> CLUSTER SLOTS
返回值示例：
1) 1) (integer) 0 2) (integer) 5460 3) 1) "10.0.0.5" 2) (integer) 6379 3) "4c5bef442ee294489c57cdd1****************" 4) 1) "10.0.0.5" 2) (integer) 6379 3) "d4e5f6a7b8c9d0e1f2a3b4c5****************"2) 1) (integer) 5461 2) (integer) 10922 3) 1) "10.0.0.5" 2) (integer) 6379 3) "a1b2c3d4e5f6a7b8c9d0e1f2****************" 4) 1) "10.0.0.5" 2) (integer) 6379 3) "e5f6a7b8c9d0e1f2a3b4c5d6****************"3) 1) (integer) 10923 2) (integer) 16383 3) 1) "10.0.0.5" 2) (integer) 6379 3) "f0e1d2c3b4a5f6e7d8c9b0a1****************" 4) 1) "10.0.0.5" 2) (integer) 6379 3) "b8c9d0e1f2a3b4c5d6e7f8a9****************"
十二、命令说明
CLUSTER SHARDS 自 Redis 7.0.0 / Valkey 7.0 起引入，返回以分片（Shard）为维度的集群拓扑信息，是 CLUSTER SLOTS 的现代替代。相比 CLUSTER SLOTS，该命令返回结构更清晰，且包含更丰富的节点元数据。
版本要求：Redis 引擎7.0及以上版本，或 Valkey 引擎8.0及以上版本。
十三、返回值格式
返回一个分片数组，每个分片包含以下字段：
| 字段 | 说明 |
| slots | 该分片服务的槽位范围列表（起止整数对） |
| nodes | 节点信息数组，每个节点包含详细属性 |
节点属性：
| 属性 | 说明 |
| id | 节点唯一 ID |
| endpoint | 客户端连接端点（IP 或 hostname） |
| ip | 节点 IP 地址 |
| port | TCP 端口 |
| tls-port | TLS 端口（若启用） |
| role | 复制角色：master 或 replica |
| replication-offset | 复制偏移量 |
| health | 健康状态：online、failed 或 loading |
十四、执行示例
127.0.0.1:6379> CLUSTER SHARDS
返回值示例：
1) 1) "slots" 2) 1) (integer) 0 2) (integer) 5460 3) "nodes" 4) 1) 1) "id" 2) "4c5bef442ee294489c57cdd1****************" 3) "port" 4) (integer) 6379 5) "ip" 6) "10.0.0.5" 7) "endpoint" 8) "10.0.0.5" 9) "role" 10) "master" 11) "replication-offset" 12) (integer) 1234 13) "health" 14) "online" 2) 1) "id" 2) "d4e5f6a7b8c9d0e1f2a3b4c5****************" 3) "port" 4) (integer) 6379 5) "ip" 6) "10.0.0.5" 7) "endpoint" 8) "10.0.0.5" 9) "role" 10) "replica" 11) "replication-offset" 12) (integer) 1234 13) "health" 14) "online"
注意：说明：
注意：与 CLUSTER NODES 和 CLUSTER SLOTS 一致，所有节点的 ip 和 endpoint 字段均返回实例 Proxy VIP 地址。
十六、智能客户端行为
智能客户端（如 Jedis Cluster、Lettuce Cluster、redis-py Cluster）在初始化时会调用 CLUSTER SLOTS 或 CLUSTER SHARDS 获取拓扑信息，据此建立到各分片的直连。在分布式缓存数据库集群架构下，由于返回的 IP 均为 Proxy VIP，客户端实际建立的所有连接均指向 Proxy 代理层，Proxy 负责将请求路由到正确的分片。
这种方式对客户端透明，业务代码无需修改即可正常使用智能客户端库。
十七、与开源 Redis Cluster 的差异
| 对比项 | 开源 Redis Cluster | 分布式缓存数据库集群架构 |
| 返回节点 IP | 各分片真实 IP | 统一为 Proxy VIP 地址 |
| 客户端直连分片 | 支持 | 不支持（统一经过 Proxy） |
| -MOVED 重定向 | 指向目标分片 IP | 指向 Proxy VIP |
| -ASK 重定向 | 指向迁移目标 IP | 指向 Proxy VIP |
十八、版本与架构适用范围
| 命令 | Redis 引擎 | Valkey 引擎 | 架构要求 |
| CLUSTER NODES | 所有版本 | 8.0+ | 集群架构 |
| CLUSTER SLOTS | 所有版本（7.0+ 已弃用） | 8.0+（已弃用） | 集群架构 |
| CLUSTER SHARDS | 7.0+ | 8.0+ | 集群架构 |
十九、使用建议
·新应用接入：推荐使用 CLUSTER SHARDS（7.0+/Valkey 8.0+），获取更丰富的节点元数据和更清晰的返回结构。
·存量应用兼容：已使用 CLUSTER SLOTS 的客户端可继续使用，功能不受影响。
·管理与调试：CLUSTER NODES 适用于查看集群节点状态和拓扑概览，但请注意 IP 信息已被替换。
·客户端库选择：主流客户端库（Jedis 4.0+、Lettuce 6.0+、redis-py 4.0+）均已支持 CLUSTER SHARDS，建议升级到较新版本。
20、相关文档
| 文档 | 说明 |
| 命令参考概览 | 命令支持总览与集群架构限制说明 |
| 自定义命令使用示例 | 集群架构自定义命令（带 node-id 参数）使用方法 |
| 社区版命令支持概览 | 各命令族完整兼容性列表 |
| 大版本命令使用差异 | Redis 6.x/7.x 和 Valkey 8.0 新增/变更命令 |