How to Build a High‑Availability RocketMQ Cluster: Step‑by‑Step Guide

Cluster Architecture Overview

RocketMQ offers several deployment patterns: a single‑master setup (simple but single‑point‑of‑failure, suitable for development), multi‑master without data sync (no single point of failure, but no replication, fit for non‑critical production), asynchronous multi‑master‑multi‑slave (high availability with async replication, ideal for most production), and synchronous multi‑master‑multi‑slave (zero message loss, required for finance or payment scenarios). For production we recommend at least two masters and two slaves with asynchronous replication, combined with a Nameserver cluster for routing redundancy.

Environment Preparation

Assume a deployment of 2 Master + 2 Slave + 2 NameServer (async replication). Define the nodes as follows:

ns1 – 192.168.1.101 – NameServer

ns2 – 192.168.1.102 – NameServer

broker-a – 192.168.1.103 – Master A

broker-a-s – 192.168.1.104 – Slave A

broker-b – 192.168.1.105 – Master B

broker-b-s – 192.168.1.106 – Slave B

Software Requirements

JDK 8+ (recommended 8u281+)

Linux x86_64 (CentOS 7/8, Ubuntu 20+)

RocketMQ 5.x (latest stable version)

Download and Extract

wget https://archive.apache.org/dist/rocketmq/5.2.0/rocketmq-all-5.2.0-bin-release.zip
unzip rocketmq-all-5.2.0-bin-release.zip
cd rocketmq-all-5.2.0-bin-release

Start NameServer Cluster

Edit namesrv.conf if you need to bind a specific IP (default listenPort=9876).

nohup sh bin/mqnamesrv -c conf/namesrv.conf > logs/namesrv.log 2>&1 &

Verify with tail -f logs/namesrv.log; the log should contain "The Name Server boot success".

Configure Broker Cluster

Example broker-a.conf (Master A):

brokerClusterName=rocketmq-cluster
brokerName=broker-a
brokerId=0
namesrvAddr=192.168.1.101:9876;192.168.1.102:9876
listenPort=10911
deleteWhen=04
fileReservedTime=48
brokerRole=ASYNC_MASTER
flushDiskType=ASYNC_FLUSH
storePathRootDir=/data/rocketmq/store
storePathCommitLog=/data/rocketmq/store/commitlog

Example broker-a-s.conf (Slave A):

brokerClusterName=rocketmq-cluster
brokerName=broker-a
brokerId=1
namesrvAddr=192.168.1.101:9876;192.168.1.102:9876
listenPort=10911
deleteWhen=04
fileReservedTime=48
brokerRole=SLAVE
flushDiskType=ASYNC_FLUSH
storePathRootDir=/data/rocketmq/store
storePathCommitLog=/data/rocketmq/store/commitlog

Broker‑B and its slave use the same configuration with brokerName=broker-b.

Start Broker Nodes

nohup sh bin/mqbroker -c conf/broker-a.conf > logs/broker-a.log 2>&1 &

Check with tail -f logs/broker-a.log; you should see "The broker[broker-a, 0] boot success".

Validate Cluster Status

sh bin/mqadmin clusterList -n 192.168.1.101:9876

The output lists each broker with its ID, confirming that masters and slaves are registered.

Optional Web Console

wget https://github.com/apache/rocketmq-dashboard/releases/download/1.0.0/rocketmq-dashboard-1.0.0.jar
java -jar rocketmq-dashboard-1.0.0.jar --server.port=8080 --rocketmq.config.namesrvAddr=192.168.1.101:9876

Access the dashboard at http://<em>your_ip</em>:8080.

Production Deployment Recommendations

NameServer: Deploy at least two instances on separate machines.

Broker: Separate master and slave, use SSD for storage.

Monitoring & Alerting: Combine RocketMQ Dashboard with Prometheus and Grafana.

Persistence Tuning: Increase mappedFileSizeCommitLog (default 1 GB) and set flushDiskType=ASYNC_FLUSH for better performance.

Security: Enable ACL ( aclEnable=true) and TLS ( tlsEnable=true).

One‑Click Deployment Script (Multi‑Node)

#!/bin/bash
# Nodes configuration
NAMESERVERS=("192.168.1.101" "192.168.1.102")
MASTERS=("192.168.1.103" "192.168.1.105")
SLAVES=("192.168.1.104" "192.168.1.106")
ROCKETMQ_PKG="/opt/rocketmq-all-5.2.0-bin-release.zip"
INSTALL_DIR="/opt"

function deploy_nameserver() {
  for ns in "${NAMESERVERS[@]}"; do
    echo "[NameServer] Deploying $ns"
    ssh $ns "unzip -o $ROCKETMQ_PKG -d $INSTALL_DIR"
    ssh $ns "nohup $INSTALL_DIR/rocketmq-all-5.2.0-bin-release/bin/mqnamesrv > /dev/null 2>&1 &"
    echo "[NameServer] $ns started"
  done
}

function deploy_broker() {
  for master in "${MASTERS[@]}"; do
    echo "[Master] Deploying $master"
    scp broker-$master.conf $master:$INSTALL_DIR/rocketmq-all-5.2.0-bin-release/conf/
    ssh $master "nohup $INSTALL_DIR/rocketmq-all-5.2.0-bin-release/bin/mqbroker -c $INSTALL_DIR/rocketmq-all-5.2.0-bin-release/conf/broker-$master.conf > /dev/null 2>&1 &"
  done
  for slave in "${SLAVES[@]}"; do
    echo "[Slave] Deploying $slave"
    scp broker-$slave.conf $slave:$INSTALL_DIR/rocketmq-all-5.2.0-bin-release/conf/
    ssh $slave "nohup $INSTALL_DIR/rocketmq-all-5.2.0-bin-release/bin/mqbroker -c $INSTALL_DIR/rocketmq-all-5.2.0-bin-release/conf/broker-$slave.conf > /dev/null 2>&1 &"
  done
}

deploy_nameserver
sleep 5
deploy_broker

echo "Cluster deployment complete! Check status with:"
echo "sh bin/mqadmin clusterList -n 192.168.1.101:9876"

Key Production Configuration Optimizations

# Append to broker.conf (example for Master)
JAVA_OPT="${JAVA_OPT} -server -Xms8g -Xmx8g -Xmn4g"
autoCreateTopicEnable=false
sendMessageTimeout=3000
mappedFileSizeCommitLog=2147483648
flushDiskType=ASYNC_FLUSH
slaveReadEnable=true

Security Hardening

Enable ACL:

aclEnable=true
bin/mqadmin updateAclConfig -b broker -a 10911 -a {accessKey:secretKey}

Enable TLS:

tlsEnable=true
tlsTestModeEnable=false

Monitoring Metrics Suggestions

Broker disk usage > 80 % → possible write failures.

PageCache usage < 20 % → may affect read/write performance.

Consumer backlog > 1000 messages → check consumer health.

Send/Get TPS drop > 50 % → investigate network or broker issues.