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）执行

```bash
# 创建 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）执行

```bash
# 仅创建 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 服务：

```yaml
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 服务：

```yaml
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 服务：

```yaml
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`：

```properties
# 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`：

```properties
# ========== 节点标识配置（每个节点不同） ==========
# 节点 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`：

```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` 中添加：

```properties
# 开启 ACL 认证
aclEnable = true

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

#### 8.1.2 创建 ACL 配置文件

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

```yaml
# 全局白名单（允许访问的 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 配置文件挂载：

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

### 8.2 TLS/SSL 加密（可选）

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

#### 8.2.1 生成证书

```bash
# 生成 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` 中添加：

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

挂载证书文件：

```yaml
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台节点执行）

```bash
# 进入目录
cd /data/rocketmq

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

# 查看启动状态
docker compose ps
```

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

```bash
# 进入目录
cd /data/rocketmq

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

# 查看启动状态
docker compose ps
```

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

```bash
# 进入目录
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

```bash
# 查看日志（所有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

```bash
# 查看日志（仅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

```bash
# 查看 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 参数：

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

### 11.2 操作系统优化

```bash
# 增加文件描述符限制
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 数据备份

```bash
# 备份 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 数据恢复

```bash
# 停止 Broker
docker compose stop rocketmq-broker

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

# 启动 Broker
docker compose start rocketmq-broker
```

---

## 十四、升级和扩容

### 14.1 版本升级

```bash
# 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 集群扩容

```bash
# 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 官方文档](https://rocketmq.apache.org/zh/docs/)
- [RocketMQ 5.x Controller 模式介绍](https://rocketmq.apache.org/zh/docs/featureBehavior/05controller)
- [jRaft 官方文档](https://github.com/sofastack/sofa-jraft)