RocketMQ 安装操作手册（Ubuntu + Docker 版）

weixin_40912009

978人浏览 · 2025-11-28 09:53:37

weixin_40912009 · 2025-11-28 09:53:37 发布

RocketMQ 安装操作手册（Ubuntu + Docker 版）

文档说明

项目	内容
适用环境	Ubuntu 20.04/22.04 LTS（64 位）
安装方式	Docker 容器化部署（免手动配置 Java 环境）
适配版本	RocketMQ 5.2.0（稳定版）
核心特性	国内镜像加速、公网可访问、一键启停、数据持久化
服务器要求	最低配置：1C2G，推荐配置：2C4G+（根据业务调整 JVM 内存）
公网 IP 示例	x.x.x.x.x（实际使用时替换为自身服务器公网 IP）

一、前置准备

1.1 环境检查

bash

运行

# 检查系统版本（需 Ubuntu 20.04+/22.04+）
lsb_release -a

# 检查内核版本（需 5.4+）
uname -r

1.2 安装 Docker 及 Docker Compose

1.2.1 卸载旧版本（若已安装）

bash

运行

sudo apt remove -y docker docker-engine docker.io containerd runc

1.2.2 安装依赖包

bash

运行

sudo apt update && sudo apt install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

1.2.3 配置国内 Docker 源（中科大源，避免国外连接超时）

bash

运行

# 添加源 GPG 密钥
curl -fsSL https://mirrors.ustc.edu.cn/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/docker-ustc.gpg

# 配置 apt 仓库
echo "deb [arch=$(dpkg --print-architecture)] https://mirrors.ustc.edu.cn/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

1.2.4 安装 Docker 核心组件

bash

运行

sudo apt update && sudo apt install -y \
    docker-ce \
    docker-ce-cli \
    containerd.io \
    docker-compose-plugin

1.2.5 启动 Docker 并设置开机自启

bash

运行

# 启动 Docker 服务
sudo systemctl start docker

# 设置开机自启
sudo systemctl enable docker

# 验证安装（显示版本即成功）
docker --version
docker compose version

1.3 配置国内镜像加速器（轩辕云）

bash

运行

# 创建 Docker 配置目录
sudo mkdir -p /etc/docker

# 写入加速器配置（替换为轩辕云加速地址）
sudo tee /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://mirrors.ustc.edu.cn/dockerhub/"
  ]
}
EOF

# 重启 Docker 生效
sudo systemctl daemon-reload && sudo systemctl restart docker

# 验证加速器配置
docker info | grep "Registry Mirrors"

二、RocketMQ 部署步骤

2.1 创建部署目录（数据持久化）

bash

运行

# 创建主目录及子目录（日志、存储、配置）
mkdir -p /opt/rocketmq/{namesrv/logs,broker/{logs,store,conf}}

# 进入工作目录（后续操作均在此执行）
cd /opt/rocketmq

2.2 编写 Docker Compose 配置文件（无注释纯配置）

bash

运行

cat > docker-compose.yml << 'EOF'
services:
  namesrv:
    image: apache/rocketmq:5.2.0
    container_name: rocketmq-namesrv
    ports:
      - "9876:9876"
    volumes:
      - ./namesrv/logs:/home/rocketmq/logs
    command: sh mqnamesrv
    networks:
      - rocketmq-net
    restart: always
  broker:
    image: apache/rocketmq:5.2.0
    container_name: rocketmq-broker
    ports:
      - "10909:10909"
      - "10911:10911"
      - "10912:10912"
    volumes:
      - ./broker/logs:/home/rocketmq/logs
      - ./broker/store:/home/rocketmq/store
      - ./broker/conf:/home/rocketmq/conf
    environment:
      - NAMESRV_ADDR=namesrv:9876
      - BROKER_IP1=你的服务器IP
      - JAVA_OPT=-server -Xms512m -Xmx512m
    command: sh mqbroker -c /home/rocketmq/conf/broker.conf
    depends_on:
      - namesrv
    networks:
      - rocketmq-net
    restart: always
networks:
  rocketmq-net:
    driver: bridge
EOF

2.3 编写 Broker 配置文件（无注释纯配置）

bash

运行

cat > ./broker/conf/broker.conf << 'EOF'
brokerClusterName=DefaultCluster
brokerName=broker-a
brokerId=0
deleteWhen=04
fileReservedTime=48
brokerRole=ASYNC_MASTER
flushDiskType=ASYNC_FLUSH
autoCreateTopicEnable=true
listenPort=10911
namesrvAddr=namesrv:9876
brokerIP1=你的服务器IP
EOF

2.4 启动 RocketMQ 服务

bash

运行

# 后台启动服务
sudo docker compose up -d

# 查看容器状态（Up 表示正常运行）
sudo docker compose ps

三、端口开放配置

3.1 服务器防火墙（UFW）开放端口

bash

运行

# 开放核心端口
sudo ufw allow 9876/tcp   # NameServer 端口
sudo ufw allow 10909/tcp  # Broker TCP 通信端口
sudo ufw allow 10911/tcp  # Broker 服务端口
sudo ufw allow 10912/tcp  # Broker 主从同步端口

# 重启防火墙生效
sudo ufw reload

# 查看开放状态
sudo ufw status

3.2 云服务器安全组配置（华为云 ECS 示例）

登录华为云控制台，进入 ECS 实例详情页；
找到「安全组」→「配置规则」→「入方向规则」→「添加规则」；
按以下参数添加规则（允许公网访问）：

协议	端口范围	源地址	描述
TCP	9876	0.0.0.0/0	RocketMQ NameServer
TCP	10909	0.0.0.0/0	Broker TCP 通信
TCP	10911	0.0.0.0/0	Broker 服务端口
TCP	10912	0.0.0.0/0	Broker 主从同步

保存规则，等待 1-2 分钟生效。

四、服务验证

4.1 容器状态验证

bash

运行

sudo docker compose ps

预期输出：

plaintext

NAME               IMAGE                   COMMAND                  SERVICE   CREATED         STATUS         PORTS
rocketmq-broker    apache/rocketmq:5.2.0   "./docker-entrypoint…"   broker    30 seconds ago  Up 28 seconds   0.0.0.0:10909->10909/tcp, 0.0.0.0:10911->10911/tcp, 0.0.0.0:10912->10912/tcp
rocketmq-namesrv   apache/rocketmq:5.2.0   "./docker-entrypoint…"   namesrv   30 seconds ago  Up 29 seconds   0.0.0.0:9876->9876/tcp

4.2 日志验证

bash

运行

# 查看 NameServer 日志（无报错即正常）
sudo docker logs rocketmq-namesrv

# 查看 Broker 日志（关键看启动成功提示）
sudo docker logs rocketmq-broker

Broker 成功启动标识：

plaintext

The broker[broker-a, 你的服务器IP:10911] boot success. serializeType=JSON

4.3 功能测试（消息发送 / 接收）

bash

运行

# 进入 Broker 容器
sudo docker exec -it rocketmq-broker /bin/sh

# 进入工具目录
cd /home/rocketmq/bin

# 发送消息（生产者）
sh tools.sh org.apache.rocketmq.example.quickstart.Producer
# 成功提示：SendResult [sendStatus=SEND_OK, msgId=...]

# 接收消息（消费者）
sh tools.sh org.apache.rocketmq.example.quickstart.Consumer
# 成功提示：ConsumeMessageThread_%d Receive New Messages: [MessageExt...]

# 退出容器
exit

4.4 公网连通性验证（本地电脑）

bash

运行

# 测试 NameServer 端口（返回乱码即通）
curl 你的服务器IP:9876

# 或使用 telnet 测试（需本地安装 telnet）
telnet 你的服务器IP 9876

五、常用操作命令

5.1 服务启停命令

bash

运行

# 启动服务
sudo docker compose up -d

# 停止服务（保留容器和数据）
sudo docker compose stop

# 停止服务并删除容器（保留数据）
sudo docker compose down

# 重启服务
sudo docker compose restart

5.2 日志查看命令

bash

运行

# 实时查看 Broker 日志
sudo docker logs -f rocketmq-broker

# 查看 NameServer 最新 100 行日志
sudo docker logs --tail 100 rocketmq-namesrv

5.3 数据管理命令

bash

运行

# 查看消息存储目录
ls -l /opt/rocketmq/broker/store

# 清理日志（需停止服务后执行）
sudo docker compose stop
sudo rm -rf /opt/rocketmq/namesrv/logs/*
sudo rm -rf /opt/rocketmq/broker/logs/*

六、常见问题排查

6.1 Broker 容器反复重启

现象

rocketmq-broker 状态显示 Restarting (1) X seconds ago

解决步骤

查看错误日志：
```
sudo docker logs rocketmq-broker
```
常见错误及修复：
- 错误 1：Error: Could not find or load main class "-server" → JVM 参数格式错误，重新执行 2.2 步骤生成配置文件；
- 错误 2：The Name Server Address illegal → 配置文件含注释 / 乱码，重新执行 2.3 步骤生成纯配置；
- 错误 3：端口占用 → 检查端口是否被其他服务占用：sudo lsof -i:10911，kill 占用进程或修改端口。

6.2 公网无法连接

排查步骤

检查服务器防火墙端口：sudo ufw status；
检查云安全组规则是否添加正确；
验证容器端口映射：sudo docker port rocketmq-broker；
测试服务器内部连通性：curl 127.0.0.1:9876（通则说明容器正常，问题在网络配置）。

6.3 消息发送失败

常见原因

NameServer 地址配置错误 → 客户端需填写你的服务器IP:9876（你的服务器IP:9876端口）；
主题未创建 → 配置文件 autoCreateTopicEnable=true 已开启，可自动创建；
Broker 未连接到 NameServer → 重启 Broker：sudo docker compose restart broker。

错误：No topic route info in name server for the topic: canal-topic →：主题未创建，手动创建主题

# 1. 进入 RocketMQ Broker 容器
sudo docker exec -it rocketmq-broker /bin/sh

# 2. 进入 RocketMQ 工具目录
cd /home/rocketmq/bin

# 执行创建 Topic 命令：
sh mqadmin updateTopic -n 你的服务器IP:9876 -t canal-topic -b 你的服务器IP:10911 -r 4 -w 4

# 验证 Topic 是否创建成功：
sh mqadmin topicList -n 你的服务器IP:9876

# 参数说明：
# -n：NameServer 地址（你的是 你的服务器IP:9876，正确）；
# -t：Topic 名称（必须和 Canal 配置一致：canal-topic）；
# -b：Broker 地址（你的服务器IP:10911，正确）；
# -r 4：读队列数（默认 4，和日志中显示的一致）；
# -w 4：写队列数（默认 4，和日志中显示的一致）；

七、客户端连接示例（Java）

7.1 Maven 依赖

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

7.2 生产者示例

java 运行

import org.apache.rocketmq.client.producer.DefaultMQProducer;
import org.apache.rocketmq.client.producer.SendResult;
import org.apache.rocketmq.common.message.Message;

public class RocketMQProducer {
    public static void main(String[] args) throws Exception {
        // 1. 创建生产者实例
        DefaultMQProducer producer = new DefaultMQProducer("test_producer_group");
        
        // 2. 配置 NameServer 地址
        producer.setNamesrvAddr("你的服务器IP:9876");
        
        // 3. 启动生产者
        producer.start();
        
        // 4. 发送消息
        Message message = new Message(
            "test_topic",  // 主题名
            "test_tag",    // 标签
            "Hello RocketMQ".getBytes()  // 消息内容
        );
        SendResult result = producer.send(message);
        System.out.println("消息发送成功：" + result);
        
        // 5. 关闭生产者（生产环境按需关闭）
        producer.shutdown();
    }
}

7.3 消费者示例

java 运行

import org.apache.rocketmq.client.consumer.DefaultMQPushConsumer;
import org.apache.rocketmq.client.consumer.listener.ConsumeConcurrentlyStatus;
import org.apache.rocketmq.client.consumer.listener.MessageListenerConcurrently;
import org.apache.rocketmq.common.message.MessageExt;

import java.util.List;

public class RocketMQConsumer {
    public static void main(String[] args) throws Exception {
        // 1. 创建消费者实例
        DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("test_consumer_group");
        
        // 2. 配置 NameServer 地址
        consumer.setNamesrvAddr("你的服务器IP:9876");
        
        // 3. 订阅主题（* 表示所有标签）
        consumer.subscribe("test_topic", "*");
        
        // 4. 注册消息监听
        consumer.registerMessageListener((MessageListenerConcurrently) (msgs, context) -> {
            for (MessageExt msg : msgs) {
                System.out.println("接收消息：" + new String(msg.getBody()));
            }
            // 返回消费成功状态
            return ConsumeConcurrentlyStatus.CONSUME_SUCCESS;
        });
        
        // 5. 启动消费者
        consumer.start();
        System.out.println("消费者启动成功，等待接收消息...");
    }
}

7.4 微服务客户端连接失败

现象：java.lang.ClassNotFoundException: org.apache.rocketmq.common.protocol.heartbeat.MessageModel
原因：RocketMQ 依赖版本不兼容 + 核心类缺失

解决步骤：

错误提示：java.lang.ClassNotFoundException: org.apache.rocketmq.common.protocol.heartbeat.MessageModel

1. 修改 pom.xml 依赖配置
找到项目中 mall4cloud-search 模块的 pom.xml，调整 RocketMQ 相关依赖：
xml
<!-- 移除旧的 rocketmq-client 直接依赖（如果有），由 starter 自动管理 -->
<!-- 保留并升级 rocketmq-spring-boot-starter 版本 -->
<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter</artifactId>
    <!-- 升级到兼容 RocketMQ 5.x 的版本（2.3.0+ 均支持 5.x） -->
    <version>2.3.0</version>
</dependency>

<!-- 可选：如果项目中单独引入了 rocketmq-client，确保版本与 starter 兼容 -->
<!-- 若未单独引入，无需添加（starter 已包含兼容版本的 client） -->
<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-client</artifactId>
    <version>5.3.1</version> <!-- 与 starter 2.3.0 兼容，无需修改 -->
</dependency>

2. 清理 Maven 缓存 + 重新构建
执行 Maven 清理命令（IDEA 中可直接点击 Maven -> Clean）：
bash
运行
mvn clean
重新下载依赖并构建（点击 Maven -> Install）：
bash
运行
mvn install -U
-U 参数强制更新快照依赖，避免缓存导致的依赖下载不完整。

3. 验证依赖是否加载成功
打开 IDEA 的 External Libraries，查看 rocketmq-spring-boot-starter-2.3.0.jar 下是否包含 org.apache.rocketmq.common.protocol.heartbeat.MessageModel 类（可通过搜索类名确认）。
若仍缺失，右键项目 → Maven → Reload Project 强制刷新依赖。
备选方案：降级 RocketMQ 到 4.x（兼容旧版 starter）
如果不想升级 starter，可将 RocketMQ 客户端降级到 4.x 版本（starter 2.2.3 适配 RocketMQ 4.9.x）：
xml
<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter</artifactId>
    <version>2.2.3</version> <!-- 保留旧 starter 版本 -->
</dependency>
<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-client</artifactId>
    <version>4.9.7</version> <!-- 降级 client 到 4.x 兼容版本 -->
</dependency>
同样执行 mvn clean install -U 重新构建。
额外检查：排除依赖冲突（若仍报错）
如果调整版本后仍提示类缺失，可能是其他依赖引入了冲突的 RocketMQ 旧版本，需在 starter 中排除冲突：
xml
<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter</artifactId>
    <version>2.3.0</version>
    <exclusions>
        <!-- 排除冲突的旧版 client -->
        <exclusion>
            <groupId>org.apache.rocketmq</groupId>
            <artifactId>rocketmq-client</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<!-- 手动引入指定版本的 client -->
<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-client</artifactId>
    <version>5.3.1</version>
</dependency>
最终验证步骤
完成依赖调整后，执行 mvn clean install -U 构建项目；
重启 mall4cloud-search 服务；
若启动日志中无 ClassNotFoundException，且出现 RocketMQ consumer started 相关日志，说明依赖问题已解决。
关键提醒
RocketMQ 版本对应关系：starter 2.2.x 适配 4.x client，starter 2.3.x+ 适配 5.x client；
避免直接引入多个版本的 RocketMQ 依赖，会导致类加载冲突；
若使用 Docker 部署的 RocketMQ 是 5.x 版本，优先选择方案 1（升级 starter），避免版本不兼容导致的连接失败。

八、注意事项

配置文件禁忌：禁止在 docker-compose.yml 和 broker.conf 中添加任何注释（# 开头内容），避免解析错误；
磁盘空间：消息存储目录 /opt/rocketmq/broker/store 需预留足够空间，建议不低于 20GB；
JVM 内存调整：根据服务器配置修改 JAVA_OPT 参数（如 4C8G 服务器可改为 -Xms2g -Xmx2g -Xmn1g）；
生产环境优化：关闭 autoCreateTopicEnable=true，提前手动创建主题；开启主从复制提升可用性；
备份策略：定期备份 /opt/rocketmq/broker/store 目录，避免数据丢失；
控制台部署：如需可视化管理，可部署 rocketmq-dashboard 镜像：
```
sudo docker run -d -p 8080:8080 -e "NAMESRV_ADDR=你的服务器IP:9876" apacherocketmq/rocketmq-dashboard:latest
```
访问地址：http://服务器IP:8080。

九、参考文档

亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

亚马逊云科技技术品牌专区

所有评论(0)

查看更多评论

weixin_40912009

@weixin_40912009

已为社区贡献1条内容

RocketMQ 安装操作手册（Ubuntu + Docker 版）

weixin_40912009

RocketMQ 安装操作手册（Ubuntu + Docker 版）

文档说明

一、前置准备

1.1 环境检查

1.2 安装 Docker 及 Docker Compose

1.2.1 卸载旧版本（若已安装）

1.2.2 安装依赖包

1.2.3 配置国内 Docker 源（中科大源，避免国外连接超时）

1.2.4 安装 Docker 核心组件

1.2.5 启动 Docker 并设置开机自启

1.3 配置国内镜像加速器（轩辕云）

二、RocketMQ 部署步骤

2.1 创建部署目录（数据持久化）

2.2 编写 Docker Compose 配置文件（无注释纯配置）

2.3 编写 Broker 配置文件（无注释纯配置）

2.4 启动 RocketMQ 服务

三、端口开放配置

3.1 服务器防火墙（UFW）开放端口

3.2 云服务器安全组配置（华为云 ECS 示例）

四、服务验证

4.1 容器状态验证

4.2 日志验证

4.3 功能测试（消息发送 / 接收）

4.4 公网连通性验证（本地电脑）

五、常用操作命令

5.1 服务启停命令

5.2 日志查看命令

5.3 数据管理命令

六、常见问题排查

6.1 Broker 容器反复重启

现象

解决步骤

6.2 公网无法连接

排查步骤

6.3 消息发送失败

常见原因

七、客户端连接示例（Java）

7.1 Maven 依赖

7.2 生产者示例

7.3 消费者示例

7.4 微服务客户端连接失败

八、注意事项

九、参考文档

所有评论(0)

温馨提示：您尚未绑定手机号

weixin_40912009