目录标题

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-0rocketmq-ddffdb1a-nameserver-0-0Running (2/2)qfusion4245.0.3.219
NameServer-1rocketmq-ddffdb1a-nameserver-1-0Running (2/2)qfusion2245.0.1.220
NameServer-2rocketmq-ddffdb1a-nameserver-2-0Running (2/2)qfusion1245.0.0.45
Broker-0rocketmq-ddffdb1a-0-0-0Running (1/1)qfusion4245.0.3.63
Broker-1rocketmq-ddffdb1a-0-1-0Running (1/1)qfusion1245.0.0.157
Broker-2rocketmq-ddffdb1a-0-2-0Running (1/1)qfusion2245.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-groupOFFLINE0测试消费组（当前离线）
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角色
NameServerrocketmq-ddffdb1a-nameserver-0-0qfusion4245.0.3.219路由发现
NameServerrocketmq-ddffdb1a-nameserver-1-0qfusion2245.0.1.220路由发现
NameServerrocketmq-ddffdb1a-nameserver-2-0qfusion1245.0.0.45路由发现
Brokerrocketmq-ddffdb1a-0-0-0qfusion4245.0.3.63Broker (ID=0)
Brokerrocketmq-ddffdb1a-0-1-0qfusion1245.0.0.157Broker (ID=1)
Brokerrocketmq-ddffdb1a-0-2-0qfusion2245.0.1.254Broker (ID=3)

注: DLedger 模式下，LEADER 由 Raft 协议动态选举，任一 Broker 都可能成为 Leader

1.3 存储配置

PVC容量存储类挂载节点
data-rocketmq-ddffdb1a-0-0-010Gicsi-localpvqfusion4
data-rocketmq-ddffdb1a-0-1-010Gicsi-localpvqfusion1
data-rocketmq-ddffdb1a-0-2-010Gicsi-localpvqfusion2
data-rocketmq-ddffdb1a-nameserver-*-020Gicsi-localpv各节点

1.4 服务端口

服务端口说明
NameServer9876NameServer 服务端口
Broker VIP10909Broker 内部通信
Broker Main10911Broker 主服务端口
Broker HA10912Broker 高可用端口
DLedger40911DLedger Raft 协议端口
Exporter5557Prometheus 指标端口

二、健康检查命令

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 状态为 CrashLoopBackOff 或 Pending
  • 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_ratioCommitLog 磁盘使用率<0.8>0.9
rocketmq_brokeruntime_consumequeue_disk_ratioConsumeQueue 磁盘使用率<0.8>0.9
rocketmq_brokeruntime_put_message_average_size平均消息大小正常范围异常波动
rocketmq_brokeruntime_pagecache_lock_time_millsPageCache 锁定时间<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 GitHubhttps://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 Exporterhttps://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 容器名: namesrv → name-service
  • 移除不存在的 DLedger 单独日志目录，使用 broker.log 查阅
  • 修正 Leader 查看命令的日志路径
# rocketmq
Logo
AI编程社区

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

更多推荐

cover

码道 · 寻艺——从零构建“非遗交互式对话平台“的完整实践

avatar AI编程社区

码道：用 Python + FastAPI 快速构建一个学生信息管理接口：从零到 Swagger 在线文档

在日常开发和教学中，我们经常需要一套简单、可控、能快速上手的后端接口来演示"前后端分离"、练习 Restful API 设计，或者作为前端联调的 Mock 服务。传统做法往往是搭一套完整的 Web 工程：配置数据库、编写 DAO、引入 ORM、做请求分发……一套流程下来，光环境搭建就要花去不少时间，对于想快速验证想法、或者刚入门 API 开发的同学来说，显得过于沉重。

avatar AI编程社区

码道：从零构建学生信息管理系统 API：FastAPI 内存版 CRUD 项目全解析

FastAPI 的强大，很大程度上来自 Pydantic 的校验能力。我们写下类型声明，FastAPI 在运行时自动把它变成边界检查器。name：字符串，长度限制 1 到 50；age：整数，限制在 6 到 120 之间（ge大于等于、le小于等于）；gender：字符串，用正则限定只能是"男"“女”“其他”；email：邮箱格式字符串；grade与major：可选字段，代表班级和专业方向。

avatar AI编程社区