agent-skills/skills/g3fo-docs/references/middleware/rocketmq/deploy.md

RocketMQ 5.3.2 集群部署文档

一、概述

1.1 核心功能

RocketMQ 是一款分布式消息中间件，具有高吞吐、高可用、支持事务消息、延时消息等特性。RocketMQ 5.x 引入了 Controller 模式，实现了自动主从切换，提升了集群的高可用能力。

1.2 Controller 模式说明

RocketMQ 5.x 引入了基于 jRaft 的 Controller 模式，实现了以下核心功能：

• 自动主从切换：当 Master 节点故障时，Controller 自动选举新的 Master，无需人工干预
• 元数据管理：统一管理 Topic、订阅组等元数据，避免元数据不一致
• 负载均衡：自动进行 Broker 负载均衡，优化集群资源利用率

1.3 适用场景

• 生产环境下的高可用消息队列需求
• 需要事务消息、延时消息的分布式系统
• 大规模消息吞吐场景（百万级 TPS）

1.4 前置条件

• 运行环境：Docker & Docker Compose
• 镜像版本：apache/rocketmq:5.3.2
• 网络规划：所有节点需网络互通，且需明确各宿主机的外部 IP
• 集群规模：建议至少 3 个节点组成集群（NameServer、Broker、Controller 各 3 个实例）

---

二、环境准备

2.1 节点信息规划

节点	主机IP	brokerId	jRaftServerId	机器配置	角色
节点1	192.168.3.230	0	192.168.3.230:9880	高性能	Master + NameServer + Controller
节点2	192.168.3.200	1	192.168.3.200:9880	高性能	Slave + NameServer + Controller
节点3	192.168.3.110	-	192.168.3.110:9880	低配	NameServer + Controller（仅选举）

架构说明：

• 3台机均部署 NameServer：NameServer 作为服务注册发现中心，所有节点都需要部署以避免单点
• 2台高性能机部署 Broker：Broker 负责消息存储和转发，对性能要求高，仅在两台高性能机上部署
• Controller 内嵌于 NameServer：Controller 基于 jRaft 实现，随 NameServer 一起启动，用于 Broker 的自动主从切换
• 低配机仅用于选举：192.168.3.110 节点仅部署 NameServer（包含 Controller），参与 Controller 集群选举，不部署 Broker

2.2 目录结构配置

2.2.1 高性能机节点（192.168.3.230、192.168.3.200）执行

# 创建 Broker 相关目录
sudo mkdir -p /data/rocketmq/broker/{logs,store}

# 创建 NameServer 相关目录
sudo mkdir -p /data/rocketmq/nameserver/{logs,data}

# 设置目录权限（RocketMQ 容器默认用户 UID/GID 为 3000）
sudo chown 3000:3000 /data/rocketmq -R

2.2.2 低配机节点（192.168.3.110）执行

# 仅创建 NameServer 相关目录（无需 Broker 目录）
sudo mkdir -p /data/rocketmq/nameserver/{logs,data}

# 设置目录权限
sudo chown 3000:3000 /data/rocketmq -R

---

三、部署架构说明

3.1 单节点部署（开发/测试环境）

适用于开发测试环境，部署单个 NameServer 和 Broker 实例：

• 1 个 NameServer 实例
• 1 个 Broker 实例（Master）
• 1 个 Dashboard 实例（可选）

优点：部署简单，资源占用少 缺点：无高可用，单点故障风险

3.2 集群部署（生产环境推荐）

适用于生产环境，部署多个实例组成高可用集群：

• 3 个 NameServer 实例（避免单点，3台机均部署）
• 2 个 Broker 实例（1 Master + 1 Slave，仅在2台高性能机部署）
• 3 个 Controller 实例（基于 jRaft，内嵌于 NameServer）
• 1 个 Dashboard 实例（可选，建议部署在高性能机）

优点：高可用、自动故障转移、负载均衡、资源优化 缺点：部署复杂，资源占用较多

架构优势：

• 低配机仅承担 NameServer 和 Controller 选举职责，资源占用低
• 高性能机专注处理 Broker 消息存储和转发，性能最大化
• Controller 集群跨3台机部署，确保选举的高可用性

---

四、Docker Compose 配置

4.1 NameServer 配置（所有3台节点统一执行）

创建 /data/rocketmq/docker-compose.yml，添加 NameServer 服务：

version: "3.8"

networks:
  my-net:
    driver: bridge

services:
  rocketmq-nameserver:
    image: apache/rocketmq:5.3.2
    container_name: rocketmq-nameserver
    restart: always
    deploy:
      resources:
        limits:
          memory: 1G
      replicas: 1
      placement:
        constraints:
          - node.role == manager
    networks:
      - my-net
    ports:
      - "9876:9876" # NameServer 默认端口
      - "9880:9880" # jRaft 内部通信端口
      - "9770:9770" # Controller 外部通信端口
    volumes:
      - /etc/localtime:/etc/localtime
      - /etc/timezone:/etc/timezone
      - /data/rocketmq/nameserver/logs:/home/rocketmq/logs/rocketmqlogs
      - /data/rocketmq/nameserver/data:/home/rocketmq/data
      - /data/rocketmq/nameserver/namesrv.conf:/home/rocketmq/conf/namesrv.conf
    environment:
      - TZ=Asia/Hong_Kong
    command: sh mqnamesrv -c /home/rocketmq/conf/namesrv.conf

注意：NameServer 配置在所有3台节点（192.168.3.230、192.168.3.200、192.168.3.110）都需要执行。

4.2 Broker 配置（仅2台高性能机执行）

在 /data/rocketmq/docker-compose.yml 中添加 Broker 服务：

rocketmq-broker:
  image: apache/rocketmq:5.3.2
  container_name: rocketmq-broker
  restart: always
  deploy:
    resources:
      limits:
        memory: 2G
  networks:
    - my-net
  environment:
    - TZ=Asia/Hong_Kong
  ports:
    - "10911:10911" # Broker 默认服务端口
    - "10909:10909" # HA 端口（Master-Slave 同步）
    - "18081:18081" # gRPC 代理端口
    - "18080:18080" # HTTP 代理端口
  volumes:
    - /etc/localtime:/etc/localtime
    - /etc/timezone:/etc/timezone
    - /data/rocketmq/broker/logs:/home/rocketmq/logs/rocketmqlogs
    - /data/rocketmq/broker/store:/home/rocketmq/store
    - /data/rocketmq/broker/broker.conf:/home/rocketmq/broker.conf
    - /data/rocketmq/broker/rmq-proxy.json:/home/rocketmq/rocketmq-5.3.2/conf/rmq-proxy.json
  command: sh mqbroker -c /home/rocketmq/broker.conf --enable-proxy

注意：Broker 配置仅在2台高性能机（192.168.3.230、192.168.3.200）执行，低配机（192.168.3.110）不需要部署 Broker。

4.3 Dashboard 配置（可选，建议在高性能机部署）

在 /data/rocketmq/docker-compose.yml 中添加 Dashboard 服务：

rocketmq-dashboard:
  image: apacherocketmq/rocketmq-dashboard
  container_name: rocketmq-dashboard
  restart: always
  deploy:
    resources:
      limits:
        memory: 512M
  replicas: 1
  placement:
    constraints:
      - node.role == manager
  networks:
    - my-net
  ports:
    - "8086:8080"
  volumes:
    - /etc/localtime:/etc/localtime
    - /etc/timezone:/etc/timezone
  environment:
    - JAVA_OPTS=-Xmx512M -Xms256M -Xmn128M -Drocketmq.namesrv.addr=192.168.3.230:9876;192.168.3.200:9876;192.168.3.110:9876 -Dcom.rocketmq.sendMessageWithVIPChannel=false

注意：Dashboard 建议部署在高性能机（如 192.168.3.230），仅需部署1个实例即可。

---

五、核心配置文件

5.1 NameServer 配置（所有3台节点统一执行）

创建 /data/rocketmq/nameserver/namesrv.conf：

# NameServer 监听端口
listenPort = 9876

# 启用内嵌 Controller（5.x 新特性）
enableControllerInNamesrv = true

# jRaft 内核配置（三台节点统一）
controllerType = jRaft

# 集群唯一标识
jRaftGroupId = controller-jraft-group

# Raft 内部通信地址（对应容器 9880 端口）
jRaftInitConf = 192.168.3.230:9880,192.168.3.200:9880,192.168.3.110:9880

# Controller 外部通信地址（对应容器 9770 端口）
jRaftControllerRPCAddr = 192.168.3.230:9770,192.168.3.200:9770,192.168.3.110:9770

# 标志自己节点的 ServerId，必须出现在 jRaftInitConf 中
# 每个节点需要修改为对应的主机 IP
jRaftServerId = 192.168.3.200:9880

# Controller 数据存储路径
controllerStorePath = /home/rocketmq/data

注意：每个节点的 jRaftServerId 需要修改为对应的主机 IP，例如：

• 节点1（192.168.3.230）：jRaftServerId = 192.168.3.230:9880
• 节点2（192.168.3.200）：jRaftServerId = 192.168.3.200:9880
• 节点3（192.168.3.110）：jRaftServerId = 192.168.3.110:9880

5.2 Broker 配置（仅2台高性能机执行）

创建 /data/rocketmq/broker/broker.conf：

# ========== 节点标识配置（每个节点不同） ==========
# 节点 ID，0 表示 Master，其他正整数表示 Slave
brokerId = 1

# Broker 节点名称，集群部署时同一主从对的名称相同
brokerName = broker

# ========== Controller 模式配置 ==========
# Broker Controller 模式的总开关，只有该值为 true，自动主从切换模式才会打开
enableControllerMode = true

# Controller 地址列表（多个用 ; 隔开）
controllerAddr = 192.168.3.230:9770;192.168.3.200:9770;192.168.3.110:9770

# ========== NameServer 配置 ==========
# NameServer 地址列表（多个用 ; 隔开）
namesrvAddr = 192.168.3.230:9876;192.168.3.200:9876;192.168.3.110:9876

# ========== 集群配置 ==========
# 集群名称，同一集群中必须一致
brokerClusterName = DefaultCluster

# ========== 网络配置 ==========
# Broker 对外服务的监听端口（默认 10911）
# 注意：Broker 启动后会占用 3 个端口（listenPort-2、listenPort、listenPort+1）
listenPort = 10911

# Broker 服务地址（内部使用填内网 IP，外部使用填公网 IP）
brokerIP1 = 192.168.3.200

# BrokerHAIP 地址，供 Slave 同步消息的地址
# brokerIP2 = 127.0.0.1

# ========== 主从复制配置 ==========
# Broker 角色
# ASYNC_MASTER：异步复制 Master，主写成功即响应，可能丢失少量数据
# SYNC_MASTER：同步双写 Master，主从都写成功才响应，不会丢失数据
# SLAVE：从节点
brokerRole = ASYNC_MASTER

# 刷盘方式
# SYNC_FLUSH：同步刷新，性能较差但可靠性高
# ASYNC_FLUSH：异步刷新，性能好但可能丢失少量数据
flushDiskType = ASYNC_FLUSH

# ========== 消息存储配置 ==========
# 每天什么时间删除超过保留时间的 commit log（默认 04 点）
deleteWhen = 04

# 文件保留时间（小时，默认 72 小时）
fileReservedTime = 24

# 消息最大大小（字节，默认 4MB）
maxMessageSize = 4194304

# ========== Topic 配置 ==========
# 自动创建 Topic 时的默认队列数
defaultTopicQueueNums = 4

# 是否允许 Broker 自动创建 Topic（建议线下开启，线上关闭）
autoCreateTopicEnable = true

# 是否允许 Broker 自动创建订阅组（建议线下开启，线上关闭）
autoCreateSubscriptionGroup = true

# ========== 延时消息配置 ==========
# 延时等级（从 1 开始，可自定义添加如 1d）
messageDelayLevel = 1s 5s 10s 30s 1m 2m 3m 4m 5m 6m 7m 8m 9m 10m 20m 30m 1h 2h

# ========== 事务消息配置 ==========
# TM 在 20 秒内应将最终确认状态发送给 TC，否则引发消息回查（默认 60 秒）
transactionTimeout = 20

# 最多回查 5 次，超过后丢弃消息并记录错误日志（默认 15 次）
transactionCheckMax = 5

# 消息回查的时间间隔为 10 秒（默认 60 秒）
transactionCheckInterval = 10

# ========== 其他配置 ==========
# 延时消息最大时长（秒，默认 3 天，这里设置为 7 天）
timerMaxDelaySec = 604800

# 开启消息追踪
traceTopicEnable = true

注意：每个节点需要修改以下参数：

• brokerId：高性能机1（192.168.3.230）为 0（Master），高性能机2（192.168.3.200）为 1（Slave）
• brokerIP1：当前节点的主机 IP

配置示例：

• 高性能机1（192.168.3.230）：brokerId = 0，brokerIP1 = 192.168.3.230
• 高性能机2（192.168.3.200）：brokerId = 1，brokerIP1 = 192.168.3.200
• 低配机（192.168.3.110）：不需要部署 Broker

5.3 Proxy 配置（仅2台高性能机执行）

创建 /data/rocketmq/broker/rmq-proxy.json：

{
  "rocketMQClusterName": "DefaultCluster",
  "remotingListenPort": 18080,
  "grpcServerPort": 18081,
  "namesrvAddr": "192.168.3.200:9876;192.168.3.230:9876;192.168.3.110:9876"
}

注意：namesrvAddr 可以配置为当前节点优先的 NameServer 地址列表。

---

六、端口说明

6.1 NameServer 端口

端口	用途	说明
9876	NameServer 服务端口	客户端和 Broker 连接 NameServer 的默认端口
9880	jRaft 内部通信端口	Controller 集群内部 Raft 协议通信
9770	Controller 外部通信端口	Broker 连接 Controller 的 RPC 端口

6.2 Broker 端口

端口	用途	说明
10911	Broker 默认服务端口	客户端发送和接收消息的默认端口
10909	HA 端口	Master-Slave 主从同步端口（listenPort - 2）
10912	Fast Fail 端口	快速失败端口（listenPort + 1，自动占用）
18080	HTTP 代理端口	Proxy HTTP 协议接入端口
18081	gRPC 代理端口	Proxy gRPC 协议接入端口

6.3 Dashboard 端口

端口	用途	说明
8086	Dashboard Web 界面	RocketMQ 管理控制台访问端口

注意：部署集群时需要确保所有节点的端口不冲突，建议提前规划端口分配。

---

七、Controller 模式详解

7.1 Controller 模式架构

Controller 模式基于 jRaft 实现，采用 Raft 一致性算法，确保元数据的一致性和高可用：

                    +-----------------+
                    |   Client App    |
                    +--------+--------+
                             |
                             v
        +--------------------+--------------------+
        |                    |                    |
+-------v-------+    +-------v-------+    +-------v-------+
|  NameServer   |    |  NameServer   |    |  NameServer   |
| (高性能机1)   |    | (高性能机2)   |    |   (低配机)    |
|   (Node1)     |    |   (Node2)     |    |   (Node3)     |
+-------+-------+    +-------+-------+    +-------+-------+
        |                    |                    |
        +--------------------+--------------------+
                             |
                    +--------v--------+
                    |   Controller    | (jRaft 集群)
                    |   (Leader)      |
                    +--------+--------+
                             |
        +--------------------+
        |
+-------v-------+
|    Broker     | (高性能机1)
|   (Master)    |
+---------------+
        |
        v
+---------------+
|    Broker     | (高性能机2)
|   (Slave)     |
+---------------+

架构说明：

• 3台 NameServer：所有节点都部署 NameServer，确保服务注册发现的高可用
• Controller 内嵌于 NameServer：Controller 基于 jRaft 实现，随 NameServer 一起启动
• 2台 Broker：仅在2台高性能机部署 Broker，低配机仅参与选举
• 自动主从切换：当 Master 故障时，Controller 自动选举 Slave 为新 Master

7.2 Controller 核心功能

1. 自动主从切换

   • 监控 Broker 健康状态
   • Master 故障时自动选举新 Master
   • 更新 NameServer 路由信息

2. 元数据管理

   • 统一管理 Topic、订阅组等元数据
   • 避免元数据不一致问题
   • 支持动态扩缩容

3. 负载均衡

   • 自动进行 Broker 负载均衡
   • 优化集群资源利用率
   • 支持流量调度

7.3 jRaft 配置说明

配置项	说明	示例值
controllerType	Controller 实现类型	jRaft
jRaftGroupId	Raft 集群唯一标识	controller-jraft-group
jRaftInitConf	Raft 内部通信地址列表	192.168.3.230:9880,192.168.3.200:9880,192.168.3.110:9880
jRaftControllerRPCAddr	Controller 外部通信地址列表	192.168.3.230:9770,192.168.3.200:9770,192.168.3.110:9770
jRaftServerId	当前节点的 ServerId	192.168.3.200:9880

注意：

• jRaftServerId 必须出现在 jRaftInitConf 中
• 建议至少 3 个节点组成 Raft 集群，确保高可用
• Raft 集群会自动选举 Leader，无需手动指定

---

八、安全配置（可选）

8.1 ACL 认证配置

生产环境建议开启 ACL 认证，防止未授权访问。

8.1.1 启用 ACL 认证

在 broker.conf 中添加：

# 开启 ACL 认证
aclEnable = true

# 指定 ACL 配置文件路径
globalWhiteRemoteAddresses = 127.0.0.1

8.1.2 创建 ACL 配置文件

创建 /data/rocketmq/broker/plain_acl.yml：

# 全局白名单（允许访问的 IP 地址）
globalWhiteRemoteAddresses:
  - 10.*.*.*
  - 192.168.*.*

# 账户配置
accounts:
  # 管理员账户
  - accessKey: admin
    secretKey: admin123
    whiteRemoteAddress:
    admin: true

  # 普通用户账户
  - accessKey: appuser
    secretKey: appuser123
    whiteRemoteAddress:
    admin: false
    defaultTopicPerm: PUB|SUB
    defaultGroupPerm: PUB|SUB
    topicPerms:
      - topicA=PUB
      - topicB=SUB
    groupPerms:
      - groupA=PUB|SUB

8.1.3 挂载 ACL 配置文件

在 docker-compose.yml 中添加 ACL 配置文件挂载：

volumes:
  - /data/rocketmq/broker/plain_acl.yml:/home/rocketmq/conf/plain_acl.yml

8.2 TLS/SSL 加密（可选）

生产环境建议开启 TLS/SSL 加密，保障数据传输安全。

8.2.1 生成证书

# 生成 CA 证书
openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt -subj "/CN=RocketMQ CA"

# 生成服务器证书
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr -subj "/CN=192.168.3.200"
openssl x509 -req -days 3650 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

# 生成客户端证书
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr -subj "/CN=Client"
openssl x509 -req -days 3650 -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt

8.2.2 配置 TLS

在 broker.conf 中添加：

# 开启 TLS
tlsTestModeEnable = false
tlsServerCert = /home/rocketmq/conf/server.crt
tlsServerKey = /home/rocketmq/conf/server.key
tlsServerAuthClient = true
tlsClientCertPath = /home/rocketmq/conf/ca.crt

挂载证书文件：

volumes:
  - /data/rocketmq/broker/server.crt:/home/rocketmq/conf/server.crt
  - /data/rocketmq/broker/server.key:/home/rocketmq/conf/server.key
  - /data/rocketmq/broker/ca.crt:/home/rocketmq/conf/ca.crt

---

九、启动和验证

9.1 启动服务

9.1.1 启动 NameServer（所有3台节点执行）

# 进入目录
cd /data/rocketmq

# 启动 NameServer
docker compose up -d rocketmq-nameserver

# 查看启动状态
docker compose ps

9.1.2 启动 Broker（仅2台高性能机执行）

# 进入目录
cd /data/rocketmq

# 启动 Broker
docker compose up -d rocketmq-broker

# 查看启动状态
docker compose ps

9.1.3 启动 Dashboard（可选，建议在高性能机执行）

# 进入目录
cd /data/rocketmq

# 启动 Dashboard
docker compose up -d rocketmq-dashboard

# 查看启动状态
docker compose ps

启动顺序建议：

1. 先在所有3台节点启动 NameServer
2. 等待 NameServer 启动完成（约 30 秒）
3. 再在2台高性能机启动 Broker
4. 最后启动 Dashboard（可选）

9.2 验证 NameServer

# 查看日志（所有3台节点执行）
docker logs rocketmq-nameserver

# 测试连接
telnet 192.168.3.230 9876
telnet 192.168.3.200 9876
telnet 192.168.3.110 9876

9.3 验证 Broker

# 查看日志（仅2台高性能机执行）
docker logs rocketmq-broker

# 检查 Broker 是否注册到 NameServer
docker exec rocketmq-nameserver sh mqadmin clusterList -n 192.168.3.230:9876

# 查看集群状态（应该看到 2 个 Broker）
docker exec rocketmq-nameserver sh mqadmin brokerStatus -n 192.168.3.230:9876

9.4 验证 Controller

# 查看 Controller 状态（所有3台节点执行）
docker exec rocketmq-nameserver sh mqadmin getControllerMode -n 192.168.3.230:9876

# 查看 Controller 集群状态
docker exec rocketmq-nameserver sh mqadmin getControllerInfo -n 192.168.3.230:9876

预期结果：

• Controller 模式应显示为 ENABLED
• Controller 集群应选举出 Leader（3台节点中选1个）

9.5 访问 Dashboard

浏览器访问：http://192.168.3.230:8086

默认账号密码：admin / admin

验证内容：

• 集群概览中应显示 2 个 Broker
• NameServer 列表中应显示 3 个节点
• Controller 状态应为正常

---

十、常见问题

10.1 Broker 无法连接 NameServer

现象：Broker 日志显示连接 NameServer 失败

排查步骤：

1. 检查 namesrvAddr 配置是否正确
2. 检查防火墙是否开放 9876 端口
3. 检查网络连通性：telnet <nameserver-ip> 9876

10.2 Controller 集群无法选举 Leader

现象：Controller 集群一直处于选举状态

排查步骤：

1. 检查 jRaftInitConf 和 jRaftServerId 配置是否正确
2. 检查 9880 和 9770 端口是否开放
3. 检查节点时间是否同步（NTP）
4. 查看 NameServer 日志：docker logs rocketmq-nameserver

10.3 主从切换失败

现象：Master 故障后无法自动切换

排查步骤：

1. 检查 enableControllerMode 是否为 true
2. 检查 Controller 集群状态是否正常
3. 检查 Slave 节点是否正常运行
4. 查看 Broker 日志：docker logs rocketmq-broker

10.4 消息发送失败

现象：客户端发送消息超时或失败

排查步骤：

1. 检查 NameServer 地址配置是否正确
2. 检查 Topic 是否存在（autoCreateTopicEnable 是否开启）
3. 检查 Broker 是否正常注册到 NameServer
4. 检查网络连通性和防火墙规则

10.5 磁盘空间不足

现象：Broker 日志显示磁盘空间不足

解决方案：

1. 调整 fileReservedTime 参数，缩短消息保留时间
2. 调整 deleteWhen 参数，增加清理频率
3. 扩容磁盘空间
4. 手动清理过期消息：docker exec rocketmq-broker sh mqadmin cleanExpiredCQFile -n <nameserver-addr>

---

十一、性能优化建议

11.1 JVM 参数优化

在 docker-compose.yml 中调整 JVM 参数：

environment:
  - JAVA_OPT_EXT=-Xms2g -Xmx2g -Xmn1g -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=320m

11.2 操作系统优化

# 增加文件描述符限制
ulimit -n 65535

# 优化 TCP 参数
echo 'net.core.somaxconn = 1024' >> /etc/sysctl.conf
echo 'net.ipv4.tcp_max_syn_backlog = 2048' >> /etc/sysctl.conf
sysctl -p

11.3 网络优化

• 使用万兆网络（10Gbps）
• 部署在同一机房，减少网络延迟
• 使用专用网络，避免公网访问

11.4 存储优化

• 使用 SSD 存储，提升 IO 性能
• 将日志和数据分离到不同磁盘
• 定期清理过期消息，避免磁盘满

---

十二、监控和告警

12.1 关键监控指标

指标	说明	告警阈值
消息堆积量	消息未消费数量	> 10000
消息发送 TPS	每秒发送消息数	异常波动
消息消费 TPS	每秒消费消息数	异常波动
Broker CPU 使用率	Broker 进程 CPU 占用	> 80%
Broker 内存使用率	Broker 进程内存占用	> 80%
磁盘使用率	数据目录磁盘占用	> 80%
网络流量	网络入出流量	异常波动

12.2 日志监控

• Broker 日志：/data/rocketmq/broker/logs/
• NameServer 日志：/data/rocketmq/nameserver/logs/

建议使用 ELK 或 Loki 等日志收集系统进行集中管理。

---

十三、备份和恢复

13.1 数据备份

# 备份 Broker 数据
tar -czf rocketmq-broker-backup-$(date +%Y%m%d).tar.gz /data/rocketmq/broker/store

# 备份配置文件
tar -czf rocketmq-config-backup-$(date +%Y%m%d).tar.gz /data/rocketmq/broker/*.conf /data/rocketmq/broker/*.json

13.2 数据恢复

# 停止 Broker
docker compose stop rocketmq-broker

# 恢复数据
tar -xzf rocketmq-broker-backup-20240121.tar.gz -C /

# 启动 Broker
docker compose start rocketmq-broker

---

十四、升级和扩容

14.1 版本升级

# 1. 停止服务
docker compose down

# 2. 备份数据
tar -czf rocketmq-backup-$(date +%Y%m%d).tar.gz /data/rocketmq

# 3. 更新镜像版本
sed -i 's/apache\/rocketmq:5.3.2/apache\/rocketmq:5.3.3/g' docker-compose.yml

# 4. 启动服务
docker compose up -d

# 5. 验证服务
docker compose ps

14.2 集群扩容

# 1. 在新节点创建目录
sudo mkdir -p /data/rocketmq/broker/{logs,store}
sudo mkdir -p /data/rocketmq/nameserver/{logs,data}
sudo chown 3000:3000 /data/rocketmq -R

# 2. 复制配置文件到新节点
scp /data/rocketmq/broker/broker.conf root@<new-node>:/data/rocketmq/broker/
scp /data/rocketmq/nameserver/namesrv.conf root@<new-node>:/data/rocketmq/nameserver/

# 3. 修改新节点配置（brokerId、brokerIP1、jRaftServerId 等）

# 4. 在新节点启动服务
cd /data/rocketmq && docker compose up -d

# 5. 验证新节点注册
docker exec rocketmq-nameserver sh mqadmin clusterList -n 192.168.3.230:9876

---

十五、总结

15.1 部署检查清单

15.1.1 所有3台节点（192.168.3.230、192.168.3.200、192.168.3.110）

• NameServer 目录创建完成（/data/rocketmq/nameserver/{logs,data}）
• NameServer 目录权限设置正确（chown 3000:3000 /data/rocketmq -R）
• NameServer 配置文件正确（/data/rocketmq/nameserver/namesrv.conf）
• jRaftServerId 配置唯一（每个节点对应自己的 IP）
• Docker Compose 配置文件正确（包含 NameServer 服务）
• 防火墙规则配置正确（9876、9880、9770 端口开放）
• NameServer 启动成功，日志无错误
• NameServer 之间网络互通

15.1.2 高性能机节点（192.168.3.230、192.168.3.200）

• Broker 目录创建完成（/data/rocketmq/broker/{logs,store}）
• Broker 目录权限设置正确（chown 3000:3000 /data/rocketmq -R）
• Broker 配置文件正确（/data/rocketmq/broker/broker.conf）
• brokerId 配置正确（192.168.3.230 为 0，192.168.3.200 为 1）
• brokerIP1 配置正确（对应当前节点 IP）
• Proxy 配置文件正确（/data/rocketmq/broker/rmq-proxy.json）
• Docker Compose 配置文件正确（包含 Broker 服务）
• 防火墙规则配置正确（10911、10909、18080、18081 端口开放）
• Broker 启动成功，日志无错误
• Broker 成功注册到所有 NameServer

15.1.3 Dashboard 节点（建议在 192.168.3.230）

• Docker Compose 配置文件正确（包含 Dashboard 服务）
• 防火墙规则配置正确（8086 端口开放）
• Dashboard 启动成功
• Dashboard 可以正常访问（http://192.168.3.230:8086）

15.1.4 集群整体验证

• 3 个 NameServer 都正常运行
• 2 个 Broker 都正常运行
• Controller 集群选举成功（有 1 个 Leader）
• Controller 模式已启用（ENABLED）
• Broker 主从关系正常（1 Master + 1 Slave）
• Dashboard 显示集群状态正常

15.2 最佳实践

1. 架构设计：

   • 3台 NameServer 确保服务注册发现的高可用
   • 2台 Broker 部署在高性能机，低配机仅参与选举
   • Controller 跨3台机部署，确保选举的高可用性

2. 数据可靠性：根据业务需求选择 brokerRole 和 flushDiskType

3. 监控告警：建立完善的监控和告警机制，及时发现异常

4. 定期备份：定期备份配置文件和数据，防止数据丢失

5. 安全加固：生产环境建议开启 ACL 认证和 TLS 加密

6. 性能优化：根据实际负载调整 JVM 参数和系统参数

7. 日志管理：定期清理日志，避免磁盘满

8. 资源规划：低配机仅部署 NameServer，高性能机部署 Broker，资源利用率最大化

---

参考资料：

• RocketMQ 官方文档
• RocketMQ 5.x Controller 模式介绍
• jRaft 官方文档