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

# 检查所有 Pod 状态
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 详细状态检查

# 查看 Broker 资源状态
kubectl get broker rocketmq-ddffdb1a -n qfusion-admin -o yaml

# 查看 NameServer 资源状态
kubectl get nameserver rocketmq-ddffdb1a-nameserver -n qfusion-admin -o yaml

# 查看 PVC 状态
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 状态为 CrashLoopBackOffPending
  • Pod 反复重启
排查步骤
# 1. 查看 Pod 状态
kubectl get pod -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -o wide

# 2. 查看 Pod 详情
kubectl describe pod -n qfusion-admin rocketmq-ddffdb1a-0-0-0

# 3. 查看 Pod 日志
kubectl logs -n qfusion-admin rocketmq-ddffdb1a-0-0-0 --tail=200

# 4. 查看初始化容器日志
kubectl logs -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -c init-config --tail=200

# 5. 查看 PVC 绑定状态
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
# 删除 Pod 让其自动重建(数据不会丢失,PVC 保留)
kubectl delete pod -n qfusion-admin rocketmq-ddffdb1a-0-0-0

# 等待 Pod 重建
kubectl wait --for=condition=Ready pod -n qfusion-admin rocketmq-ddffdb1a-0-0-0 --timeout=300s

3.2 NameServer 故障

症状
  • 客户端无法连接 NameServer
  • Topic 路由信息获取失败
排查步骤
# 1. 检查所有 NameServer Pod(使用 app=name_service 标签)
kubectl get pods -n qfusion-admin -l app=name_service

# 2. 测试 NameServer 连通性
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-nameserver-0-0 -c name-service -- \
  nc -zv 246.108.185.135 9876

# 3. 查看 NameServer 日志
kubectl logs -n qfusion-admin rocketmq-ddffdb1a-nameserver-0-0 -c name-service --tail=100

# 4. 检查服务端点
kubectl get endpoints -n qfusion-admin rocketmq-ddffdb1a-nameserver-client
解决方案
# 重启 NameServer Pod
kubectl delete pod -n qfusion-admin rocketmq-ddffdb1a-nameserver-0-0

# NameServer 为无状态服务,重启不会影响已有连接
# 建议逐个重启,避免全部重启导致路由信息丢失

3.3 DLedger 集群故障

症状
  • 消息发送失败
  • Leader 选举频繁
  • 集群不可用
排查步骤
# 1. 查看集群状态
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  /root/rocketmq/broker/bin/mqadmin clusterList -n 246.108.185.135:9876

# 2. 查看 Broker 日志(包含 DLedger 相关信息)
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  tail -100 /root/logs/rocketmqlogs/broker.log | grep -i dledger

# 3. 检查网络连通性(注:DLedger 内部端口可能需要从节点 IP 访问)
# 使用节点 IP 替代集群内部 IP
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  nc -zv 246.106.184.88 40911
# 或者检查本地 DLedger 端口监听
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  netstat -tlnp | grep 40911 || ss -tlnp | grep 40911

# 4. 查看 Broker 状态
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 集群恢复
# 1. 确认至少有 2 个 Broker 正常运行(满足 Raft 多数派)
kubectl get pods -n qfusion-admin -l broker_cr=rocketmq-ddffdb1a

# 2. 如果只有一个节点正常,优先恢复其他节点
# 3. 不要轻易删除数据,DLedger 会自动进行Leader选举
# 4. 查看哪个节点是 Leader
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 增加
排查步骤
# 1. 查看所有 Topic
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  /root/rocketmq/broker/bin/mqadmin topiclist -n 246.108.185.135:9876

# 2. 查看 Topic 状态
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>

# 3. 查看消费者进度
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  /root/rocketmq/broker/bin/mqadmin consumerProgress -n 246.108.185.135:9876

# 4. 查看消费者连接
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>

# 5. 查看 TPS 统计
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  /root/rocketmq/broker/bin/mqadmin statsAll -n 246.108.185.135:9876
解决方案
# 方案1: 重置消费 Offset(谨慎使用)
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>

# 方案2: 跳过堆积消息
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 无法写入新消息
  • 日志显示磁盘空间不足
排查步骤
# 1. 查看 PV 使用情况
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- df -h

# 2. 查看存储目录大小
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- du -sh /root/store/

# 3. 查看磁盘比率
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  /root/rocketmq/broker/bin/mqadmin clusterList -n 246.108.185.135:9876
# 查看 #SPACE 列

# 4. 查看过期消息清理策略
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  cat /root/rocketmq/broker/conf/broker.conf | grep -E "deleteWhen|fileReservedTime"
解决方案
# 方案1: 手动清理过期消息(谨慎操作)
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  /root/rocketmq/broker/bin/mqadmin cleanExpiredCQ -n 246.108.185.135:9876

# 方案2: 删除过期 CommitLog(谨慎操作)
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  /root/rocketmq/broker/bin/mqadmin deleteExpiredCommitLog -n 246.108.185.135:9876

# 方案3: 扩容 PVC(需要管理员权限)
# 修改 PVC 大小或使用更大的存储类重新部署

3.6 性能问题

症状
  • 发送/消费延迟高
  • TPS 下降
排查步骤
# 1. 查看 Broker 资源使用(注:当前环境 Metrics API 不可用)
# kubectl top pod -n qfusion-admin rocketmq-ddffdb1a-0-0-0
# 替代方案:查看容器资源使用情��
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- ps aux | grep java

# 2. 查看 Broker 运行时状态
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

# 3. 查看线程池状态
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  grep -i "thread pool" /root/logs/rocketmqlogs/broker.log | tail -20

# 4. 查看 PageCache 锁定情况
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 监控端点

# Exporter 端口: 5557
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/

# Broker 主日志
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- tail -f /root/logs/rocketmqlogs/broker.log

# Store 日志
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

# NameServer 日志(容器名为 name-service)
kubectl logs -n qfusion-admin rocketmq-ddffdb1a-nameserver-0-0 -c name-service -f

5.2 日志级别调整

# 查看 broker 日志配置
kubectl exec -n qfusion-admin rocketmq-ddffdb1a-0-0-0 -- \
  cat /root/rocketmq/broker/conf/logback_broker.xml

# 临时调整日志级别(需要重启 Broker 生效)
# 修改 logback 配置中的 <root level="INFO"> 为 DEBUG

六、备份与恢复

6.1 备份策略

# 注:当前环境未配置 backupjob 资源
# DLedger 模式本身通过 Raft 协议实现数据多副本同步
# 如需配置备份,需要单独创建备份 Job 或使用外部备份方案

6.2 数据恢复

# RocketMQ DLedger 模式通过 Raft 协议自动同步数据
# 如果单个节点数据损坏,可以删除 Pod 让其重新同步

# 删除损坏的 Pod
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

# 查看 Pod 状态
kubectl get pods -n $NS -l AppName=rocketmq-ddffdb1a

# 查看 Broker 日志
kubectl logs -n $NS $BROKER --tail=100 -f

# 进入 Pod Shell
kubectl exec -it -n $NS $BROKER -- /bin/bash

# 查看 Topic 列表
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

# 查看 TPS 统计
kubectl exec -n $NS $BROKER -- /root/rocketmq/broker/bin/mqadmin statsAll -n $NSRV

9.2 测试工具

# 使用 Python 测试工具
cd /bpx/rocketmq
python3 rocketmq_test.py --topic bpx-topic --prod-rate 5 --cons-rate 2 --duration 60

# 快速测试
bash quick-test.sh

9.3 故障排查检查清单

  • 检查 Pod 状态
  • 检查 PVC 绑定状态
  • 检查节点健康状态
  • 检查 NameServer 连通性
  • 检查 DLedger Leader 状态
  • 检查磁盘空间使用率
  • 检查网络连接
  • 检查资源使用率
  • 查看相关日志
  • 检查监控指标

文档维护: 本文档应随集群变更及时更新
版本: 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 容器名: namesrvname-service
  • 移除不存在的 DLedger 单独日志目录,使用 broker.log 查阅
  • 修正 Leader 查看命令的日志路径
Logo

汇聚全球AI编程工具,助力开发者即刻编程。

更多推荐