mq Troubleshooting
RocketMQ 消息丢失排查方法
RocketMQ 消息发送成功但消费端收不到、疑似丢失时，用 mqadmin queryMsgById 追踪消息落盘与消费轨迹，consumerStatus 查消费组 offset，检查死信队列 %DLQ%<group> 是否堆积，并确认 Broker 是否开启同步刷盘和主从同步复制。
通过 mqadmin queryMsgById 追踪消息全链路，结合 consumerStatus 与死信队列定位是发送丢失、Broker 落盘丢失还是消费失败
Scenario
这篇文章解决什么问题
适用于“RocketMQ 消息丢失排查方法”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。通过 mqadmin queryMsgById 追踪消息全链路，结合 consumerStatus 与死信队列定位是发送丢失、Broker 落盘丢失还是消费失败
Symptoms
典型现象
- RocketMQ 消息发送成功但消费端收不到、疑似丢失时，用 mqadmin queryMsgById 追踪消息落盘与消费轨迹，consumerStatus 查消费组 offset，检查死信队列 %DLQ%<group> 是否堆积，并确认 Broker 是否开启同步刷盘和主从同步复制。
- 相关日志、命令或页面中反复出现 rocketmq、消息丢失、死信队列 等关键词。
- 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。
Before Debugging
排查前先确认
- 先确认是生产者、Broker 还是消费者的问题，不要在三层之间盲改。
- 保留消息 ID、offset 和故障时间点，方便和上下游日志对齐。
- 区分消息丢失（没投递成功）和消息积压（投递了但没消费），两者根因完全不同。
Root Causes
常见根因分层
消费者处理速度跟不上生产速度
消费逻辑慢、单线程拉取、批量大小不合理，会让 lag 持续增长，表现为积压而不是丢失。
- 看 lag 和消费 TPS
- 确认并发消费者数
- 排查消费逻辑是否有阻塞
分区或队列不均衡、rebalance 频繁
分区分配倾斜、消费者频繁上下线触发 rebalance，会让部分消费者空转、部分积压。
- 看分区分布和消费进度
- 确认 session timeout 和心跳
- 排查消费者重启原因
连接数或 channel 爆满、内存水位触发
连接泄漏、channel 不复用、Broker 内存超 watermark 触发 flow control，会让生产者被限流甚至断连。
- 统计连接和 channel 数
- 看 Broker 内存水位
- 确认是否触发 flow control
Diagnosis Path
分步诊断流程
1. 固定现场，避免追着变化状态跑
先记录故障时间、影响入口、完整错误和最近一次变更。RocketMQ 消息丢失排查方法 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。
- 截图或保存完整错误文本
- 记录请求域名/IP/端口/namespace/服务名
- 标出最近发布、配置、证书、镜像或依赖变更
mqadmin clusterList -n 127.0.0.1:9876
mqadmin consumerStatus -n 127.0.0.1:9876 -g my-group2. 在故障发生的同一位置复现
很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。
- 从报错服务所在机器执行测试
- 必要时加 Host、SNI、namespace 或代理参数
- 把成功路径和失败路径的输出并排比较
mqadmin consumerStatus -n 127.0.0.1:9876 -g my-group
mqadmin queryMsgById -n 127.0.0.1:9876 -i msgId
mqadmin queryMsgByOffset -n 127.0.0.1:9876 -t my-topic -b broker-a -q 0 -o 1003. 读取服务端证据，而不是只看客户端提示
客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。
- 使用 mqadmin clusterList 确认集群 Broker 状态、各节点角色与同步延迟是否正常
- 使用 mqadmin consumerStatus -g <group> 查看消费组 offset、消费 TPS 与堆积量
- 使用 mqadmin queryMsgById -i <msgId> 追踪消息从发送、存储到消费的全链路轨迹
mqadmin queryMsgById -n 127.0.0.1:9876 -i msgId
mqadmin queryMsgByOffset -n 127.0.0.1:9876 -t my-topic -b broker-a -q 0 -o 1004. 做最小修复并立即回归验证
每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。
- 使用 mqadmin queryMsgById -i <msgId> 追踪消息从发送、存储到消费的全链路轨迹
- 检查死信队列 %DLQ%<group> 是否有消息，确认消费失败次数达到 maxReconsumeTimes 后进入死信
- 排查发送端是否开启同步刷盘与主从同步复制，确认 Producer 是否收到 SEND_OK 且 FLUSH_DISK_TIMEOUT 等状态
mqadmin queryMsgById -n 127.0.0.1:9876 -i msgId
mqadmin queryMsgByOffset -n 127.0.0.1:9876 -t my-topic -b broker-a -q 0 -o 100Commands
排查命令与使用意图
命令 1
用于补充“RocketMQ 消息丢失排查方法”的排查证据链。mqadmin 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
mqadmin clusterList -n 127.0.0.1:9876命令 2
用于补充“RocketMQ 消息丢失排查方法”的排查证据链。mqadmin 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
mqadmin consumerStatus -n 127.0.0.1:9876 -g my-group命令 3
用于补充“RocketMQ 消息丢失排查方法”的排查证据链。mqadmin 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
mqadmin queryMsgById -n 127.0.0.1:9876 -i msgId命令 4
用于补充“RocketMQ 消息丢失排查方法”的排查证据链。mqadmin 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
mqadmin queryMsgByOffset -n 127.0.0.1:9876 -t my-topic -b broker-a -q 0 -o 100Risk Notes
容易踩坑的地方
- 不要直接清空队列丢弃消息来“解决”积压，会导致业务数据丢失，应先确认积压原因。
- 不要盲目重启 Broker，未持久化的消息和未确认的投递会丢失，重启前应确认同步状态。
- 不要在生产环境随意调整分区数，分区扩展后不能缩减，且会影响现有消息的顺序。
Verification
修复后怎么确认
- 原始故障现象已经消失，且使用同一入口重新测试 RocketMQ 消息丢失 能稳定成功。
- 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
- 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。
Prevention
后续预防
- 监控 lag、连接数和磁盘使用，而不是只看 Broker 是否存活，及时发现潜在问题。
- 消费者做幂等处理，避免重复消费导致数据错乱，特别是在重试和 rebalance 场景下。
- 设置合理的消息 TTL 和死信队列，防止异常消息无限堆积影响正常消息处理。
- 对关键消息链路做端到端监控，从生产到消费全链路追踪，快速定位问题节点。
常见问题
消息显示发送成功但消费端收不到怎么办？
先用 queryMsgById 确认 Broker 是否真正落盘，再查消费组 offset 是否被错误重置或订阅关系过滤表达式不匹配
消费失败的消息去了哪里？
重试达到 maxReconsumeTimes（默认 16）后会进入死信队列 %DLQ%<group>，需对死信队列做人工补偿或告警处理
Long-tail SEO
你可能正在搜索这些报错
下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。
- rocketmq 消息丢失
- rocketmq 消费失败
- rocketmq 死信队列
- rocketmq 消息查不到
- rocketmq queryMsgById
- rocketmq 消息丢失排查
Need More Help
这个问题还没完全解决？
把你的报错、环境和已经尝试过的步骤发给我，后续会优先补充到排障手册。