Ubuntu 安装 RocketMQ 5.x + Dashboard 完整教程

版本信息（截至 2025 年）

RocketMQ：5.3.3（最新稳定版）

RocketMQ Dashboard：2.1.0（最新稳定版）

JDK：11（推荐，最低要求 JDK 8）

Maven：3.9.x

一、安装 JDK

RocketMQ 运行依赖 JDK 8 或更高版本，推荐使用 JDK 11。

方式 A：使用 apt 安装 OpenJDK 11（推荐，最简单）

bash 复制代码

# 更新包索引
sudo apt update

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

# 验证安装
java -version

预期输出类似：

复制代码

openjdk version "11.x.x" ...

方式 B：手动安装 Oracle JDK（可选）

bash 复制代码

# 添加 PPA 源
sudo add-apt-repository ppa:linuxuprising/java
sudo apt update

# 安装 Oracle JDK 11
sudo apt install -y oracle-java11-installer-local

# 验证
java -version

配置 JAVA_HOME 环境变量

bash 复制代码

# 查找 JDK 安装路径
update-alternatives --config java
# 通常路径为 /usr/lib/jvm/java-11-openjdk-amd64

# 编辑环境变量
sudo nano /etc/profile.d/java.sh

在文件中写入以下内容：

bash 复制代码

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

保存后使配置生效：

bash 复制代码

source /etc/profile.d/java.sh

# 验证
echo $JAVA_HOME

二、安装 Maven

编译 RocketMQ Dashboard 源码时需要 Maven。如果你只使用 RocketMQ 的二进制包且 Dashboard 通过 Docker 运行，则可跳过此步骤。

方式 A：使用 apt 安装（快速）

bash 复制代码

sudo apt install -y maven

# 验证
mvn -version

方式 B：手动安装最新版 Maven（推荐，版本更新）

bash 复制代码

# 下载 Maven 3.9.x（请到 https://maven.apache.org 确认最新版本号）
cd /opt
sudo wget https://archive.apache.org/dist/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz

# 解压
sudo tar -xzf apache-maven-3.9.9-bin.tar.gz

# 重命名，方便管理
sudo mv apache-maven-3.9.9 maven

# 配置环境变量
sudo nano /etc/profile.d/maven.sh

在文件中写入：

bash 复制代码

export MAVEN_HOME=/opt/maven
export PATH=$MAVEN_HOME/bin:$PATH

使配置生效：

bash 复制代码

source /etc/profile.d/maven.sh

# 验证
mvn -version

配置阿里云镜像（国内加速，强烈推荐）

bash 复制代码

# 编辑 Maven 配置文件
sudo nano /opt/maven/conf/settings.xml

在 <mirrors> 标签内添加：

xml 复制代码

<mirror>
  <id>alimaven</id>
  <name>aliyun maven</name>
  <url>https://maven.aliyun.com/repository/public</url>
  <mirrorOf>central</mirrorOf>
</mirror>

三、安装 RocketMQ 5.x

3.1 安装必要工具

bash 复制代码

sudo apt update
sudo apt install -y wget unzip

3.2 下载二进制包（推荐）

bash 复制代码

# 创建安装目录
sudo mkdir -p /opt/rocketmq
cd /opt/rocketmq

# 下载 RocketMQ 5.3.3 二进制包
sudo wget https://dist.apache.org/repos/dist/release/rocketmq/5.3.3/rocketmq-all-5.3.3-bin-release.zip

# 解压
sudo unzip rocketmq-all-5.3.3-bin-release.zip

# 重命名
sudo mv rocketmq-all-5.3.3-bin-release rocketmq-5.3.3

# 进入目录
cd /opt/rocketmq/rocketmq-5.3.3

3.3 调整 JVM 内存（低配服务器必做）

RocketMQ 默认 JVM 内存较大，低配机器需要调小，否则会启动失败。

调整 NameServer 内存：

bash 复制代码

sudo nano bin/runserver.sh

找到下面这行（类似）：

复制代码

JAVA_OPT="${JAVA_OPT} -server -Xms4g -Xmx4g -Xmn2g ..."

修改为（根据实际内存调整）：

复制代码

JAVA_OPT="${JAVA_OPT} -server -Xms512m -Xmx512m -Xmn256m ..."

调整 Broker 内存：

bash 复制代码

sudo nano bin/runbroker.sh

同样找到 Xms/Xmx/Xmn 参数并调整为合适大小，例如：

复制代码

JAVA_OPT="${JAVA_OPT} -server -Xms1g -Xmx1g -Xmn512m ..."

3.4 配置 Broker（可选但推荐）

bash 复制代码

sudo nano conf/broker.conf

在文件末尾添加以下内容（将 YOUR_SERVER_IP 替换为实际 IP）：

properties 复制代码

# Broker 对外暴露的 IP（云服务器需填公网 IP）
brokerIP1=YOUR_SERVER_IP

# 允许自动创建 Topic（开发环境建议开启）
autoCreateTopicEnable=true

# NameServer 地址
namesrvAddr=localhost:9876

3.5 启动 NameServer

bash 复制代码

cd /opt/rocketmq/rocketmq-5.3.3

# 后台启动 NameServer
nohup sh bin/mqnamesrv &

# 查看启动日志，看到 "The Name Server boot success" 即表示成功
tail -f ~/logs/rocketmqlogs/namesrv.log

按 Ctrl+C 退出日志查看。

3.6 启动 Broker

bash 复制代码

# 后台启动 Broker（-n 指定 NameServer 地址）
nohup sh bin/mqbroker -n localhost:9876 -c conf/broker.conf &

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

看到 The broker[broker-a, IP:10911] boot success 即启动成功。

3.7 验证 RocketMQ 运行

bash 复制代码

# 设置环境变量
export NAMESRV_ADDR=localhost:9876

# 测试发送消息
sh bin/tools.sh org.apache.rocketmq.example.quickstart.Producer

# 测试接收消息（新开一个终端）
export NAMESRV_ADDR=localhost:9876
sh bin/tools.sh org.apache.rocketmq.example.quickstart.Consumer

四、安装 RocketMQ Dashboard

Dashboard 提供可视化的 Web 管理界面，支持查看 Topic、Consumer、消息轨迹等。

方式 A：Docker 方式（最简单，推荐）

需要先安装 Docker：

bash 复制代码

# 安装 Docker
sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

# 拉取并启动 Dashboard（替换 127.0.0.1 为 NameServer 实际地址）
sudo docker run -d \
  --name rocketmq-dashboard \
  -e "JAVA_OPTS=-Drocketmq.namesrv.addr=127.0.0.1:9876" \
  -p 8080:8080 \
  --restart=always \
  apacherocketmq/rocketmq-dashboard:latest

启动后访问：http://YOUR_IP:8080

方式 B：源码编译方式

确保已完成第二步 Maven 的安装。

bash 复制代码

# 安装 git
sudo apt install -y git

# 克隆 Dashboard 源码
cd /opt
sudo git clone https://github.com/apache/rocketmq-dashboard.git
cd rocketmq-dashboard

# 修改 NameServer 地址配置
sudo nano src/main/resources/application.properties

找到并修改以下配置：

properties 复制代码

rocketmq.config.namesrvAddr=127.0.0.1:9876

编译打包：

bash 复制代码

# 跳过测试，加速编译
mvn clean package -DskipTests

# 编译成功后，jar 包在 target 目录
ls target/rocketmq-dashboard-*.jar

运行 Dashboard：

bash 复制代码

# 后台运行
nohup java -jar target/rocketmq-dashboard-2.1.0.jar \
  --server.port=8080 \
  --rocketmq.config.namesrvAddr=127.0.0.1:9876 \
  > /tmp/dashboard.log 2>&1 &

# 查看启动日志
tail -f /tmp/dashboard.log

看到 Started App in x.xxx seconds 表示启动成功。

访问：http://YOUR_IP:8080

五、常用管理命令

停止服务

bash 复制代码

cd /opt/rocketmq/rocketmq-5.3.3

# 停止 Broker
sh bin/mqshutdown broker

# 停止 NameServer
sh bin/mqshutdown namesrv

查看进程

bash 复制代码

# 查看 RocketMQ 相关进程
ps -ef | grep rocketmq

创建 Topic（手动）

bash 复制代码

export NAMESRV_ADDR=localhost:9876
sh bin/mqadmin updateTopic -n localhost:9876 -b localhost:10911 -t MyTopic

查看 Broker 状态

bash 复制代码

export NAMESRV_ADDR=localhost:9876
sh bin/mqadmin brokerStatus -n localhost:9876 -b localhost:10911

六、端口说明

组件	端口	说明
NameServer	9876	客户端/Broker 注册与发现
Broker	10911	消息读写端口
Broker	10912	主从同步端口
Broker	10909	VIP 通道（可选）
Dashboard	8080	Web 管理界面

防火墙提示：如果是云服务器，需要在安全组/防火墙中开放以上端口。
bash 复制代码
# Ubuntu UFW 开放端口示例
sudo ufw allow 9876
sudo ufw allow 10911
sudo ufw allow 8080

常见问题

Q：启动 Broker 报内存不足？

回到 3.3 步骤，调小 runbroker.sh 中的 JVM 参数。

Q：Dashboard 连不上 NameServer？

检查 application.properties 中的 namesrvAddr 配置是否为正确 IP，云服务器注意内网/公网地址区别。

Q：发消息报 connect to xxx failed？

在 broker.conf 中配置 brokerIP1=你的实际IP，并重启 Broker。

Q：编译 Dashboard 太慢？

参考第二步配置阿里云 Maven 镜像。