# 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 集群故障
症状
排查步骤
# 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 磁盘空间不足
症状
排查步骤
# 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 性能问题
症状
排查步骤
# 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_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/# 关键日志文件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 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 常用运维命令速查
# 环境变量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 故障排查检查清单
文档维护: 本文档应随集群变更及时更新
版本: 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 查看命令的日志路径