How to Build a High‑Availability RocketMQ Cluster on Two Linux Servers

Cluster deployment options

RocketMQ can run with a single NameServer (high‑availability) and several broker topologies:

Single‑master : one broker only; simple but no HA.

Multi‑master : multiple masters without slaves; highest performance, but a master outage makes its pending messages unavailable until it recovers.

Multi‑master + async replication : each master has a slave; slaves replicate asynchronously (millisecond lag). Message loss is minimal, and consumers can read from a slave when the master fails.

Multi‑master + synchronous double‑write : each master has a slave that writes synchronously; no data loss and no latency on failover, at the cost of ~10% lower throughput.

Installation environment

OS: CentOS 7

RocketMQ version: 4.7.0

Java: JDK 1.8

Installation steps

1. Install Java

On both servers create a directory, extract the JDK, and set environment variables.

cd /usr/local
mkdir java
tar zxvf jdk-8u161-linux-x64.tar.gz -C java

# edit /etc/profile (append)
JAVA_HOME=/usr/local/java/jdk1.8.0_161
CLASSPATH=.:$JAVA_HOME/lib
PATH=$PATH:$JAVA_HOME/bin
export JAVA_HOME CLASSPATH PATH

source /etc/profile
java -version

2. Install and start NameServer

Create a data directory, download the RocketMQ binary package, unzip it, and launch the NameServer as a background process.

mkdir /data
cd /data
wget https://mirror.bit.edu.cn/apache/rocketmq/4.7.0/rocketmq-all-4.7.0-bin-release.zip
unzip rocketmq-all-4.7.0-bin-release.zip
nohup sh rocketmq-all-4.7.0-bin-release/bin/mqnamesrv &

# verify
jps | grep NamesrvStartup

3. Install and start brokers (2 master + 2 slave, async replication)

Each host runs one master broker and one slave broker, forming a cross‑paired HA topology. Configuration files are under conf/2m-2s-async/. Edit the properties to match the host IPs and roles.

Master broker example (broker-a.properties on 192.168.31.186)

brokerClusterName=rocketmq-cluster
brokerName=broker-a
brokerId=0
deleteWhen=04
fileReservedTime=120
brokerRole=ASYNC_MASTER
flushDiskType=SYNC_FLUSH
listenPort=10911
namesrvAddr=192.168.31.186:9876;192.168.31.231:9876
defaultTopicQueueNums=8
autoCreateTopicEnable=true
autoCreateSubscriptionGroup=true
brokerIP1=192.168.31.186
storePathRootDir=/data/rocketmq-all-4.7.0-bin-release/data/store
storePathCommitLog=${storePathRootDir}/commitlog
storePathConsumerQueue=${storePathRootDir}/consumequeue
storePathIndex=${storePathRootDir}/index
storeCheckpoint=${storePathRootDir}/checkpoint
abortFile=${storePathRootDir}/abort
mapedFileSizeCommitLog=1073741824
mapedFileSizeConsumeQueue=300000

Slave broker files (e.g., broker-a-s.properties) are identical except for brokerRole=SLAVE and a different listenPort (11011).

Start brokers

# on 192.168.31.186
nohup sh bin/mqbroker -c conf/2m-2s-async/broker-a.properties &
nohup sh bin/mqbroker -c conf/2m-2s-async/broker-b-s.properties &

# on 192.168.31.231
nohup sh bin/mqbroker -c conf/2m-2s-async/broker-b.properties &
nohup sh bin/mqbroker -c conf/2m-2s-async/broker-a-s.properties &

4. Common issues and tuning

Insufficient JVM memory : the default broker JVM options allocate 8 GB. Reduce them in bin/runbroker.sh if the host cannot provide that amount. JAVA_OPT="${JAVA_OPT} -server -Xms512m -Xmx512m -Xmn512m" Port accessibility : ensure firewall rules allow NameServer port 9876 and broker ports 10911, 11011, 10909, 11009.

5. Verification

Check broker logs (default location defined in conf/logback_broker.xml) for normal startup messages. Use the built‑in admin tool to query cluster status:

sh bin/mqadmin clusterList -n "192.168.31.186:9876;192.168.31.231:9876"

The output lists each broker, its ID, address, and version.

6. Shutdown procedure

# stop all brokers first
sh bin/mqshutdown broker
# then stop NameServer
sh bin/mqshutdown namesrv

7. Optional: install rocketmq‑console (web UI)

rocketmq‑console provides a graphical management console. Build it with Maven and run the jar, pointing to the NameServer addresses.

# install Maven (if not present)
wget http://mirrors.cnnic.cn/apache/maven/maven-3/3.5.4/binaries/apache-maven-3.5.4-bin.tar.gz
tar zxvf apache-maven-3.5.4-bin.tar.gz -C /opt
export MAVEN_HOME=/opt/apache-maven-3.5.4
export PATH=$MAVEN_HOME/bin:$PATH

# clone the externals repository
git clone https://github.com/apache/rocketmq-externals.git
cd rocketmq-externals/rocketmq-console
mvn clean package -Dmaven.test.skip=true

# run the console
java -jar target/rocketmq-console-ng-1.0.1.jar \
  --rocketmq.config.namesrvAddr='192.168.31.186:9876;192.168.31.231:9876'

After startup, the UI is reachable at http://192.168.31.186:8080.

References

RocketMQ quick‑start documentation: http://rocketmq.apache.org/docs/quick-start/ Official RocketMQ source: https://github.com/apache/rocketmq rocketmq‑console source:

https://github.com/apache/rocketmq-externals/tree/master/rocketmq-console