tencent cloud

腾讯云分布式缓存数据库（兼容 Redis）

文档腾讯云分布式缓存数据库（兼容 Redis）命令参考Redis/Valkey 版有限支持命令

Redis/Valkey 版有限支持命令

Download
聚焦模式
字号
最后更新时间： 2026-08-11 11:12:00

概述

分布式缓存数据库集群架构通过 Proxy 代理层对外提供服务，隐藏了后端分片的真实网络拓扑。为兼容 Jedis Cluster、Lettuce Cluster 等智能客户端的连接发现机制，集群架构对部分 Cluster 命令做了有限支持——命令可正常执行，但返回的节点 IP 地址统一替换为实例的 Proxy VIP 地址（即实例的内网 IPv4 接入地址），而非后端各分片节点的真实内部 IP。这种设计确保智能客户端在连接发现阶段不会尝试直连后端分片（后端分片对客户端不可达），同时保持协议层的兼容性。

CLUSTER NODES

命令说明

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-5460
a1b2c3d4e5f6a7b8c9d0e1f2**************** 10.0.0.5:6379@16379 master - 0 1691234567000 2 connected 5461-10922
f0e1d2c3b4a5f6e7d8c9b0a1**************** 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 返回哈希槽到节点的映射关系，以数组形式输出每个槽位范围及其对应节点。
说明：
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（推荐替代）

命令说明

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，建议升级到较新版本。

相关文档

文档
说明
命令支持总览与集群架构限制说明
集群架构自定义命令（带 node-id 参数）使用方法
各命令族完整兼容性列表
Redis 6.x/7.x 和 Valkey 8.0 新增/变更命令
上一篇: DMC 支持命令列表下一篇: 自定义命令使用示例

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈