韶关市网站建设_网站建设公司_门户网站_seo优化
2026/1/6 8:36:43 网站建设 项目流程

目录标题

  • RocketMQ 应急故障排查手册
    • 环境变量设置
    • 环境验证(2026-01-05)
      • 验证命令
      • 当前状态
      • 当前 Topic 列表
      • 当前 ConsumerGroup
    • 一、部署架构概览
      • 1.1 集群拓扑
      • 1.2 组件清单
      • 1.3 存储配置
      • 1.4 服务端口
    • 二、健康检查命令
      • 2.1 快速健康检查
      • 2.2 详细状态检查
    • 三、常见故障场景与排查
      • 3.1 Broker Pod 无法启动
        • 症状
        • 排查步骤
        • 常见原因与解决方案
        • 强制重启 Broker
      • 3.2 NameServer 故障
        • 症状
        • 排查步骤
        • 解决方案
      • 3.3 DLedger 集群故障
        • 症状
        • 排查步骤
        • DLedger 集群恢复
      • 3.4 消息堆积问题
        • 症状
        • 排查步骤
        • 解决方案
      • 3.5 磁盘空间不足
        • 症状
        • 排查步骤
        • 解决方案
      • 3.6 性能问题
        • 症状
        • 排查步骤
    • 四、监控指标说明
      • 4.1 Prometheus 监控端点
      • 4.2 关键监控指标
      • 4.3 Grafana Dashboard
    • 五、日志文件位置
      • 5.1 Broker 日志
      • 5.2 日志级别调整
    • 六、备份与恢复
      • 6.1 备份策略
      • 6.2 数据恢复
    • 七、官方文档链接
    • 八、应急联系与升级
      • 8.1 问题严重级别定义
      • 8.2 紧急恢复流程
      • 8.3 快速决策树
    • 九、附录
      • 9.1 常用运维命令速查
      • 9.2 测试工具
      • 9.3 故障排查检查清单
      • 版本更新历史

RocketMQ 应急故障排查手册

实例:rocketmq-ddffdb1a
命名空间:qfusion-admin
集群模式: DLedger (Raft 一致性协议)
版本: RocketMQ 4.9.7
文档更新: 2026-01-05
环境验证: ✓ 已通过


环境变量设置

exportKUBECONFIG=/bpx/.145-admin.conf

环境验证(2026-01-05)

验证命令

# 快速验证所有组件状态exportKUBECONFIG=/bpx/.145-admin.conf kubectl get pods-nqfusion-admin-lAppName=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 的命令:

kubectlexec-nqfusion-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 快速健康检查

exportKUBECONFIG=/bpx/.145-admin.conf# 检查所有 Pod 状态kubectl get pods-nqfusion-admin-lAppName=rocketmq-ddffdb1a# 检查集群状态kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin clusterList-n246.108.185.135:9876

2.2 详细状态检查

# 查看 Broker 资源状态kubectl get broker rocketmq-ddffdb1a-nqfusion-admin-oyaml# 查看 NameServer 资源状态kubectl get nameserver rocketmq-ddffdb1a-nameserver-nqfusion-admin-oyaml# 查看 PVC 状态kubectl get pvc-nqfusion-admin|greprocketmq-ddffdb1a# 查看事件kubectl get events-nqfusion-admin --field-selectorinvolvedObject.name=rocketmq-ddffdb1a-0-0-0 --sort-by='.lastTimestamp'

三、常见故障场景与排查

3.1 Broker Pod 无法启动

症状
  • Pod 状态为CrashLoopBackOffPending
  • Pod 反复重启
排查步骤
# 1. 查看 Pod 状态kubectl get pod-nqfusion-admin rocketmq-ddffdb1a-0-0-0-owide# 2. 查看 Pod 详情kubectl describe pod-nqfusion-admin rocketmq-ddffdb1a-0-0-0# 3. 查看 Pod 日志kubectl logs-nqfusion-admin rocketmq-ddffdb1a-0-0-0--tail=200# 4. 查看初始化容器日志kubectl logs-nqfusion-admin rocketmq-ddffdb1a-0-0-0-cinit-config--tail=200# 5. 查看 PVC 绑定状态kubectl get pvc-nqfusion-admin>常见原因与解决方案
原因检查命令解决方案
存储卷未绑定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-nqfusion-admin rocketmq-ddffdb1a-0-0-0# 等待 Pod 重建kubectlwait--for=condition=Ready pod-nqfusion-admin rocketmq-ddffdb1a-0-0-0--timeout=300s

3.2 NameServer 故障

症状
  • 客户端无法连接 NameServer
  • Topic 路由信息获取失败
排查步骤
# 1. 检查所有 NameServer Pod(使用 app=name_service 标签)kubectl get pods-nqfusion-admin-lapp=name_service# 2. 测试 NameServer 连通性kubectlexec-nqfusion-admin rocketmq-ddffdb1a-nameserver-0-0-cname-service --\nc-zv246.108.185.1359876# 3. 查看 NameServer 日志kubectl logs-nqfusion-admin rocketmq-ddffdb1a-nameserver-0-0-cname-service--tail=100# 4. 检查服务端点kubectl get endpoints-nqfusion-admin rocketmq-ddffdb1a-nameserver-client
解决方案
# 重启 NameServer Podkubectl delete pod-nqfusion-admin rocketmq-ddffdb1a-nameserver-0-0# NameServer 为无状态服务,重启不会影响已有连接# 建议逐个重启,避免全部重启导致路由信息丢失

3.3 DLedger 集群故障

症状
  • 消息发送失败
  • Leader 选举频繁
  • 集群不可用
排查步骤
# 1. 查看集群状态kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin clusterList-n246.108.185.135:9876# 2. 查看 Broker 日志(包含 DLedger 相关信息)kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\tail-100/root/logs/rocketmqlogs/broker.log|grep-idledger# 3. 检查网络连通性(注:DLedger 内部端口可能需要从节点 IP 访问)# 使用节点 IP 替代集群内部 IPkubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\nc-zv246.106.184.8840911# 或者检查本地 DLedger 端口监听kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\netstat-tlnp|grep40911||ss-tlnp|grep40911# 4. 查看 Broker 状态kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin brokerStatus-n246.108.185.135:9876-crocketmq-ddffdb1a
DLedger 集群恢复
# 1. 确认至少有 2 个 Broker 正常运行(满足 Raft 多数派)kubectl get pods-nqfusion-admin-lbroker_cr=rocketmq-ddffdb1a# 2. 如果只有一个节点正常,优先恢复其他节点# 3. 不要轻易删除数据,DLedger 会自动进行Leader选举# 4. 查看哪个节点是 Leaderkubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\grep-i"leader"/root/logs/rocketmqlogs/broker.log|tail-10

3.4 消息堆积问题

症状
  • Consumer 消费速度慢
  • 消息堆积持续增长
  • Consumer Lag 增加
排查步骤
# 1. 查看所有 Topickubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin topiclist-n246.108.185.135:9876# 2. 查看 Topic 状态kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin topicStatus-n246.108.185.135:9876-t<TOPIC_NAME># 3. 查看消费者进度kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin consumerProgress-n246.108.185.135:9876# 4. 查看消费者连接kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin consumerConnection-n246.108.185.135:9876-g<CONSUMER_GROUP># 5. 查看 TPS 统计kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin statsAll-n246.108.185.135:9876
解决方案
# 方案1: 重置消费 Offset(谨慎使用)kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin resetOffsetByTime-n246.108.185.135:9876\-g<CONSUMER_GROUP>-t<TOPIC_NAME>-s<timestamp># 方案2: 跳过堆积消息kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin skipAccumulatedMessage-n246.108.185.135:9876\-g<CONSUMER_GROUP>-t<TOPIC_NAME>

3.5 磁盘空间不足

症状
  • Broker 无法写入新消息
  • 日志显示磁盘空间不足
排查步骤
# 1. 查看 PV 使用情况kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --df-h# 2. 查看存储目录大小kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --du-sh/root/store/# 3. 查看磁盘比率kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin clusterList-n246.108.185.135:9876# 查看 #SPACE 列# 4. 查看过期消息清理策略kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\cat/root/rocketmq/broker/conf/broker.conf|grep-E"deleteWhen|fileReservedTime"
解决方案
# 方案1: 手动清理过期消息(谨慎操作)kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin cleanExpiredCQ-n246.108.185.135:9876# 方案2: 删除过期 CommitLog(谨慎操作)kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin deleteExpiredCommitLog-n246.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# 替代方案:查看容器资源使用情��kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --psaux|grepjava# 2. 查看 Broker 运行时状态kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin brokerStatus-n246.108.185.135:9876-bx.x.x.146:10911# 3. 查看线程池状态kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\grep-i"thread pool"/root/logs/rocketmqlogs/broker.log|tail-20# 4. 查看 PageCache 锁定情况kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin clusterList-n246.108.185.135:9876|grep"PCWait"

四、监控指标说明

4.1 Prometheus 监控端点

# Exporter 端口: 5557kubectl port-forward-nqfusion-admin rocketmq-ddffdb1a-nameserver-0-05557:5557# 查看指标kubectlexec-nqfusion-admin rocketmq-ddffdb1a-nameserver-0-0-crocketmq-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/# 关键日志文件kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --ls-la/root/logs/rocketmqlogs/# Broker 主日志kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --tail-f/root/logs/rocketmqlogs/broker.log# Store 日志kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --tail-f/root/logs/rocketmqlogs/store.log# 消息追踪日志kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --tail-f/root/logs/rocketmqlogs/rocketmq_client.log# NameServer 日志(容器名为 name-service)kubectl logs-nqfusion-admin rocketmq-ddffdb1a-nameserver-0-0-cname-service-f

5.2 日志级别调整

# 查看 broker 日志配置kubectlexec-nqfusion-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 让其重新同步# 删除损坏的 Podkubectl delete pod-nqfusion-admin rocketmq-ddffdb1a-0-1-0# 等待重建和数据同步kubectlwait--for=condition=Ready pod-nqfusion-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 常用运维命令速查

# 环境变量exportKUBECONFIG=/bpx/.145-admin.confexportNSRV=246.108.185.135:9876exportBROKER=rocketmq-ddffdb1a-0-0-0exportNS=qfusion-admin# 查看 Pod 状态kubectl get pods-n$NS-lAppName=rocketmq-ddffdb1a# 查看 Broker 日志kubectl logs-n$NS$BROKER--tail=100-f# 进入 Pod Shellkubectlexec-it-n$NS$BROKER-- /bin/bash# 查看 Topic 列表kubectlexec-n$NS$BROKER-- /root/rocketmq/broker/bin/mqadmin topiclist-n$NSRV# 查看集群状态kubectlexec-n$NS$BROKER-- /root/rocketmq/broker/bin/mqadmin clusterList-n$NSRV# 查看消费者进度kubectlexec-n$NS$BROKER-- /root/rocketmq/broker/bin/mqadmin consumerProgress-n$NSRV# 查看 TPS 统计kubectlexec-n$NS$BROKER-- /root/rocketmq/broker/bin/mqadmin statsAll-n$NSRV

9.2 测试工具

# 使用 Python 测试工具cd/bpx/rocketmq python3 rocketmq_test.py--topicbpx-topic --prod-rate5--cons-rate2--duration60# 快速测试bashquick-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 查看命令的日志路径

需要专业的网站建设服务?

联系我们获取免费的网站建设咨询和方案报价,让我们帮助您实现业务目标

立即咨询