```mdk height=520 color=#4f46e5 # RocketMQ 使用与接入 ## 是什么 ### 阿里开源,后捐给 Apache,Java 编写 ### NameServer 注册中心 + Broker 存储转发 ### 强项:事务消息、延时/定时消息、消息回溯 ### 典型场景:订单、支付、削峰、异步解耦 ## 两代架构 ### 4.x:Remoting 私有协议 - 客户端连 NameServer:9876 - 再直连 Broker:10911 - Java 客户端 rocketmq-client ### 5.x:Proxy + gRPC - 客户端只连 Proxy:8081 - Proxy 代理 NameServer 与 Broker - 官方多语言客户端统一走 gRPC - 服务端仍兼容 4.x 老客户端 ## 部署 ### 4.x 二进制:mqnamesrv + mqbroker ### 5.x 容器:namesrv + broker + proxy ### 控制台:rocketmq-dashboard ## 四种接入方式 ### Java 4.x remoting ### Java 5.x gRPC ### Spring Boot(rocketmq-spring-boot-starter) ### Go / Python / C++ / Node.js 客户端 ## 消息类型 - 普通消息 - 顺序消息(队列级有序) - 延时/定时消息 - 事务消息 - 批量消息 - Tag / SQL92 过滤 ## 可靠性与运维 - 主从复制、flushDiskType - 消费重试 %RETRY%group - 死信队列 %DLQ%group - 消费端幂等 - mqadmin 常用命令 ## 常见坑 - brokerIP1 要配对外 IP - No route info of this topic - 发送超时多为 10911 不通 - 内存不足导致启动失败 ``` ===== 一、RocketMQ 是什么 ===== RocketMQ 最早由阿里内部研发(前身 MetaQ),2016 年捐给 Apache 基金会,现为 Apache 顶级项目。纯 Java 实现,特点是**高吞吐 + 低延迟 + 功能丰富**:事务消息、延时/定时消息、消息回溯、Tag/SQL92 过滤都是原生能力。 ^ 组件 ^ 作用 ^ | NameServer | 无状态注册中心,Broker 向它注册、客户端向它拉路由;生产环境一般部署 2~3 台 | | Broker | 真正存消息、转发消息的节点,启动时向所有 NameServer 注册 | | Topic | 逻辑上的消息分类,内部再切成多个 Queue(默认 4 个) | | Producer / Consumer Group | 生产者组 / 消费者组;组内负载均衡,组间各得一份 | 四个招牌能力(也是它相对 Kafka 的差异点): * **事务消息**:半消息 + 本地事务回查,解决「发消息」和「写数据库」的一致性问题。 * **延时 / 定时消息**:4.x 支持 18 个固定延时级别,5.x 支持任意时间戳。 * **消息回溯**:按时间戳重置消费位点(''resetOffsetByTime''),可重新消费历史消息,业务侧比改 offset 友好。 * **丰富的过滤**:Tag 过滤、SQL92 属性过滤,在 Broker 端就把不需要的消息筛掉。 ===== 二、4.x 与 5.x 的核心区别 ===== 一句话:**5.x = 4.x 的存储内核 + 新增 Proxy 统一入口 + gRPC 协议**。服务端换了架构,老客户端不改代码也能用。 ^ 对比项 ^ 4.x ^ 5.x ^ | 通信协议 | Remoting(自定义 TCP 协议) | gRPC(新客户端)+ Remoting(兼容老客户端) | | 客户端连接目标 | 先连 NameServer:9876 拿路由,再直连 Broker:10911 | 只连 Proxy 的 8081,由 Proxy 转发 | | 官方 Java 客户端 | ''org.apache.rocketmq:rocketmq-client'' | ''rocketmq-client-java''(gRPC);''rocketmq-client'' 5.x 仍可用 | | 多语言客户端 | C++ / Go / Python,各基于 remoting 或 C++ 内核 | 官方统一 gRPC 客户端:Java / C++ / Go / Rust / Python | | 延时消息 | 固定 18 级(1s 5s 10s 30s 1m … 2h) | 任意时间戳,精度秒级 | | 消费模式 | Push(''DefaultMQPushConsumer'')/ Pull | PushConsumer / SimpleConsumer(显式 ack)/ POP 模式 | | 扩缩容表现 | 消费者按队列重平衡,扩容时可能短暂重复消费 | POP 模式把重平衡放到 Broker 侧,扩缩容更平滑 | | 运维入口 | mqadmin 命令行 + rocketmq-console | mqadmin + Proxy 管理接口 + rocketmq-dashboard | | 兼容性 | — | 5.x 服务端同时开 remoting(10911)与 gRPC(8081),4.x 客户端可继续接 | **怎么选**: * 老项目、已有 4.x 客户端、Spring Boot 老版本 starter —— 继续走 remoting,服务端升到 5.x 也能跑。 * 新项目、多语言团队(Go / Rust / Python)、需要任意时刻定时消息 —— 直接上 5.x Proxy + gRPC 客户端。 * 4.x 客户端要连 5.x 集群时,Proxy 需要保留 remoting 兼容(配置项在 ''conf/rmq-proxy.json'' 里,例如 ''enableRemotingAccess'',键名以所用版本为准),否则老客户端连不上。 == 端口速记 == ^ 端口 ^ 用途 ^ | 9876 | NameServer(4.x 客户端连这个) | | 10911 | Broker 主服务端口(客户端收发消息) | | 10909 | Broker VIP / fast-remoting 通道 | | 8080 | 5.x Proxy 的 HTTP 接口 / 管理端口 | | 8081 | 5.x Proxy 的 gRPC 端口(新客户端连这个) | | 8082 | rocketmq-dashboard 示例端口 | ===== 三、部署 ===== == 3.1 老版本:4.x 二进制包(最经典) == wget https://archive.apache.org/dist/rocketmq/4.9.7/rocketmq-all-4.9.7-bin-release.zip unzip rocketmq-all-4.9.7-bin-release.zip && cd rocketmq-all-4.9.7-bin-release # 1) 改内存:默认要 4G/8G,小机器必须调小,否则起不来 vi bin/runserver.sh # -Xms512m -Xmx512m -Xmn256m vi bin/runbroker.sh # -Xms1g -Xmx1g # 2) Broker 配置 conf/broker.conf brokerClusterName = DefaultCluster brokerName = broker-a brokerId = 0 namesrvAddr = 127.0.0.1:9876 brokerIP1 = 192.168.1.10 # 关键:客户端最终连这个 IP,容器/云主机必须显式指定 listenPort = 10911 deleteWhen = 04 fileReservedTime = 48 brokerRole = ASYNC_MASTER flushDiskType = ASYNC_FLUSH autoCreateTopicEnable = true # 生产环境建议 false,改为手工建 Topic # 3) 启动 nohup sh bin/mqnamesrv & # NameServer nohup sh bin/mqbroker -c conf/broker.conf & # Broker # 4) 验证 sh bin/mqadmin clusterList -n 127.0.0.1:9876 控制台(可选): docker run -d --name rocketmq-dashboard -p 8082:8080 \ -e "JAVA_OPTS=-Drocketmq.namesrv.addr=127.0.0.1:9876" \ apacherocketmq/rocketmq-dashboard:latest == 3.2 新版本:5.x(namesrv + broker + proxy 三角色) == 生产建议三个角色分开部署;开发环境可以让 Broker 内嵌 Proxy(Local 模式)。 # NameServer docker run -d --name rmqnamesrv -p 9876:9876 \ -e "JAVA_OPT_EXT=-Xms512m -Xmx512m" \ apache/rocketmq:5.3.1 sh mqnamesrv # Broker(指向 NameServer) docker run -d --name rmqbroker --link rmqnamesrv:namesrv \ -p 10911:10911 -p 10909:10909 \ -e "NAMESRV_ADDR=namesrv:9876" \ -e "JAVA_OPT_EXT=-Xms1g -Xmx1g" \ apache/rocketmq:5.3.1 sh mqbroker -c /home/rocketmq/conf/broker.conf # Proxy(客户端连它的 8081) docker run -d --name rmqproxy --link rmqnamesrv:namesrv \ -p 8080:8080 -p 8081:8081 \ -e "NAMESRV_ADDR=namesrv:9876" \ apache/rocketmq:5.3.1 sh mqproxy 要点: * 新客户端连的是 **Proxy 的 8081**,不是 NameServer 的 9876,这是新老接入最大的差别。 * ''brokerIP1'' 依然要填对外真实 IP,否则 Proxy 会把内网地址回给客户端,报连接超时。 * Proxy 的配置在 ''conf/rmq-proxy.json''(''namesrvAddr''、''grpcServerPort'' 等)。 * 用云上托管版时,控制台给出的「接入点」就是 Proxy 的 endpoints,直接交给第 5 节的 gRPC 客户端。 ===== 四、接入方式一:Java 4.x(remoting,连 9876) ===== 依赖: org.apache.rocketmq rocketmq-client 4.9.7 == 生产者 == DefaultMQProducer producer = new DefaultMQProducer("pg_order"); // 生产者组 producer.setNamesrvAddr("192.168.1.10:9876"); producer.setSendMsgTimeout(3000); producer.setRetryTimesWhenSendFailed(2); producer.start(); // 只启动一次,务必全应用复用 Message msg = new Message( "topic_order", // topic "PAID", // tag "orderId=A1001", // keys,便于控制台按消息查询 "{\"orderId\":\"A1001\",\"amount\":99.5}".getBytes(StandardCharsets.UTF_8)); SendResult sr = producer.send(msg); // 同步发送 System.out.println(sr.getSendStatus() + " / " + sr.getMsgId()); // 异步:producer.send(msg, new SendCallback(){ onSuccess / onException }); // 单向:producer.sendOneway(msg); (不关心结果,吞吐最高) // 批量:producer.send(Collection) (同 topic,总大小不超过 4MB) // 指定队列:producer.send(msg, new MessageQueueSelector(){...}, arg) → 顺序消息用 producer.shutdown(); == 消费者(Push 模式,最常用) == DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("cg_order"); consumer.setNamesrvAddr("192.168.1.10:9876"); consumer.subscribe("topic_order", "PAID || REFUND"); // Tag 过滤;"*" 表示全部 consumer.setConsumeFromWhere(ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET); consumer.setConsumeThreadMin(10); consumer.setConsumeThreadMax(20); consumer.setMaxReconsumeTimes(16); // 超过次数进死信队列 consumer.registerMessageListener((MessageListenerConcurrently) (msgs, ctx) -> { for (MessageExt m : msgs) { try { handle(new String(m.getBody(), StandardCharsets.UTF_8)); } catch (Exception e) { return ConsumeConcurrentlyStatus.RECONSUME_LATER; // 稍后重试 } } return ConsumeConcurrentlyStatus.CONSUME_SUCCESS; // 成功才提交位点 }); consumer.start(); == 顺序消息 == 同一订单的消息必须落进同一个队列,消费端用 ''MessageListenerOrderly'': // 生产端:按业务主键选队列 producer.send(msg, (mqs, m, arg) -> mqs.get(Math.abs(arg.hashCode()) % mqs.size()), "A1001"); // 消费端:顺序监听器 consumer.registerMessageListener((MessageListenerOrderly) (msgs, ctx) -> { // 暂时无法处理时返回这个状态,而不是无限阻塞 // return ConsumeOrderlyStatus.SUSPEND_CURRENT_QUEUE_A_MOMENT; return ConsumeOrderlyStatus.SUCCESS; }); == 延时消息(4.x 固定 18 级) == msg.setDelayTimeLevel(5); // 级别:1s 5s 10s 30s 1m 2m 3m 4m 5m 6m 7m 8m 9m 10m 20m 30m 1h 2h // level=5 → 1m,level=17 → 2h == 事务消息 == TransactionMQProducer producer = new TransactionMQProducer("pg_tx"); producer.setNamesrvAddr("192.168.1.10:9876"); producer.setExecutorService(Executors.newFixedThreadPool(8)); // 回查线程池 producer.setTransactionListener(new TransactionListener() { @Override public LocalTransactionState executeLocalTransaction(Message msg, Object arg) { try { orderService.create((String) arg); // 本地事务:写库 return LocalTransactionState.COMMIT_MESSAGE; } catch (Exception e) { return LocalTransactionState.ROLLBACK_MESSAGE; } } @Override public LocalTransactionState checkLocalTransaction(MessageExt msg) { // Broker 回查本地事务状态,必须能查到真实结果 return orderService.exists(msg.getKeys()) ? LocalTransactionState.COMMIT_MESSAGE : LocalTransactionState.ROLLBACK_MESSAGE; } }); producer.start(); producer.sendMessageInTransaction(msg, "A1001"); // 先发半消息,再回调本地事务 ===== 五、接入方式二:Java 5.x(gRPC,连 8081) ===== 依赖(JDK 8+): org.apache.rocketmq rocketmq-client-java 5.0.7 == 客户端配置与生产者 == ClientServiceProvider provider = ClientServiceProvider.loadService(); ClientConfiguration cfg = ClientConfiguration.newBuilder() .setEndpoints("192.168.1.10:8081") // Proxy 的 gRPC 端口,多个用分号隔开 // 开启 ACL 时: // .setCredentialProvider(SessionCredentialsProvider.newBuilder() // .setAccessKey("ak").setAccessSecret("sk").build()) .build(); Producer producer = provider.newProducerBuilder() .setClientConfiguration(cfg) .setTopics("topic_order") // 前置声明用到的 topic .build(); Message msg = provider.newMessageBuilder() .setTopic("topic_order") .setTag("PAID") .setKeys("A1001") .setBody("{\"orderId\":\"A1001\"}".getBytes(StandardCharsets.UTF_8)) // 定时消息(5.x 新能力,任意时刻,精度秒级) // .setDeliveryTimestamp(System.currentTimeMillis() + 60_000L) .build(); SendReceipt receipt = producer.send(msg); System.out.println(receipt.getMessageId()); // 异步:producer.sendAsync(msg) → CompletableFuture producer.close(); // 实现 Closeable == PushConsumer(推荐,框架自动 ack) == PushConsumer consumer = provider.newPushConsumerBuilder() .setClientConfiguration(cfg) .setConsumerGroup("cg_order") .setSubscriptionExpressions(Collections.singletonMap("topic_order", "*")) .setMessageListener(messageView -> { try { handle(messageView.getBody().toString(StandardCharsets.UTF_8)); return ConsumeResult.SUCCESS; } catch (Exception e) { return ConsumeResult.FAILURE; // 触发重试,超限进死信 } }) .build(); == SimpleConsumer(拉模式,显式 ack,适合批量与自定义流控) == SimpleConsumer consumer = provider.newSimpleConsumerBuilder() .setClientConfiguration(cfg) .setConsumerGroup("cg_order_pull") .setAwaitDuration(java.time.Duration.ofSeconds(15)) .setSubscriptionExpressions(Collections.singletonMap("topic_order", "*")) .build(); List msgs = consumer.receive(32, java.time.Duration.ofSeconds(15)); for (MessageView m : msgs) { process(m); consumer.ack(m); // 处理成功才 ack;也可 changeInvisibleDuration 延长不可见时间 } == 事务消息(5.x 写法更简洁) == Producer producer = provider.newProducerBuilder() .setClientConfiguration(cfg) .setTopics("topic_order") .setTransactionChecker(messageView -> TransactionResolution.COMMIT) // 回查逻辑 .build(); Transaction transaction = producer.beginTransaction(); producer.send(transaction, msg); transaction.commit(); // 本地事务成功则 commit,失败则 transaction.rollback() == 4.x → 5.x API 映射速查 == ^ 能力 ^ 4.x remoting ^ 5.x gRPC ^ | 入口配置 | ''setNamesrvAddr("ip:9876")'' | ''ClientConfiguration#setEndpoints("ip:8081")'' | | 生产者 | ''DefaultMQProducer'' | ''ClientServiceProvider#newProducerBuilder'' | | 推消费 | ''DefaultMQPushConsumer'' + Listener | ''newPushConsumerBuilder'' + MessageListener | | 拉消费 | ''DefaultMQPullConsumer''(API 繁琐) | ''newSimpleConsumerBuilder'' + ''receive / ack'' | | 发送结果 | ''SendResult'' | ''SendReceipt'' | | 延时消息 | ''setDelayTimeLevel(int)'' | ''setDeliveryTimestamp(long)'' | | 事务消息 | ''TransactionMQProducer'' + TransactionListener | ''beginTransaction / commit / rollback'' + TransactionChecker | | 日志 | 自带 logback 配置 | 需自行引入 slf4j 实现,否则启动报错 | | 资源释放 | ''shutdown()'' | ''close()'' | ===== 六、接入方式三:Spring Boot ===== org.apache.rocketmq rocketmq-spring-boot-starter 2.3.1 rocketmq.name-server=192.168.1.10:9876 rocketmq.producer.group=pg_order rocketmq.producer.send-message-timeout=3000 # 开启 ACL 时再填 # rocketmq.producer.access-key= # rocketmq.producer.secret-key= 发送(''RocketMQTemplate'',topic 与 tag 用冒号分隔): @Resource private RocketMQTemplate rocketMQTemplate; public void pay(String payload) { // 同步 SendResult r = rocketMQTemplate.syncSend("topic_order:PAID", payload); // 异步 rocketMQTemplate.asyncSend("topic_order:PAID", payload, new SendCallback() { @Override public void onSuccess(SendResult sendResult) { } @Override public void onException(Throwable e) { } }); // 单向 rocketMQTemplate.sendOneWay("topic_order:LOG", "click"); // 顺序消息:第三个参数是 hashKey rocketMQTemplate.syncSendOrderly("topic_order:PAID", payload, "A1001"); // 延时消息:最后一个参数是 4.x 的延时级别 rocketMQTemplate.syncSend("topic_order:PAID", MessageBuilder.withPayload(payload).build(), 3000, 5); } 消费: @Service @RocketMQMessageListener( topic = "topic_order", consumerGroup = "cg_order", selectorExpression = "PAID", consumeMode = ConsumeMode.ORDERLY) // 默认 CONCURRENTLY public class OrderConsumer implements RocketMQListener { @Override public void onMessage(String body) { // 正常返回即消费成功;抛异常会触发重试 } } ===== 七、接入方式四:Go / Python / C++ / Node.js ===== ^ 语言 ^ 4.x(remoting) ^ 5.x(gRPC) ^ | Go | ''github.com/apache/rocketmq-client-go/v2'' | ''github.com/apache/rocketmq-clients/golang/v5'' | | Python | ''pip install rocketmq-client-python''(C++ 内核) | apache/rocketmq-clients 的 python 目录(gRPC,需自行装 grpcio 依赖) | | C++ | ''rocketmq-client-cpp'' | ''rocketmq-client-cpp'' 的 5.x 分支(gRPC) | | Rust | ''rocketmq-client-rust''(4.x 内核) | ''rocketmq-client-rust'' 的 5.x 分支(gRPC) | | Node.js | ''rocketmq-client-nodejs''(C++ 绑定,连 9876,已少维护) | **无官方客户端**:用 ''@grpc/grpc-js'' 自行直连 Proxy,或走 Go/Python sidecar(见下) | Go(4.x 风格): p, _ := rocketmq.NewProducer( producer.WithNameServer([]string{"192.168.1.10:9876"}), producer.WithGroupName("pg_order"), producer.WithRetry(2)) _ = p.Start() res, err := p.SendSync(context.Background(), &primitive.Message{ Topic: "topic_order", Body: []byte("hello"), }) _ = res _ = err defer p.Shutdown() Go(5.x gRPC 风格): producer, _ := golang.NewProducer(&golang.Config{ Endpoint: "192.168.1.10:8081", Credentials: credentials.NewCredentials("", ""), }, golang.WithTopics("topic_order")) _ = producer.Start() resp, err := producer.Send(context.Background(), &golang.Message{ Topic: "topic_order", Body: []byte("hello"), }) _ = resp _ = err // defer producer.GracefulStop() Python(4.x 风格): from rocketmq.client import Producer, Message producer = Producer('pg_order') producer.set_name_server_address('192.168.1.10:9876') producer.start() msg = Message('topic_order') msg.set_keys('A1001') msg.set_tags('PAID') msg.set_body('{"orderId":"A1001"}') producer.send_sync(msg) producer.shutdown() == Node.js 接 5.x gRPC:官方没客户端,两条路 == 先把现状说清楚:官方 ''rocketmq-clients'' 覆盖 Java / C++ / C# / Go / Rust / Python 等语言,**Node.js 一直是个空缺**;能搜到的 ''rocketmq-client-nodejs'' 是 4.x 时代的 C++ 绑定(连 NameServer 9876,走 remoting),早已停止更新,接不了 5.x Proxy。所以 Node 侧只有下面两条路。 === 路径 A:用 @grpc/grpc-js 直连 Proxy 的 8081 === 原理:Proxy 对外暴露的就是标准 gRPC 服务 ''apache.rocketmq.v2.MessagingService'',只要有官方 proto,Node 自己也能当客户端。 npm i @grpc/grpc-js @grpc/proto-loader # 从 apache/rocketmq-clients 仓库把 proto 目录拷到本地,例如: # proto/apache/rocketmq/v2/definition.proto # proto/apache/rocketmq/v2/service.proto const grpc = require('@grpc/grpc-js'); const protoLoader = require('@grpc/proto-loader'); const def = protoLoader.loadSync('proto/apache/rocketmq/v2/service.proto', { includeDirs: ['proto'], keepCase: false, // 生成驼峰方法名 sendMessage / receiveMessage longs: String, enums: String, defaults: true, oneofs: true, }); const { apache } = grpc.loadPackageDefinition(def); // 关键:这里填 Proxy 的 8081,不是 NameServer 的 9876 const client = new apache.rocketmq.v2.MessagingService( '192.168.1.10:8081', grpc.credentials.createInsecure(), // 托管版 / 开 TLS 时换成 createSsl(...) { 'grpc.keepalive_time_ms': 30000, 'grpc.keepalive_timeout_ms': 10000 } ); function send(body, tag, keys) { return new Promise((resolve, reject) => { client.sendMessage({ messages: [{ topic: 'topic_order', // 字段名请以你手上的 proto 为准 systemProperties: { tag, keys }, // tag / keys 属于系统属性 body: Buffer.from(body, 'utf8'), }], }, (err, resp) => (err ? reject(err) : resolve(resp.entries))); }); } send('{"orderId":"A1001"}', 'PAID', 'A1001') .then(entries => console.log(JSON.stringify(entries))) .catch(console.error); 动手前必须知道的几点: * **Message 结构动过**:''topic'' / ''tag'' / ''keys'' 是顶层字段还是塞在 ''systemProperties'' 里,5.0 前后调整过,务必对着本地 proto 文件核对字段名,不要照抄旧博客。 * **心跳不能省**:官方 SDK 会周期性发 ''TelemetryCommand''(上报 settings、线程栈)和 ''Heartbeat''。只调 ''SendMessage'' 在部分版本上看着能用,但 Proxy 会把没有存活信号的连接当异常客户端清理,表现为随机超时、偶发失败,生产环境务必补齐。 * **消费端远比发送麻烦**:POP 消费要自己维持 ''ReceiveMessage'' 长轮询、调 ''AckMessage''、管理不可见时间(invisibleDuration)与重试/死信,还要处理连接重建。手写这一套性价比很低。 * **ACL**:开启鉴权后必须在 gRPC metadata 里带签名头(AK/SK 按官方 SDK 的签名算法算),否则 Proxy 直接拒绝请求。 * **升级代价**:官方 proto 不承诺向后兼容,Proxy 升级后自维护的 stub 可能要跟着改 —— 这正是路径 B 存在的理由。 === 路径 B:Go / Python sidecar(生产推荐) === 用官方 Go(''github.com/apache/rocketmq-clients/golang/v5'')或 Python 客户端跑一个极小的网关进程,对外只暴露 HTTP / gRPC,Node 侧调网关: Node 业务进程 --HTTP/gRPC--> sidecar(官方 Go/Python 客户端) --gRPC 8081--> Proxy * 好处:协议、心跳、重试、ACK、死信全交给官方 SDK,Node 只写业务;SDK 升级只动 sidecar,不用维护 proto stub。 * 代价:多一个常驻进程,部署、监控、超时与错误透传要一起设计。 * 什么时候值得:只要这条链路要进生产,就值得。团队里 Go / Java 更熟的话,投入产出比比在 Node 里手写协议高得多。 选型建议:多语言团队优先用 5.x 的 gRPC 客户端,接口在各语言间基本一致;**Node.js 没有官方客户端**,生产链路建议用 Go/Python sidecar 包住协议细节,而不是长期自己维护 gRPC stub;4.x 时代的 Python/Node 客户端维护活跃度较低,新项目不建议依赖。 ===== 八、消息类型对照 ===== ^ 类型 ^ 4.x 写法 ^ 5.x 写法 ^ 注意点 ^ | 普通消息 | ''send / sendAsync / sendOneway'' | 同样三种 | 核心链路用同步发送并配重试,别用单向 | | 顺序消息 | 手动选队列 + Orderly 监听器 | PushConsumer 分区顺序消费 | 只在同一 Queue 内有序,选队列的 key 必须是业务主键 | | 延时消息 | ''setDelayTimeLevel(1~18)'' | ''setDeliveryTimestamp'' | 5.x 可定时到任意时刻 | | 事务消息 | 半消息 + 本地事务回查 | ''beginTransaction / commit / rollback'' | 回查有次数上限,回查逻辑必须能查到真实状态 | | 批量消息 | ''send(List)'' | 客户端批量发送接口 | 同 topic、总大小不超过 4MB;批量不等于事务 | | 过滤 | Tag 过滤(多 Tag 用两条竖线连接)、SQL92 | 同左 | 过滤表达式写在订阅方法里,注意转义 | ===== 九、运维与排错 ===== ''bin/mqadmin'' 在 4.x / 5.x 上通用,常用命令: # 集群与 Topic sh bin/mqadmin clusterList -n 127.0.0.1:9876 sh bin/mqadmin topicList -n 127.0.0.1:9876 -c DefaultCluster sh bin/mqadmin topicRoute -n 127.0.0.1:9876 -t topic_order sh bin/mqadmin updateTopic -n 127.0.0.1:9876 -c DefaultCluster -t topic_order -r 8 -w 8 sh bin/mqadmin deleteTopic -n 127.0.0.1:9876 -c DefaultCluster -t topic_order # 消费情况与位点 sh bin/mqadmin consumerProgress -n 127.0.0.1:9876 -g cg_order sh bin/mqadmin consumerStatus -n 127.0.0.1:9876 -g cg_order sh bin/mqadmin resetOffsetByTime -n 127.0.0.1:9876 -g cg_order -t topic_order -s now # 手工发一条测试消息 sh bin/mqadmin sendMessage -n 127.0.0.1:9876 -t topic_order -p "hello" 5.x 还可以配合 Proxy 的管理接口和 rocketmq-dashboard 使用。 排查清单(按出现频率排序): * ''sendDefaultImpl call timeout'':客户端到 Broker 的 **10911** 不通,多为安全组/防火墙未放行,或 ''brokerIP1'' 填了内网地址。 * ''No route info of this topic'':NameServer 上没有该 Topic 的路由。生产环境 ''autoCreateTopicEnable=false'' 时需先 ''updateTopic'' 手工创建。 * 4.x 客户端连 5.x 连不上:Proxy 未保留 remoting 兼容,或客户端仍指向已关闭的 9876。 * 5.x 新客户端连不上:''endpoints'' 必须填 Proxy 的 **8081**,填 9876 一定失败。 * Broker 启动即 OOM:默认 ''runbroker.sh'' 需要大内存,小机器必须调小 ''-Xmx''。 * 消费堆积:看 ''consumerProgress'' 的 diff;先确认消费者是否在线(''consumerStatus'' 里的 ''notOnline''),再考虑加实例(实例数超过队列数没有意义)。 * 消息重复:默认至少一次语义,别指望 MQ 去重,消费端必须幂等。 ===== 十、可靠性要点 ===== * **刷盘**:''flushDiskType=ASYNC_FLUSH'' 性能好、断电可能丢少量消息;''SYNC_FLUSH'' 更安全但 TPS 下降。 * **主从**:''ASYNC_MASTER'' 主挂掉可能有少量未同步消息丢失;''SYNC_MASTER''(同步双写)不丢消息但 RT 上升。5.x 可用 DLedger / Controller 模式做主备自动切换。 * **消费重试**:并发消费失败会重试(默认 16 次),消息进入 ''%RETRY%消费组名'' 的 Topic,以递增间隔重投;超过次数后进入 ''%DLQ%消费组名'' 死信队列,死信必须有人工处理入口。 * **幂等**:用业务唯一 ID(订单号 + 事件类型)做 Redis 或数据库唯一键去重,这是应对「至少一次」的标准做法。 * **不丢消息的三道关**:生产端同步发送 + 失败重试;Broker 端同步刷盘 / 主从可靠;消费端处理成功才 ack。 * **顺序**:顺序消费要求消息进同一队列且消费端单线程(''MessageListenerOrderly'');生产端按业务键 hash 选队列,扩容队列会破坏既有顺序。 ===== 参考 ===== * 官方文档:https://rocketmq.apache.org/docs/ * 官方示例代码:https://github.com/apache/rocketmq/tree/develop/example * 5.x 多语言客户端:https://github.com/apache/rocketmq-clients * gRPC 协议定义(proto,Node 自建客户端要取这里的文件):https://github.com/apache/rocketmq-clients/tree/master/proto * Node.js 4.x 社区绑定(仅 remoting,连 9876,长期未更新):https://github.com/apache/rocketmq-client-nodejs * Spring 集成:https://github.com/apache/rocketmq-spring