RocketMQ 架构与术语详解

RocketMQ 架构与术语详解

环境: KUBECONFIG=/bpx/.145-admin.conf
实例名称: rocketmq-ddffdb1a
命名空间: qfusion-admin
版本: RocketMQ 4.9.7
集群模式: DLedger (Raft 一致性协议)

一、部署架构总览

1.1 集群拓扑图

┌──────────────────────────────────────────────────────────────────────────────────┐ │ qfusion-admin Namespace │ │ (RocketMQ 实例: rocketmq-ddffdb1a) │ ├──────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ NameServer 集群 (3副本) │ ��� │ ├───────────────────┬───────────────────┬──────────────────────────────────┤ │ │ │ nameserver-0 │ nameserver-1 │ nameserver-2 │ │ │ │ qfusion4 │ qfusion2 │ qfusion1 │ │ │ │ 245.0.3.219:9876 │ 245.0.1.220:9876 │ 245.0.0.45:9876 │ │ │ └───────────────────┴───────────────────┴──────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ DLedger Raft Group (rocketmq-ddffdb1a-0) │ │ │ │ (3副本高可用集群 - 一致性协议: Raft) │ │ │ ├───────────────────┬───────────────────┬──────────────────────────────────┤ │ │ │ Broker-0 (LEADER) │ Broker-1 (FOLLOWER)│ Broker-2 (FOLLOWER) │ │ │ │ qfusion4 │ qfusion1 │ qfusion2 │ │ │ │ 245.0.3.63 │ 245.0.0.157 │ 245.0.1.254 │ │ │ │ BrokerId=0 │ BrokerId=1 │ BrokerId=3 │ │ │ │ 10.10.186.146:3 │ 10.10.186.146:9 │ 10.10.186.146:6 │ │ │ └───────────────────┴───────────────────┴──────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ qfusion Namespace │ │ │ │ (管理平面组件) │ │ │ ├───────────────────┬──────────────────────────────────────────────────────┤ │ │ │ rocketmq-operator │ rocketmq-webserver (2副本) │ │ │ │ Pod 管理 │ Web 控制台 (9090端口) │ │ │ └───────────────────┴──────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────────────────┘

1.2 资源清单

1.3 组件分布

二、核心术语详解

2.1 架构组件术语

2.2 消息模型术语

2.3 消费者模型术语

2.4 性能指标术语

三、服务端口说明

3.1 NameServer 端口

3.2 Broker 端口

3.3 管理服务端口

四、存储架构

4.1 存储卷清单

4.2 Broker 存储目录结构

/root/store/ ├── commitlog/ # 原始消息存储 ├── consumequeue/ # 消费队列索引 ├── index/ # 消息索引文件 ├── abort/ # 异常退出标识 └── logs/ # 运行日志 ├── broker.log # Broker 主日志 ├── dledger/ # DLedger 一致性日志 └── rmq.log # 消息追踪日志

4.3 NameServer 存储目录结构

/root/ ├── logs/ │ └── namesrv.log # NameServer 日志 └── store/ # NameServer 数据目录（如有）

五、DLedger 模式详解

5.1 DLedger 工作原理

生产者写入流程 (DLedger 模式): ┌────────┐ ┌─────────┐ ┌────────┐ ┌──────────┐ ┌─────────┐ │Producer│ ──> │ Leader │ ──> │ Raft │ ──> │ Followers│ ──> │ 确认写入 │ └────────┘ │ Broker │ │ 协议 │ │ Broker │ └─────────┘ └─────────┘ └──────────┘ └──────────┘ │ │ └────────── 同步复制 ────────────┘ 要求: 至少 2/3 节点确认后才返回成功（多数派原则）

5.2 Leader 选举

5.3 DLedger 配置参数

六、客户端连接配置

6.1 NameServer 连接地址

# 内部集群访问（Pod 间） 246.108.185.135:9876 # 多地址格式（分号分隔） 245.0.3.219:9876;245.0.1.220:9876;245.0.0.45:9876

6.2 Broker 连接地址

6.3 Java 客户端示例

// 生产者配置DefaultMQProducerproducer=newDefaultMQProducer("producer-group");producer.setNamesrvAddr("246.108.185.135:9876");producer.start();// 消费者配置DefaultMQPushConsumerconsumer=newDefaultMQPushConsumer("consumer-group");consumer.setNamesrvAddr("246.108.185.135:9876");consumer.subscribe("bpx-topic","*");consumer.registerMessageListener(newMessageListenerConcurrently(){@OverridepublicConsumeConcurrentlyStatusconsumeMessage(List<MessageExt>msgs,Contextcontext){// 处理消息returnConsumeConcurrentlyStatus.CONSUME_SUCCESS;}});consumer.start();

七、常用资源查询命令

7.1 集群资源查询

# 设置环境变量exportKUBECONFIG=/bpx/.145-admin.confexportNSRV=246.108.185.135:9876# 查看所有 Pod 状态kubectl get pods-nqfusion-admin|greprocketmq# 查看 Broker 资源kubectl get broker-nqfusion-admin# 查看 NameServer 资源kubectl get nameservers-nqfusion-admin# 查看服务kubectl get svc-nqfusion-admin|greprocketmq# 查看存储卷kubectl get pvc-nqfusion-admin|greprocketmq

7.2 Topic 相关查询

# 进入 Broker Podkubectlexec-it-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --bash# 查看 Topic 列表mqadmin topiclist-n$NSRV# 查看 Topic 状态mqadmin topicStatus-n$NSRV-t<TOPIC_NAME># 查看 Topic 路由mqadmin topicRoute-n$NSRV-t<TOPIC_NAME>

7.3 消费者相关查询

# 查看所有消费者进度mqadmin consumerProgress-n$NSRV# 查看特定消费者组mqadmin consumerProgress-n$NSRV-g<CONSUMER_GROUP># 查看消费者连接mqadmin consumerConnection-n$NSRV-g<CONSUMER_GROUP>

八、集群模式对比

九、核心概念关系图

┌─────────────────────────────────────────────────────────────────────┐ │ RocketMQ 消息模型 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ Producer ──发送消息──> Topic ──分片──> Queue ──分布──> Broker │ │ │ │ │ │ │ └──────────────────┐ │ │ │ │ │ │ v v │ │ ConsumerGroup ──订阅──> Topic ──消费──> Queue ──分配──> Consumer │ │ │ │ 关键点: │ │ * 一个 Topic 可以有多个 ConsumerGroup │ │ * 一个 ConsumerGroup 内只有一个 Consumer 消费同一条消息 │ │ * 不同 ConsumerGroup 可以独立消费同一条消息 │ │ * Offset 按 ConsumerGroup 维度管理 │ │ │ └─────────────────────────────────────────────────────────────────────┘

十、快速参考

10.1 集群访问信息

10.2 当前 Topic 示例

10.3 当前 ConsumerGroup 示例

文档版本: v1.1
最后更新: 2025-12-31
维护者: 运维团队

十一、入门必读知识

11.1 消息队列是什么？

消息队列（Message Queue）是一种进程间通信或服务间通信的方式：

┌─────────────┐ 消息 ┌─────────────┐ 消息 ┌─────────────┐ │ 服务 A │ ──────────> │ RocketMQ │ ──────────> │ 服务 B │ │ (生产者) │ │ (中转站) │ │ (消费者) │ └─────────────┘ └─────────────┘ └─────────────┘ 核心价值: * 解耦: A 不需要知道 B 的存在 * 异步: A 发完就继续，不用等 B 处理 * 削峰: 高峰期消息先缓存，慢慢消费

11.2 消息的生命周期

1. [生产] Producer 发送消息到 Topic ↓ 2. [路由] NameServer 告诉 Producer 该连哪个 Broker ↓ 3. [存储] Broker 将消息写入 CommitLog ↓ 4. [索引] 更新 ConsumeQueue 索引 ↓ 5. [推送] Consumer 从 Broker 拉取消息 ↓ 6. [消费] Consumer 处理业务逻辑 ↓ 7. [确认] Consumer 提交消费 Offset ↓ 8. [清理] 过期消息被自动删除

11.3 消费模式对比

# 默认是集群模式，无需额外配置# 广播模式需要在消费者端设置:consumer.setMessageModel(MessageModel.BROADCASTING);

11.4 推送 vs 拉取

// Push Consumer (推荐)DefaultMQPushConsumerconsumer=newDefaultMQPushConsumer("group");consumer.subscribe("topic","*");consumer.registerMessageListener(listener);// 回调处理consumer.start();// Pull ConsumerDefaultMQPullConsumerconsumer=newDefaultMQPullConsumer("group");consumer.start();Set<MessageQueue>mqs=consumer.fetchSubscribeMessageQueues("topic");// 手动控制拉取逻辑

11.5 消息重试机制

消费失败后的处理流程: ┌──────────────┐ │ 消息消费失败 │ └──────┬───────┘ │ v ┌──────────────────┐ 是 ┌────────────────┐ │ 是否返回 RECONSUME_LATER? │ ──> │ 加入重试队列 │ └──────────────────┘ └───────┬────────┘ │ 否 │ v v ┌────────────────┐ ┌─────────────────────┐ │ 消息成功确认 │ │ 延时后重新消费 │ │ Offset 推进 │ │ (延时等级递增) │ └────────────────┘ └─────────────────────┘ │ ┌──────────┴──────────┐ v v 重试次数 < 16 重试次数 >= 16 │ │ v v 继续重试 进入死信队列 (%RETRY%组名) (%DLQ%组名)

重试延时等级(默认):

级别 1: 1s 2: 5s 3: 10s 4: 30s 5: 1m 级别 6: 2m 7: 3m 8: 4m 9: 5m 10: 6m 级别 11: 7m 12: 8m 13: 9m 14: 10m 15: 30m 级别 16: 1h

11.6 延时消息

RocketMQ 支持特定延时等级的消息：

Messagemsg=newMessage("topic","Hello".getBytes());// 延时等级 1-18，对应延时时间如上msg.setDelayTimeLevel(3);// 延时 10 秒producer.send(msg);

⚠️ 注意: 开源版只支持固定延时等级，不支持任意秒数

11.7 事务消息

事务消息 = 消息发送 + 本地事务 的原子性保证 ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 发送半消息 │ ──> │ 执行本地事务 │ ──> │ 提交/回滚 │ └──────────┘ └──────────┘ └──────────┘ │ │ v v ┌──────────────────────────────────────────┐ │ Broker 等待确认 │ │ * 回查机制: 未确认则反查事务状态 │ └──────────────────────────────────────────┘

TransactionMQProducerproducer=newTransactionMQProducer("group");producer.setTransactionListener(newTransactionListener(){@OverridepublicLocalTransactionStateexecuteLocalTransaction(Messagemsg,Objectarg){// 执行本地事务// 返回 COMMIT, ROLLBACK, 或 UNKNOWNreturnLocalTransactionState.COMMIT_MESSAGE;}@OverridepublicLocalTransactionStatecheckLocalTransaction(MessageExtmsg){// 回查本地事务状态returnLocalTransactionState.COMMIT_MESSAGE;}});

11.8 Tag 与 Message Key

Topic: 第一级分类，如 "订单" Tag: 第二级分类，如 "创建"、"支付"、"完成" Key: 消息唯一标识，如订单ID ┌─────────────────────────────────────────────────┐ │ Topic: OrderTopic │ ├─────────────────────────────────────────────────┤ │ Tag: TagA Tag: TagB Tag: TagC │ │ [订单创建] [订单支付] [订单完成] │ │ Key: Order123 Key: Order123 Key: Order123│ └─────────────────────────────────────────────────┘

// 发送时设置 Tag 和 KeyMessagemsg=newMessage("OrderTopic","TagA","Order123",body);producer.send(msg);// 消费时按 Tag 过滤consumer.subscribe("OrderTopic","TagA || TagB");// 订阅多个 Tag

11.9 消息堆积与处理

消息堆积 = 生产速度 > 消费速度 ┌────────────────────────────────────────────────────────┐ │ Broker │ │ ┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐ │ │ │msg1││msg2││msg3││msg4││msg5││msg6││msg7││msg8│...│ │ └────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘ │ │ ↑ ↑ │ │ 已消费 堆积部分 │ │ │ │ │ Diff Total = 堆积量 │ └──────────────────────────────────────────────────────┘

堆积处理策略:

11.10 常见问题 FAQ

十二、学习路径建议

12.1 新手入门路线

第1天: 基础概念 ├─ 了解消息队列是什么 ├─ 理解 Topic/ConsumerGroup/Queue 概念 └─ 熟悉 NameServer 和 Broker 角色 第2天: 环境操作 ├─ 使用 mqadmin 查看集群状态 ├─ 查看 Topic 和 ConsumerGroup └─ 理解 Offset 和消息堆积 第3天: 生产消费 ├─ 使用 mqadmin sendMessage 发送消息 ├─ 使用 mqadmin consumeMessage 消费消息 └─ 观察 topicStatus 变化 第4天: 故障排查 ├─ 掌握 4 步排障法 ├─ 理解重试机制 └─ 学习处理堆积 第5天: 进阶知识 ├─ DLedger 一致性原理 ├─ 事务消息机制 └─ 性能调优基础

12.2 实战练习建议

# 练习1: 发送测试消息kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin sendMessage\-n246.108.185.135:9876-tbpx-topic-p"test"# 练习2: 观察 Topic 变化kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin topicStatus\-n246.108.185.135:9876-tbpx-topic# 练习3: 查看消费进度kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin consumerProgress\-n246.108.185.135:9876# 练习4: 查看 TPS 统计kubectlexec-nqfusion-admin rocketmq-ddffdb1a-0-0-0 --\/root/rocketmq/broker/bin/mqadmin statsAll\-n246.108.185.135:9876|grepbpx-topic

12.3 推荐阅读顺序

1. 本文档 - 架构与术语
2. mqadmin-troubleshooting-guide.md - 命令工具使用
3. RocketMQ_Emergency_Troubleshooting.md - 应急故障处理
4. 官方文档 - https://rocketmq.apache.org/zh/docs/