RocketMQ 消息订阅失败排查¶

一、现象¶

消费者订阅了 Topic，但收不到消息，或一直 Rebalance 报错。

二、排查清单¶

1. NameServer 连通性¶

生产者、消费者、Broker 都要能连 NameServer。
检查 namesrvAddr 配置是否一致。
telnet namesrv 9876 测试。

2. Topic 路由信息¶

mqadmin topicList -n namesrv:9876
mqadmin topicRoute -t TopicTest -n namesrv:9876

看 Topic 是否存在、Broker 是否注册了队列。

3. 消费组订阅关系¶

同一消费组内所有实例的 Topic 订阅必须一致，否则 Rebalance 失败。
代码里 subscribe("TopicA", "*")，所有实例都要订阅 TopicA。

consumer.subscribe("TopicA", "*");

常见错误

同一个消费组，实例 1 订阅 TopicA，实例 2 订阅 TopicB，会导致订阅不一致，消费异常。

4. Tag 过滤¶

consumer.subscribe("TopicA", "TagA || TagB");

如果消息只打了 TagC，就收不到。

5. 消费组名冲突¶

不同业务用了同一个 consumerGroup，会互相抢消息。

6. 顺序消息 / 广播消费模式¶

集群消费（默认）：一条消息只被组内一个实例消费。
广播消费：每个实例都收。

确认使用模式是否符合预期。

7. 消费位点（Offset）¶

如果之前订阅过且 offset 已经到末尾，新消息应该能收到。
如果 offset 文件损坏，可能从最旧或最新开始。
mqadmin consumerProgress -g group 查看堆积。

8. 权限 / ACL¶

开启 ACL 后，AccessKey 没有 Topic 的 sub 权限，会订阅失败。

9. Broker 状态¶

Broker 是否存活：mqadmin clusterList。
Broker 是否写满磁盘（达到阈值会拒绝写入）。
主从是否同步正常。

10. 客户端版本¶

Namesrv / Broker / 客户端版本差距过大，协议不兼容。
升级时先升 Broker，再升客户端。

三、常用排查命令¶

# 查看 Topic 路由
mqadmin topicRoute -t TopicTest -n namesrv:9876

# 查看消费进度
mqadmin consumerProgress -g CG_TEST -n namesrv:9876

# 查看连接
mqadmin consumerConnection -g CG_TEST -n namesrv:9876

# 查看 Broker 状态
mqadmin brokerStatus -b broker:10911

四、常见报错¶

报错	原因
`subscription not exist`	没订阅该 Topic
`consumer group not exist`	消费组没启动
`Rebalance failed`	订阅关系不一致
`no route info`	NameServer 上没有路由，Topic 没创建
`the consumer not online`	消费组所有实例都挂了

排查顺序

看日志：客户端日志 + Broker 日志。
看 NameServer 路由。
看消费组是否在线。
看订阅关系是否一致。
看网络和 ACL。