Redis ROLE 怎样查看当前实例的复制角色

想确认一台 Redis 当前是主节点、副本还是 Sentinel，先执行 ROLE，不要先解析配置文件。它是一个 O(1) 的只读查询命令，返回数组的第一个元素就是角色名；后面的字段会随着角色变化。master 重点看复制偏移量和副本列表，replica 重点看主节点地址、连接状态与复制偏移量，sentinel 则返回自己正在监视的主节点信息。

官方文档：https://redis.io/docs/latest/commands/role/

本文只解决“怎样读懂当前实例的复制角色”这一件事，不把 ROLE 当成故障转移命令，也不展开复制配置修改。

先用 ROLE 读取当前角色

最小命令只有一行：

# 连接目标实例并读取当前复制角色
redis-cli -h 127.0.0.1 -p 6379 ROLE

执行后先看第一项，而不是把整段数组当成固定列数：

1) "master"
2) (integer) 18420
3) 1
4) 1) 1) "10.0.0.12"
      2) "6379"
      3) "18391"

上面第一项是 master，第二项是主节点复制偏移量，第三项表示已连接的副本数量，后面是副本列表。不同角色返回的数据结构不一样，因此脚本必须先判断第一项，再读取后续字段。

master 返回值怎么读

当第一项是 master 时，返回结构可以按下面的关系理解：

主节点的偏移量不是业务键数量，也不是消息条数。它是复制流位置，适合和副本的偏移量放在一起比较，不能直接换算成“还有多少条数据”。如果只是想知道副本数量，读第三项就够了；如果要判断复制积压，则还需要读取副本条目中的偏移量。

# 只查看主节点的角色名、复制偏移量和副本数量
redis-cli ROLE | sed -n '1,4p'

# 连接指定实例；地址和端口应替换为本次排查目标
redis-cli -h 10.0.0.10 -p 6379 ROLE

如果自动化程序要做长期采集，建议保留原始数组和采集时间，再把角色专属字段转换成统一记录，而不是假设每次返回长度相同。

replica 返回值怎么读

副本的第一项是 slave 或 replica，具体显示形式取决于 Redis 版本和客户端呈现；程序判断时应兼容这两种角色字符串。后续字段通常包含主节点 host、主节点 port、连接状态、最近一次接收的主节点偏移量、当前副本偏移量以及复制积压相关信息。

# 读取副本角色；先观察第一项，再按字段含义解析后续数组
redis-cli -h 10.0.0.12 -p 6379 ROLE

# 用原始 RESP 风格输出，便于排查脚本读取的是哪一列
redis-cli --raw -h 10.0.0.12 -p 6379 ROLE

最有用的判断顺序是：

1. 第一项确认它确实是副本。
2. 主节点 host 和 port 确认复制目标是否指向预期实例。
3. 连接状态确认复制链路是否处于可用状态。
4. 比较主节点与副本偏移量，判断是否存在复制滞后。

不要只看到副本角色就认为同步正常。副本可能仍然保留角色，但连接状态已经断开；也不要把一次采集的偏移差直接当成稳定延迟，复制流会继续增长，应该在连续采样中观察差值是否持续扩大。

sentinel 返回值表示什么

当第一项是 sentinel 时，后续内容描述 Sentinel 当前监视的主节点名称和地址信息。它回答的是“这个 Sentinel 监视了哪些主节点”，不是“当前 Redis 数据实例保存了多少数据”。

# 在 Sentinel 端读取它当前监视的主节点信息
redis-cli -h 10.0.0.20 -p 26379 ROLE

因此，排查时要先确认连接的端口和实例类型。把 Sentinel 的返回值当成 master 的返回值解析，会让字段含义全部错位。

把 ROLE 用进排查脚本时的边界

如果只是人工排查，redis-cli ROLE 足够。如果要给监控或发布脚本使用，可以只把角色与少量关键字段输出成稳定文本：

# 先取角色名；空输出或连接失败时直接返回错误
role="$(redis-cli --raw ROLE 2>/dev/null | sed -n '1p')"
if [ -z "$role" ]; then
  # 连接失败不能伪装成 unknown，否则会掩盖实例不可达
  echo "ROLE 查询失败" >&2
  exit 1
fi

case "$role" in
  master|replica|slave|sentinel)
    # 只输出受支持的角色，完整原始结果另行保存
    echo "当前角色：$role"
    ;;
  *)
    # 新版本或代理返回新角色时保留原值，避免静默误判
    echo "未识别角色：$role" >&2
    exit 2
    ;;
esac

这类脚本只做角色识别，不应该自动执行 REPLICAOF、故障转移或配置修改。角色查询是观察动作，配置变更是另一条需要审批和回滚设计的运维路径。

另外，ROLE 的权限属于管理类命令。若 ACL 用户没有执行权限，脚本应把权限错误记录为失败，而不是根据空结果猜测角色。

集群场景为什么不能只看一台实例

在 Redis Cluster 中，ROLE 仍然只反映当前连接节点的角色和复制上下文。它不是全局拓扑清单，也不会代替 CLUSTER NODES 或 CLUSTER SHARDS。如果要做集群级巡检，应先枚举目标节点，再对每个节点分别读取 ROLE，最后将节点地址作为记录主键。

# 读取当前节点的角色；集群全局判断需要对节点逐一采集
redis-cli -c -h 10.0.0.10 -p 6379 ROLE

# 查看集群节点清单；这一步用于发现节点，不替代 ROLE 的角色字段
redis-cli -c -h 10.0.0.10 -p 6379 CLUSTER NODES

把“当前节点是 master”误写成“整个集群只有 master”是最常见的范围错误。先区分实例级事实与集群级事实，再决定采集范围。

常见误区与快速结论

可以把最终结论压缩为一句话：ROLE 负责回答“当前实例是谁”，第一项决定解析分支，后续字段负责补充复制关系；要判断集群全貌或执行切换，还需要使用对应的拓扑与运维命令。

相关问题

ROLE 能判断副本是否完全追平吗？

它能提供连接状态和复制偏移量等判断依据，但一次返回不能证明持续追平。应结合连续采样和业务可接受的滞后阈值。

为什么不直接读取 INFO replication？

INFO replication 适合读取更完整的复制统计；ROLE 更适合做一次轻量角色识别。两者是互补关系，不是互相替代。

ROLE 可以触发主从切换吗？

不可以。ROLE 是查询命令。切换、复制配置和 Sentinel 故障转移应使用各自的运维流程，并在执行前明确影响范围。