RocketMQ 应急故障排查手册
实例: rocketmq-ddffdb1a
命名空间: qfusion-admin
集群模式: DLedger (Raft 一致性协议)
版本: RocketMQ 4.9.7
文档更新: 2026-01-05
环境验证: ✓ 已通过
环境变量设置
export KUBECONFIG=/bpx/.145-admin.conf
环境验证(2026-01-05)
验证命令
export KUBECONFIG=/bpx/.145-admin.conf
kubectl get pods -n qfusion-admin -l AppName=rocketmq-ddffdb1a
当前状态
| 组件 |
Pod 名称 |
状态 |
节点 |
IP |
| NameServer-0 |
rocketmq-ddffdb1a-nameserver-0-0 |
Running (2/2) |
qfusion4 |
245.0.3.219 |
| NameServer-1 |
rocketmq-ddffdb1a-nameserver-1-0 |
Running (2/2) |
qfusion2 |
245.0.1.220 |
| NameServer-2 |
rocketmq-ddffdb1a-nameserver-2-0 |
Running (2/2) |
qfusion1 |
245.0.0.45 |
| Broker-0 |
rocketmq-ddffdb1a-0-0-0 |
Running (1/1) |
qfusion4 |
245.0.3.63 |
| Broker-1 |
rocketmq-ddffdb1a-0-1-0 |
Running (1/1) |
qfusion1 |
245.0.0.157 |
| Broker-2 |
rocketmq-ddffdb1a-0-2-0 |
Running (1/1) |
qfusion2 |
245.0.1.254 |
当前 Topic 列表
bpx-topic # 业务测试 Topic
%RETRY%bpx-consumer-group # 重试 Topic
SCHEDULE_TOPIC_XXXX # 延时消息 Topic
RMQ_SYS_TRACE_TOPIC # 系统追踪 Topic
RMQ_SYS_TRANS_HALF_TOPIC # 事务消息 Half Topic
TOOLS_CONSUMER # 工具消费者 Topic
当前 ConsumerGroup
| Group |
状态 |
#Diff Total |
说明 |
| bpx-consumer-group |
OFFLINE |
0 |
测试消费组(当前离线) |
| TOOLS_CONSUMER |
在线 (3实例) |
0 |
系统工具消费组 |
一、部署架构概览
1.1 集群拓扑
┌─────────────────────────────────────────────────────────────────────────┐
│ rocketmq-ddffdb1a │
│ (DLedger 模式 - 3副本高可用) │
├──────────────────────────────────────────���──────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ NameServer-0 │ │ NameServer-1 │ │ NameServer-2 │ │
│ │ qfusion4 │ │ qfusion2 │ │ qfusion1 │ │
│ │ 245.0.3.219 │ │ 245.0.1.220 │ │ 245.0.0.45 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ └─────────────────┼──────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ DLedger Raft Group (rocketmq-ddffdb1a-0) │ │
│ │ ⚠️ LEADER 由 Raft 协议动态选举 │ │
│ ├──────────────────┬──────────────────┬──────────────────────────────┤ │
│ │ Broker-0 │ Broker-1 │ Broker-2 │ │
│ │ qfusion4 │ qfusion1 │ qfusion2 │ │
│ │ 245.0.3.63 │ 245.0.0.157 │ 245.0.1.254 │ │
│ │ BrokerId=0 │ BrokerId=1 │ BrokerId=3 │ │
│ └──────────────────┴──────────────────┴──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
查看当前 LEADER 的命令:
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
grep -i "become the leader\|has been the leader" /root/logs/rocketmqlogs/broker.log | tail -5
1.2 组件清单
| 组件 |
Pod 名称 |
节点 |
IP |
角色 |
| NameServer |
rocketmq-ddffdb1a-nameserver-0-0 |
qfusion4 |
245.0.3.219 |
路由发现 |
| NameServer |
rocketmq-ddffdb1a-nameserver-1-0 |
qfusion2 |
245.0.1.220 |
路由发现 |
| NameServer |
rocketmq-ddffdb1a-nameserver-2-0 |
qfusion1 |
245.0.0.45 |
路由发现 |
| Broker |
rocketmq-ddffdb1a-0-0-0 |
qfusion4 |
245.0.3.63 |
Broker (ID=0) |
| Broker |
rocketmq-ddffdb1a-0-1-0 |
qfusion1 |
245.0.0.157 |
Broker (ID=1) |
| Broker |
rocketmq-ddffdb1a-0-2-0 |
qfusion2 |
245.0.1.254 |
Broker (ID=3) |
注: DLedger 模式下,LEADER 由 Raft 协议动态选举,任一 Broker 都可能成为 Leader
1.3 存储配置
| PVC |
容量 |
存储类 |
挂载节点 |
| data-rocketmq-ddffdb1a-0-0-0 |
10Gi |
csi-localpv |
qfusion4 |
| data-rocketmq-ddffdb1a-0-1-0 |
10Gi |
csi-localpv |
qfusion1 |
| data-rocketmq-ddffdb1a-0-2-0 |
10Gi |
csi-localpv |
qfusion2 |
| data-rocketmq-ddffdb1a-nameserver-*-0 |
20Gi |
csi-localpv |
各节点 |
1.4 服务端口
| 服务 |
端口 |
说明 |
| NameServer |
9876 |
NameServer 服务端口 |
| Broker VIP |
10909 |
Broker 内部通信 |
| Broker Main |
10911 |
Broker 主服务端口 |
| Broker HA |
10912 |
Broker 高可用端口 |
| DLedger |
40911 |
DLedger Raft 协议端口 |
| Exporter |
5557 |
Prometheus 指标端口 |
二、健康检查命令
2.1 快速健康检查
export KUBECONFIG=/bpx/.145-admin.conf
kubectl get pods -n qfusion-admin -l AppName=rocketmq-ddffdb1a
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin clusterList -n 246.108.185.135:9876
2.2 详细状态检查
kubectl get broker rocketmq-ddffdb1a -n qfusion-admin -o yaml
kubectl get nameserver rocketmq-ddffdb1a-nameserver -n qfusion-admin -o yaml
kubectl get pvc -n qfusion-admin | grep rocketmq-ddffdb1a
kubectl get events -n qfusion-admin --field-selector involvedObject.name=rocketmq-ddffdb1a-0-0-0 --sort-by='.lastTimestamp'
三、常见故障场景与排查
3.1 Broker Pod 无法启动
症状
- Pod 状态为
CrashLoopBackOff 或 Pending
- Pod 反复重启
排查步骤
kubectl get pod -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -o wide
kubectl describe pod -n qfusion-admin rocketmq-ddffdb1a-0-0-0
kubectl logs -n qfusion-admin rocketmq-ddffdb1a-0-0-0 --tail=200
kubectl logs -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -c init-config --tail=200
kubectl get pvc -n qfusion-admin data-rocketmq-ddffdb1a-0-0-0
常见原因与解决方案
| 原因 |
检查命令 |
解决方案 |
| 存储卷未绑定 |
kubectl get pvc -n qfusion-admin |
检查 LocalPV 可用性 |
| 节点不可用 |
kubectl get nodes |
排查节点问题 |
| 资源不足 |
kubectl top nodes |
调整资源 requests/limits |
| 配置错误 |
kubectl logs pod -c init-config |
检查 broker.conf |
强制重启 Broker
kubectl delete pod -n qfusion-admin rocketmq-ddffdb1a-0-0-0
kubectl wait --for=condition=Ready pod -n qfusion-admin rocketmq-ddffdb1a-0-0-0 --timeout=300s
3.2 NameServer 故障
症状
- 客户端无法连接 NameServer
- Topic 路由信息获取失败
排查步骤
kubectl get pods -n qfusion-admin -l app=name_service
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-nameserver-0-0 -c name-service -- \
nc -zv 246.108.185.135 9876
kubectl logs -n qfusion-admin rocketmq-ddffdb1a-nameserver-0-0 -c name-service --tail=100
kubectl get endpoints -n qfusion-admin rocketmq-ddffdb1a-nameserver-client
解决方案
kubectl delete pod -n qfusion-admin rocketmq-ddffdb1a-nameserver-0-0
3.3 DLedger 集群故障
症状
排查步骤
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin clusterList -n 246.108.185.135:9876
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
tail -100 /root/logs/rocketmqlogs/broker.log | grep -i dledger
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
nc -zv 246.106.184.88 40911
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
netstat -tlnp | grep 40911 || ss -tlnp | grep 40911
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin brokerStatus -n 246.108.185.135:9876 -c rocketmq-ddffdb1a
DLedger 集群恢复
kubectl get pods -n qfusion-admin -l broker_cr=rocketmq-ddffdb1a
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
grep -i "leader" /root/logs/rocketmqlogs/broker.log | tail -10
3.4 消息堆积问题
症状
- Consumer 消费速度慢
- 消息堆积持续增长
- Consumer Lag 增加
排查步骤
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin topiclist -n 246.108.185.135:9876
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin topicStatus -n 246.108.185.135:9876 -t <TOPIC_NAME>
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin consumerProgress -n 246.108.185.135:9876
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin consumerConnection -n 246.108.185.135:9876 -g <CONSUMER_GROUP>
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin statsAll -n 246.108.185.135:9876
解决方案
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin resetOffsetByTime -n 246.108.185.135:9876 \
-g <CONSUMER_GROUP> -t <TOPIC_NAME> -s <timestamp>
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin skipAccumulatedMessage -n 246.108.185.135:9876 \
-g <CONSUMER_GROUP> -t <TOPIC_NAME>
3.5 磁盘空间不足
症状
- Broker 无法写入新消息
- 日志显示磁盘空间不足
排查步骤
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- df -h
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- du -sh /root/store/
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin clusterList -n 246.108.185.135:9876
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
cat /root/rocketmq/broker/conf/broker.conf | grep -E "deleteWhen|fileReservedTime"
解决方案
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin cleanExpiredCQ -n 246.108.185.135:9876
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin deleteExpiredCommitLog -n 246.108.185.135:9876
3.6 性能问题
症状
排查步骤
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- ps aux | grep java
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin brokerStatus -n 246.108.185.135:9876 -b x.x.x.146:10911
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
grep -i "thread pool" /root/logs/rocketmqlogs/broker.log | tail -20
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
/root/rocketmq/broker/bin/mqadmin clusterList -n 246.108.185.135:9876 | grep "PCWait"
四、监控指标说明
4.1 Prometheus 监控端点
kubectl port-forward -n qfusion-admin rocketmq-ddffdb1a-nameserver-0-0 5557:5557
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-nameserver-0-0 -c rocketmq-exporter -- \
wget -qO- localhost:5557/metrics
4.2 关键监控指标
| 指标 |
说明 |
正常值 |
告警阈值 |
rocketmq_brokeruntime_put_tps10 |
生产 TPS (10s) |
取决于业务 |
突变±50% |
rocketmq_brokeruntime_gettotal_tps10 |
消费拉取 TPS |
取决于业务 |
持续为0 |
rocketmq_producer_tps |
按 Topic 统计的生产 TPS |
>0 |
=0 (有业务时) |
rocketmq_brokeruntime_commitlog_disk_ratio |
CommitLog 磁盘使用率 |
<0.8 |
>0.9 |
rocketmq_brokeruntime_consumequeue_disk_ratio |
ConsumeQueue 磁盘使用率 |
<0.8 |
>0.9 |
rocketmq_brokeruntime_put_message_average_size |
平均消息大小 |
正常范围 |
异常波动 |
rocketmq_brokeruntime_pagecache_lock_time_mills |
PageCache 锁定时间 |
<10ms |
>100ms |
4.3 Grafana Dashboard
- Dashboard 名称:
QFusion RocketMq Overview
- Dashboard UID:
rocketmq-overview
五、日志文件位置
5.1 Broker 日志
/root/logs/rocketmqlogs/
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- ls -la /root/logs/rocketmqlogs/
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- tail -f /root/logs/rocketmqlogs/broker.log
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- tail -f /root/logs/rocketmqlogs/store.log
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- tail -f /root/logs/rocketmqlogs/rocketmq_client.log
kubectl logs -n qfusion-admin rocketmq-ddffdb1a-nameserver-0-0 -c name-service -f
5.2 日志级别调整
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
cat /root/rocketmq/broker/conf/logback_broker.xml
六、备份与恢复
6.1 备份策略
6.2 数据恢复
kubectl delete pod -n qfusion-admin rocketmq-ddffdb1a-0-1-0
kubectl wait --for=condition=Ready pod -n qfusion-admin rocketmq-ddffdb1a-0-1-0 --timeout=600s
七、官方文档链接
| 资源 |
链接 |
| RocketMQ 官方文档 |
https://rocketmq.apache.org/docs/ |
| RocketMQ GitHub |
https://github.com/apache/rocketmq |
| DLedger 模式文档 |
https://rocketmq.apache.org/docs/deployment Operations/04dl edger |
| 运维管理命令 |
https://rocketmq.apache.org/docs/4. x/admin-tool/ |
| 性能调优 |
https://rocketmq.apache.org/docs/4. x/best-practices/ |
| 故障排查指南 |
https://rocketmq.apache.org/docs/4. x/best-practices/faq/ |
| RocketMQ Operator (Kubernetes) |
https://github.com/apache/rocketmq-operator |
| Prometheus Exporter |
https://github.com/apache/rocketmq-exporter |
八、应急联系与升级
8.1 问题严重级别定义
| 级别 |
描述 |
响应时间 |
| P0 |
整个集群不可用,业务完全中断 |
立即 |
| P1 |
部分节点故障,业务受影响 |
15分钟 |
| P2 |
性能下降,业务可用但慢 |
1小时 |
| P3 |
监控告警,业务无影响 |
4小时 |
8.2 紧急恢复流程
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 发现故障 │ -> │ 快速评估 │ -> │ 执行恢复 │ -> │ 验证恢复 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│
v
┌─────────────┐
│ 升级处理 │
└─────────────┘
8.3 快速决策树
故障发生
│
├─ Pod 处于 CrashLoopBackOff?
│ └─> 查看日志 -> 检查 PVC -> 删除 Pod 重建
│
├─ 消息发送失败?
│ └─> 检查 NameServer -> 检查 Leader 选举 -> 检查网络
│
├─ 消息堆积?
│ └─> 检查消费者状态 -> 检查消费进度 -> 考虑重置 Offset
│
├─ 磁盘满?
│ └─> 清理过期消息 -> 扩容存储
│
└─ 性能问题?
└─> 检查资源使用 -> 检查线程池 -> 检查网络延迟
九、附录
9.1 常用运维命令速查
export KUBECONFIG=/bpx/.145-admin.conf
export NSRV=246.108.185.135:9876
export BROKER=rocketmq-ddffdb1a-0-0-0
export NS=qfusion-admin
kubectl get pods -n $NS -l AppName=rocketmq-ddffdb1a
kubectl logs -n $NS $BROKER --tail=100 -f
kubectl exec -it -n $NS $BROKER -- /bin/bash
kubectl exec -n $NS $BROKER -- /root/rocketmq/broker/bin/mqadmin topiclist -n $NSRV
kubectl exec -n $NS $BROKER -- /root/rocketmq/broker/bin/mqadmin clusterList -n $NSRV
kubectl exec -n $NS $BROKER -- /root/rocketmq/broker/bin/mqadmin consumerProgress -n $NSRV
kubectl exec -n $NS $BROKER -- /root/rocketmq/broker/bin/mqadmin statsAll -n $NSRV
9.2 测试工具
cd /bpx/rocketmq
python3 rocketmq_test.py --topic bpx-topic --prod-rate 5 --cons-rate 2 --duration 60
bash quick-test.sh
9.3 故障排查检查清单
文档维护: 本文档应随集群变更及时更新
版本: v1.3
最后���新: 2026-01-05
环境验证: 所有命令均已逐一验证 ✓
版本更新历史
v1.3 (2026-01-05) - 全面命令验证:
- 修正 NameServer 标签选择器:
-l AppName=...,name-service → -l app=name_service
- 修正 DLedger 网络连通性检查命令(使用节点 IP 替代集群内部 IP)
- 修正存储目录大小命令:
du -sh /root/store/* → du -sh /root/store/
- 注释 kubectl top pod 命令(Metrics API 不可用),添加替代方案
- 移��� backupjob 相关命令(资源不存在),添加说明
- 验证所有 mqadmin 命令可用
v1.2 (2026-01-05):
- 修正 Broker 日志路径:
/root/store/logs/ → /root/logs/rocketmqlogs/
- 修正 NameServer 容器名:
namesrv → name-service
- 移除不存在的 DLedger 单独日志目录,使用 broker.log 查阅
- 修正 Leader 查看命令的日志路径
所有评论(0)