安装部署

本章节介绍如何在本地快速部署 RocketMQ，以及生产环境的集群部署方案。

环境要求

操作系统要求

• 64 位操作系统
• 推荐 Linux/Unix/macOS
• Windows 系统也可运行，但生产环境推荐 Linux

软件要求

• JDK：JDK 1.8 或更高版本
• Maven：3.6+（源码编译需要）
• 内存：至少 4GB 可用内存

验证 Java 环境：

java -version
# 输出类似：
# java version "1.8.0_XXX"
# Java(TM) SE Runtime Environment (build 1.8.0_XXX-bXX)

快速安装（二进制包）

1. 下载安装包

从官方网站下载二进制包：

# 下载 RocketMQ 5.3.2
wget https://archive.apache.org/dist/rocketmq/5.3.2/rocketmq-all-5.3.2-bin-release.zip

# 解压
unzip rocketmq-all-5.3.2-bin-release.zip
cd rocketmq-all-5.3.2-bin-release

2. 目录结构

rocketmq-all-5.3.2-bin-release/
├── bin/              # 启动脚本
│   ├── mqnamesrv     # NameServer 启动脚本
│   ├── mqbroker      # Broker 启动脚本
│   ├── mqadmin       # 管理命令
│   └── tools.sh      # 工具脚本
├── conf/             # 配置文件
│   ├── broker.conf   # Broker 配置
│   └── namesrv.conf  # NameServer 配置
├── lib/              # 依赖库
└── logs/             # 日志目录（运行后生成）

3. 调整内存参数（可选）

如果开发环境内存有限，可以调整 JVM 参数：

# 编辑 bin/runserver.sh（NameServer）
# 编辑 bin/runbroker.sh（Broker）
# 修改 JAVA_OPT 中的内存参数

# 示例：将 -Xms4g -Xmx4g 改为 -Xms512m -Xmx512m

启动单机版

1. 启动 NameServer

NameServer 是路由注册中心，类似注册中心，必须首先启动：

# 启动 NameServer（后台运行）
nohup sh bin/mqnamesrv &

# 查看启动日志
tail -f ~/logs/rocketmqlogs/namesrv.log

看到以下日志表示启动成功：

The Name Server boot success. serializeType=JSON

2. 启动 Broker（Local 模式）

RocketMQ 5.x 支持 Local 模式，Broker 和 Proxy 同进程运行：

# 启动 Broker（Local 模式，含 Proxy）
nohup sh bin/mqbroker -n localhost:9876 --enable-proxy &

# 查看启动日志
tail -f ~/logs/rocketmqlogs/proxy.log

看到以下日志表示启动成功：

The broker[broker-a,192.168.1.100:10911] boot success.

3. 验证服务状态

# 查看 NameServer 进程
ps -ef | grep namesrv

# 查看 Broker 进程
ps -ef | grep broker

# 查看端口监听
netstat -tlnp | grep -E '9876|10911|8081'

默认端口说明：

端口	服务	说明
9876	NameServer	路由注册中心端口
10911	Broker	Broker 服务端口
8081	Proxy	5.x 新增的 gRPC 端口

测试消息收发

使用命令行工具测试

设置 NameServer 地址：

export NAMESRV_ADDR=localhost:9876

发送测试消息：

sh bin/tools.sh org.apache.rocketmq.example.quickstart.Producer

输出示例：

SendResult [sendStatus=SEND_OK, msgId=AC11000100002A9F0000000000000000, ...

消费测试消息：

sh bin/tools.sh org.apache.rocketmq.example.quickstart.Consumer

输出示例：

ConsumeMessageThread_1 Receive New Messages: [MessageExt [queueId=0, ...

使用 Java SDK 测试

1. 添加 Maven 依赖

<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-client-java</artifactId>
    <version>5.0.7</version>
</dependency>

2. 创建 Topic

使用管理工具创建 Topic：

sh bin/mqadmin updatetopic -n localhost:9876 -t TestTopic -c DefaultCluster

3. 发送消息

import org.apache.rocketmq.client.apis.*;
import org.apache.rocketmq.client.apis.message.Message;
import org.apache.rocketmq.client.apis.producer.Producer;
import org.apache.rocketmq.client.apis.producer.SendReceipt;

public class ProducerDemo {
    public static void main(String[] args) throws Exception {
        // 创建客户端配置
        ClientServiceProvider provider = ClientServiceProvider.loadService();
        ClientConfiguration config = ClientConfiguration.newBuilder()
                .setEndpoints("localhost:8081")  // Proxy 地址
                .build();
        
        // 创建生产者
        Producer producer = provider.newProducerBuilder()
                .setClientConfiguration(config)
                .setTopics("TestTopic")
                .build();
        
        // 构建消息
        Message message = provider.newMessageBuilder()
                .setTopic("TestTopic")
                .setTag("TagA")
                .setKeys("order_001")
                .setBody("Hello RocketMQ".getBytes())
                .build();
        
        // 发送消息
        SendReceipt receipt = producer.send(message);
        System.out.println("消息发送成功，MessageId: " + receipt.getMessageId());
        
        producer.close();
    }
}

4. 消费消息

import org.apache.rocketmq.client.apis.*;
import org.apache.rocketmq.client.apis.consumer.*;
import java.util.Collections;

public class ConsumerDemo {
    public static void main(String[] args) throws Exception {
        ClientServiceProvider provider = ClientServiceProvider.loadService();
        ClientConfiguration config = ClientConfiguration.newBuilder()
                .setEndpoints("localhost:8081")
                .build();
        
        // 创建 PushConsumer
        PushConsumer consumer = provider.newPushConsumerBuilder()
                .setClientConfiguration(config)
                .setConsumerGroup("TestGroup")
                .setSubscriptionExpressions(Collections.singletonMap(
                        "TestTopic",
                        new FilterExpression("*", FilterExpressionType.TAG)
                ))
                .setMessageListener(messageView -> {
                    System.out.println("收到消息: " + messageView.getMessageId());
                    return ConsumeResult.SUCCESS;
                })
                .build();
        
        // 保持运行
        Thread.sleep(Long.MAX_VALUE);
    }
}

关闭服务

测试完成后，按顺序关闭服务：

# 先关闭 Broker
sh bin/mqshutdown broker

# 再关闭 NameServer
sh bin/mqshutdown namesrv

Docker 部署

使用 Docker Compose

创建 docker-compose.yml：

version: '3'

services:
  namesrv:
    image: apache/rocketmq:5.3.2
    container_name: rmqnamesrv
    ports:
      - 9876:9876
    command: sh mqnamesrv
    networks:
      - rocketmq

  broker:
    image: apache/rocketmq:5.3.2
    container_name: rmqbroker
    ports:
      - 10909:10909
      - 10911:10911
      - 8081:8081
    environment:
      - NAMESRV_ADDR=namesrv:9876
    command: sh mqbroker -n namesrv:9876 --enable-proxy
    depends_on:
      - namesrv
    networks:
      - rocketmq

  dashboard:
    image: apacherocketmq/rocketmq-dashboard:latest
    container_name: rmqdashboard
    ports:
      - 8180:8080
    environment:
      - rocketmq.config.namesrvAddr=namesrv:9876
    depends_on:
      - namesrv
    networks:
      - rocketmq

networks:
  rocketmq:
    driver: bridge

启动服务：

docker-compose up -d

访问 Dashboard：http://localhost:8180

单容器快速启动

# 启动 NameServer
docker run -d --name rmqnamesrv \
  -p 9876:9876 \
  apache/rocketmq:5.3.2 \
  sh mqnamesrv

# 启动 Broker
docker run -d --name rmqbroker \
  -p 10911:10911 -p 8081:8081 \
  -e "NAMESRV_ADDR=host.docker.internal:9876" \
  apache/rocketmq:5.3.2 \
  sh mqbroker -n host.docker.internal:9876 --enable-proxy

常见问题

1. 启动失败：内存不足

问题：`Java HotSpot(TM) 64-Bit Server VM warning: INFO: os::commit_memory(0x000000...)

解决：调整 JVM 内存参数

# 编辑 bin/runbroker.sh
# 找到 JAVA_OPT，修改内存参数
JAVA_OPT="${JAVA_OPT} -Xms512m -Xmx512m"

2. 连接失败：NameServer 地址错误

问题：connect to null failed

解决：确保正确设置 NameServer 地址

# 方式1：环境变量
export NAMESRV_ADDR=localhost:9876

# 方式2：启动参数
sh bin/mqbroker -n localhost:9876

3. 端口冲突

问题：Address already in use

解决：检查端口占用，修改配置文件中的端口

# 查看端口占用
netstat -tlnp | grep 9876

# 修改 conf/broker.conf 中的端口配置
listenPort=10911

4. Docker 容器无法连接宿主机

问题：容器内无法连接宿主机的 NameServer

解决：

# macOS/Windows 使用 host.docker.internal
-e "NAMESRV_ADDR=host.docker.internal:9876"

# Linux 使用宿主机 IP 或 --network host
--network host

小结

本节介绍了：

1. 环境要求：JDK 1.8+、操作系统要求
2. 快速安装：二进制包下载和解压
3. 单机部署：启动 NameServer 和 Broker
4. 测试验证：命令行工具和 Java SDK 测试
5. Docker 部署：使用 Docker Compose 快速部署
6. 常见问题：内存不足、端口冲突等问题的解决

延伸阅读

• RocketMQ 官方部署文档
• RocketMQ Docker Hub