RocketMQ 5.3.0 ARM64 架构安装部署指南

背景说明
环境要求
[1. 系统环境准备](#1. 系统环境准备)
[2. Java 环境配置](#2. Java 环境配置)
[3. Maven 安装配置](#3. Maven 安装配置)
[4. RocketMQ 源码编译](#4. RocketMQ 源码编译)
[5. Docker 镜像制作](#5. Docker 镜像制作)
[6. 部署配置](#6. 部署配置)
[7. ARM64 架构验证测试](#7. ARM64 架构验证测试)
[8. 常见问题解决](#8. 常见问题解决)

背景说明

安全漏洞: CVE-2024-23321（2024年7月22日公布）
升级要求: 将 RocketMQ 升级至 5.3.0 版本
特殊需求: 由于官方未提供 ARM64 架构的 Docker 镜像，需要自行编译打包
构建方式: 支持在 x86_64 系统上跨平台构建 ARM64 镜像

环境要求

目标运行环境

操作系统: 麒麟KYLINOS (ARM64/aarch64)
CPU 架构: ARM64
内存: 建议 8GB 以上
磁盘空间: 至少 20GB 可用空间
Docker: 20.10.0 或更高版本

构建环境（可以是不同架构）

操作系统: Ubuntu/CentOS/
CPU 架构: x86_64 或 ARM64
Docker: 20.10.0 或更高版本（需支持 buildx）
网络: 能够访问 Maven 中央仓库和 Docker Hub

1. 系统环境准备

1.1 更新系统包

bash 复制代码

# 更新软件包列表
sudo apt update

# 升级已安装的软件包
sudo apt upgrade -y

# 安装必要的工具
sudo apt install -y wget curl unzip git build-essential

1.2 检查系统架构

bash 复制代码

# 检查系统架构，应该显示 aarch64 或 arm64
uname -m

# 查看详细的系统信息
lscpu | grep Architecture

# 查看系统版本
lsb_release -a

2. Java 环境配置

2.1 安装 OpenJDK 8

bash 复制代码

# 安装 OpenJDK 8
sudo apt install -y openjdk-8-jdk

# 安装完成后验证
java -version
javac -version

2.2 配置 JAVA_HOME 环境变量

bash 复制代码

# 查找 Java 安装路径
sudo update-alternatives --config java

# 编辑环境变量文件
sudo nano /etc/environment

在文件末尾添加：

复制代码

JAVA_HOME="/usr/lib/jvm/java-8-openjdk-arm64"
# 编辑 profile 文件
sudo nano /etc/profile

在文件末尾添加：

bash 复制代码

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-arm64
export PATH=$PATH:$JAVA_HOME/bin

2.3 使环境变量生效

bash 复制代码

# 重新加载环境变量
source /etc/environment
source /etc/profile

# 验证环境变量
echo $JAVA_HOME
java -version

3. Maven 安装配置

3.1 安装 Maven

bash 复制代码

# 安装 Maven
sudo apt install -y maven

# 验证安装
mvn -version

3.2 配置 Maven（可选）

创建 Maven 配置文件以使用国内镜像（提高下载速度）：

bash 复制代码

# 创建 .m2 目录
mkdir -p ~/.m2

# 创建 settings.xml
nano ~/.m2/settings.xml

添加以下内容：

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
          http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <mirrors>
        <mirror>
            <id>aliyun</id>
            <mirrorOf>central</mirrorOf>
            <name>Aliyun Maven Mirror</name>
            <url>https://maven.aliyun.com/repository/public</url>
        </mirror>
    </mirrors>
</settings>

4. RocketMQ 源码编译

注意：源码编译可以在任何架构的系统上进行，编译产物是 Java 字节码，可以跨平台运行。

4.1 下载源码

bash 复制代码

# 创建工作目录
mkdir -p ~/rocketmq-build
cd ~/rocketmq-build

# 下载 RocketMQ 5.3.0 源码
wget https://archive.apache.org/dist/rocketmq/5.3.0/rocketmq-all-5.3.0-source-release.zip

# 如果 wget 下载失败，可以使用 curl
# curl -O https://archive.apache.org/dist/rocketmq/5.3.0/rocketmq-all-5.3.0-source-release.zip

# 解压源码
unzip rocketmq-all-5.3.0-source-release.zip
cd rocketmq-all-5.3.0-source-release

4.2 编译源码

bash 复制代码

# 设置 Maven 内存参数（防止编译时内存不足）
export MAVEN_OPTS="-Xmx3072m"

# 开始编译（耗时较长，约30-60分钟）
mvn -Prelease-all -DskipTests -Dspotbugs.skip=true clean install -U

# 查看编译结果
ls -la distribution/target/rocketmq-5.3.0/rocketmq-5.3.0/

4.3 验证编译结果

bash 复制代码

# 进入编译产物目录
cd distribution/target/rocketmq-5.3.0/rocketmq-5.3.0

# 查看目录结构
tree -L 2

# 检查二进制文件
file bin/mqnamesrv
file bin/mqbroker

5. Docker 镜像制作

5.1 安装 Docker（如未安装）

在 Ubuntu 20.04.5 LTS 系统上安装 Docker CE 26.1.4 完整指南-CSDN博客

5.1.1 配置 Docker 多平台构建支持（跨平台构建必需）

如果你的构建系统不是 ARM64 架构，但需要构建 ARM64 镜像，需要配置 Docker 的多平台构建支持：

bash 复制代码

# 安装 QEMU 用户态模拟器
sudo apt-get update
sudo apt-get install -y qemu-user-static

# 检查是否支持多平台
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# 创建并使用新的 buildx 构建器
docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap

# 查看支持的平台
docker buildx ls

5.2 拉取基础镜像

方式一：自动拉取对应架构的镜像（推荐）

bash 复制代码

# Docker 会自动根据你的系统架构拉取对应的镜像
docker pull dyrnq/rocketmq:4.9.7

# 验证镜像架构
docker inspect dyrnq/rocketmq:4.9.7 | grep Architecture

方式二：明确指定 ARM64 架构（跨平台构建时使用）

bash 复制代码

# 明确拉取 ARM64 版本
docker pull --platform linux/arm64 dyrnq/rocketmq:4.9.7

# 查看镜像的多架构支持情况
docker manifest inspect dyrnq/rocketmq:4.9.7

# 验证拉取的镜像架构
docker inspect dyrnq/rocketmq:4.9.7 | grep -A 5 Architecture

5.3 创建新镜像

方式一：在 ARM64 系统上直接构建

bash 复制代码

# 启动临时容器
docker run -it --name rocketmq-upgrade dyrnq/rocketmq:4.9.7 /bin/bash

方式二：在非 ARM64 系统上跨平台构建

bash 复制代码

# 使用 --platform 参数指定 ARM64 平台
docker run -it --platform linux/arm64 --name rocketmq-upgrade dyrnq/rocketmq:4.9.7 /bin/bash

在另一个终端中执行：

bash 复制代码

# 复制编译好的 RocketMQ 到容器
docker cp ~/rocketmq-build/rocketmq-all-5.3.0-source-release/distribution/target/rocketmq-5.3.0/rocketmq-5.3.0 rocketmq-upgrade:/home/rocketmq/

# 查看复制结果
docker exec rocketmq-upgrade ls -la /home/rocketmq/

回到容器终端，执行：

bash 复制代码

# 在容器内操作
cd /home/rocketmq

# 备份原有文件（可选）
mkdir -p /tmp/backup
cp -r /opt/rocketmq/* /tmp/backup/

# 清理旧版本
rm -rf /opt/rocketmq/*

# 复制新版本
cp -r /home/rocketmq/rocketmq-5.3.0/* /opt/rocketmq/

# 修改权限
chown -R rocketmq:rocketmq /opt/rocketmq/

# 验证版本
/opt/rocketmq/bin/mqnamesrv -v

# 退出容器
exit

5.4 提交新镜像

bash 复制代码

# 提交容器为新镜像
docker commit rocketmq-upgrade rocketmq:5.3.0-arm64

# 查看新镜像
docker images | grep rocketmq

# 清理临时容器
docker rm rocketmq-upgrade

5.5 创建优化版 Dockerfile（可选）

创建 Dockerfile：

dockerfile 复制代码

FROM rocketmq:5.3.0-arm64
# 更新版本号
ENV ROCKETMQ_VERSION=5.3.0
ENTRYPOINT ["/docker-entrypoint.sh"]
# 如果需要健康检查，添加这部分
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD sh -c 'cd /opt/rocketmq && sh bin/mqadmin clusterList -n localhost:9876' || exit 1

构建优化版镜像：

方式一：在 ARM64 系统上构建

bash 复制代码

docker build -t rocketmq:5.3.0-arm64-optimized .

方式二：跨平台构建（推荐）

bash 复制代码

# 使用 buildx 构建多平台镜像
docker buildx build --platform linux/arm64 -t rocketmq:5.3.0-arm64-optimized .

# 如果需要同时支持多个平台
docker buildx build --platform linux/arm64,linux/amd64 -t rocketmq:5.3.0-multiarch .

# 构建并推送到仓库（需要先 docker login）
docker buildx build --platform linux/arm64 -t your-registry/rocketmq:5.3.0-arm64 --push .

6. 部署配置

6.1 创建配置文件

创建 broker.conf：

bash 复制代码

# 创建配置目录
mkdir -p ~/rocketmq-deploy
cd ~/rocketmq-deploy

# 创建 broker 配置文件
cat > broker.conf << EOF
brokerClusterName = DefaultCluster
brokerName = broker-a
brokerId = 0
deleteWhen = 04
fileReservedTime = 48
brokerRole = ASYNC_MASTER
flushDiskType = ASYNC_FLUSH
brokerIP1 = 0.0.0.0
listenPort = 10911
# 开启自动创建主题
autoCreateTopicEnable = true
# 存储路径
storePathRootDir = /home/rocketmq/store
storePathCommitLog = /home/rocketmq/store/commitlog
storePathConsumeQueue = /home/rocketmq/store/consumequeue
storePathIndex = /home/rocketmq/store/index
storeCheckpoint = /home/rocketmq/store/checkpoint
abortFile = /home/rocketmq/store/abort
EOF

6.2 创建 docker-compose.yml

yaml 复制代码

version: '3.8'

services:
  namesrv:
    image: rocketmq:5.3.0-arm64-optimized
    container_name: rocketmq-namesrv
    restart: always
    mem_limit: "4g"
    cpus: "2"
    volumes:
      - ./namesrv-logs:/home/rocketmq/logs
      - ./namesrv-store:/home/rocketmq/store
    networks:
      - rocketmq
    ports:
      - "9876:9876"
    environment:
      - TZ=Asia/Shanghai
      - MAX_POSSIBLE_HEAP=2048m
      - JAVA_OPT_EXT=-server -Xms512m -Xmx2048m -Xmn1024m
    command: sh mqnamesrv
    healthcheck:
      test: ["CMD", "sh", "-c", "netstat -tnl | grep 9876"]
      interval: 30s
      timeout: 10s
      retries: 3

  broker:
    image: rocketmq:5.3.0-arm64-optimized
    container_name: rocketmq-broker
    depends_on:
      namesrv:
        condition: service_healthy
    restart: always
    mem_limit: "8g"
    cpus: "4"
    volumes:
      - ./broker.conf:/opt/rocketmq/conf/broker.conf:ro
      - ./broker-logs:/home/rocketmq/logs
      - ./broker-store:/home/rocketmq/store
    networks:
      - rocketmq
    ports:
      - "10909:10909"
      - "10911:10911"
      - "10912:10912"
    environment:
      - TZ=Asia/Shanghai
      - NAMESRV_ADDR=namesrv:9876
      - MAX_POSSIBLE_HEAP=4096m
      - JAVA_OPT_EXT=-server -Xms1024m -Xmx4096m -Xmn2048m
    command: sh mqbroker -c /opt/rocketmq/conf/broker.conf

  console:
    image: candice0630/rocketmq-console-ng:2.0
    container_name: rocketmq-console
    depends_on:
      - namesrv
      - broker
    restart: always
    networks:
      - rocketmq
    ports:
      - "19876:8080"
    environment:
      - JAVA_OPTS=-Drocketmq.config.namesrvAddr=namesrv:9876 -Drocketmq.config.isVIPChannel=false
      - TZ=Asia/Shanghai

networks:
  rocketmq:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

6.3 启动服务

bash 复制代码

# 创建必要的目录
mkdir -p {namesrv-logs,namesrv-store,broker-logs,broker-store}

# 设置目录权限
chmod -R 777 {namesrv-logs,namesrv-store,broker-logs,broker-store}

# 启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

7. ARM64 架构验证测试

7.1 验证镜像架构

bash 复制代码

# 检查镜像架构信息
docker inspect rocketmq:5.3.0-arm64-optimized | jq '.[0].Architecture'

# 检查镜像详细信息
docker run --rm rocketmq:5.3.0-arm64-optimized uname -m

# 检查 Java 架构
docker run --rm rocketmq:5.3.0-arm64-optimized java -version 2>&1 | grep -i arm

7.2 功能测试

7.2.1 测试 NameServer

bash 复制代码

# 检查 NameServer 端口
netstat -tlnp | grep 9876

# 测试 NameServer 连接
telnet localhost 9876

# 查看 NameServer 日志
docker logs rocketmq-namesrv | tail -20

7.2.2 测试 Broker

bash 复制代码

# 检查 Broker 状态
docker exec rocketmq-broker sh -c "cd /opt/rocketmq && sh bin/mqadmin clusterList -n localhost:9876"

# 查看 Broker 配置
docker exec rocketmq-broker sh -c "cd /opt/rocketmq && sh bin/mqadmin getBrokerConfig -n localhost:9876 -b localhost:10911"

7.2.3 创建测试主题

bash 复制代码

# 创建测试主题
docker exec rocketmq-broker sh -c "cd /opt/rocketmq && sh bin/mqadmin updateTopic -n localhost:9876 -t TestTopic -c DefaultCluster"

# 查看主题列表
docker exec rocketmq-broker sh -c "cd /opt/rocketmq && sh bin/mqadmin topicList -n localhost:9876"

7.3 生产者消费者测试

7.3.1 创建测试脚本

创建 producer_test.sh：

bash 复制代码

#!/bin/bash
docker exec rocketmq-broker sh -c "
cd /opt/rocketmq && \
export NAMESRV_ADDR=localhost:9876 && \
sh bin/tools.sh org.apache.rocketmq.example.quickstart.Producer
"

创建 consumer_test.sh：

bash 复制代码

#!/bin/bash
docker exec rocketmq-broker sh -c "
cd /opt/rocketmq && \
export NAMESRV_ADDR=localhost:9876 && \
sh bin/tools.sh org.apache.rocketmq.example.quickstart.Consumer
"
# 赋予执行权限
chmod +x producer_test.sh consumer_test.sh

# 运行测试
./producer_test.sh
./consumer_test.sh

7.4 Web 控制台验证

打开浏览器访问：http://服务器IP:19876
检查集群状态
查看主题列表
监控消息生产和消费

8. 常见问题解决

8.1 跨平台构建问题

问题1：在 x86_64 系统上构建 ARM64 镜像失败

bash 复制代码

# 确保已安装 QEMU
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# 使用 buildx 构建
docker buildx create --use
docker buildx build --platform linux/arm64 -t your-image:tag .

问题2：容器内执行命令很慢

这是因为在非 ARM 系统上运行 ARM 容器时使用了 QEMU 模拟，性能会有所下降。解决方案：

在真实的 ARM64 硬件上构建
或者接受性能损失，仅用于构建镜像

问题3：manifest 未找到

bash 复制代码

# 启用 Docker 实验性功能
echo '{"experimental": true}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker

8.2 编译问题

问题1：Maven 内存不足

bash 复制代码

# 增加 Maven 内存
export MAVEN_OPTS="-Xmx4096m -XX:MaxPermSize=512m"

问题2：下载依赖超时

使用国内 Maven 镜像
检查网络连接
多次重试编译命令

8.3 Docker 问题

问题1：权限问题

bash 复制代码

# 修复权限
sudo chown -R $(id -u):$(id -g) ./broker-store ./namesrv-store

问题2：端口占用

bash 复制代码

# 检查端口占用
sudo netstat -tlnp | grep -E "9876|10909|10911|19876"

8.4 RocketMQ 运行问题

问题1：Broker 无法注册到 NameServer

检查网络连通性
确认 NAMESRV_ADDR 配置正确
查看防火墙设置

问题2：消息发送失败

检查 Topic 是否创建
验证 Broker 状态
查看日志文件

8.5 ARM64 特定问题

问题1：二进制不兼容

确保所有组件都是 ARM64 架构
重新编译源码

问题2：性能问题

调整 JVM 参数
优化系统内核参数

附录

A. 系统优化建议

bash 复制代码

# 编辑 /etc/sysctl.conf
sudo nano /etc/sysctl.conf

# 添加以下内容
vm.max_map_count = 655360
fs.file-max = 655360
net.ipv4.tcp_keepalive_time = 600
net.ipv4.tcp_keepalive_intvl = 30
net.ipv4.tcp_keepalive_probes = 10

# 应用配置
sudo sysctl -p

C. 备份脚本

创建 backup.sh：

bash 复制代码

#!/bin/bash
BACKUP_DIR="/backup/rocketmq/$(date +%Y%m%d_%H%M%S)"
mkdir -p $BACKUP_DIR

# 备份配置
cp -r *.conf $BACKUP_DIR/
cp docker-compose.yml $BACKUP_DIR/

# 备份数据
docker-compose stop
tar -czf $BACKUP_DIR/broker-store.tar.gz ./broker-store
tar -czf $BACKUP_DIR/namesrv-store.tar.gz ./namesrv-store
docker-compose start

echo "备份完成: $BACKUP_DIR"