运维手册

# 前言

本文档为金蝶Apusic分布式消息队列for RocketMQ（Apusic Distributed Message Queue for RocketMQ，简称：ADMQ for RocketMQ）的运维手册，旨在为中间件运维人员提供ADMQ for RocketMQ标准化运维指南，涵盖安装部署、配置优化、日常运维、故障排查、安全加固等核心场景，确保ADMQ for RocketMQ产品服务稳定、高效、安全运行。

# 适用对象

本文档适用于IT信息化业务负责人、研发经理、软件项目经理、软件架构师、运维工程师。

# 相关文档

了解更多ADMQ for RocketMQ产品相关的信息，请参阅以下ADMQ for RocketMQ产品手册文档集：

序号 手册文档 说明
1 金蝶Apusic分布式消息队列for RocketMQ 快速使用手册 简单介绍了如何快速上手使用ADMQ for RocketMQ 。
2 金蝶Apusic分布式消息队列for RocketMQ 安装手册 详细介绍如何在各操作系统上安装ADMQ for RocketMQ，以及ADMQ for RocketMQ服务启停等操作。
3 金蝶Apusic分布式消息队列for RocketMQ 消息引擎用户手册 详细介绍 ADMQ for RocketMQ 消息引擎相关功能的使用、配置、管理及配套工具的使用方法。
4 金蝶Apusic分布式消息队列for RocketMQ 管控台用户手册 详细介绍ADMQ for RocketMQ管控台相关功能的使用和操作说明。
5 金蝶Apusic分布式消息队列for RocketMQ 开发手册 详细介绍基于各开发语言进行ADMQ for RocketMQ客户端应用开发的说明。
6 金蝶Apusic分布式消息队列for RocketMQ 迁移手册 详细介绍从RocketMQ迁移到ADMQ for RocketMQ的说明。
7 金蝶Apusic分布式消息队列for RocketMQ 运维手册 详细介绍ADMQ for RocketMQ的监控、运维、安全加固等运维说明。
8 金蝶Apusic分布式消息队列for RocketMQ 性能优化手册 详细介绍ADMQ for RocketMQ性能调优的说明。

# 技术支持

ADMQ for RocketMQ产品提供全面的技术支持服务，您可以通过以下方式获得技术支持：

  • 网址：www.apusic.com
  • 电话：400-855-5800
  • 邮箱：support@apusic.com
  • 金蝶云社区：https://vip.kingdee.com/?productId=73&productLineId=14&lang=zh-CN

您在取得技术支持时，请提供如下信息：

  1. 您的姓名
  2. 公司信息与联系方式
  3. 操作系统及其版本
  4. 产品版本号
  5. 出现异常及错误的日志、截图等详细信息

# 日常运维

# 服务管理

# 启动服务

# 启动 NameServer
bin/rocketmq start nameserver

# 启动 Broker
bin/rocketmq start broker

# 启动管控台
bin/admq-service start
1
2
3
4
5
6
7
8

# 停止服务

# 停止 Broker
bin/rocketmq stop broker

# 停止 NameServer
bin/rocketmq stop nameserver

# 停止管控台
bin/admq-service stop
1
2
3
4
5
6
7
8

# 查看服务状态

# 查看进程
ps -ef | grep rocketmq

# 查看 NameServer 日志
tail -f logs/namesrv.log

# 查看 Broker 日志
tail -f logs/broker.log

# 查看集群状态
bin/mqadmin clusterList -n localhost:9876
1
2
3
4
5
6
7
8
9
10
11

# 重启服务

# 先停止再启动
bin/rocketmq stop broker
sleep 5
bin/rocketmq start broker
1
2
3
4

# 日志管理

# 日志位置

日志类型 路径 说明
NameServer 日志 logs/namesrv.log NameServer 运行日志
Broker 日志 logs/broker.log Broker 运行日志
管控台日志 /opt/admq-manager-V2.0.6/logs/ 管控台运行日志

# 日志级别配置

# 查看当前日志级别
# 在 conf/logback_namesrv.xml 和 conf/logback_broker.xml 中配置

# 动态调整日志级别（通过 JMX 或配置文件）
# 修改 logback 配置文件后自动生效
1
2
3
4
5

# 日志轮转

# logback 自动轮转配置
# 在 logback_broker.xml 中配置：
# <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
#     <fileNamePattern>${user.home}/logs/broker.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
#     <maxHistory>30</maxHistory>
# </rollingPolicy>
1
2
3
4
5
6

# 监控检查

# 日常检查清单

检查项 检查命令 正常标准
NameServer 状态 ps -ef | grep mqnamesrv 进程存在
Broker 状态 ps -ef | grep mqbroker 进程存在
集群状态 mqadmin clusterList 所有 Broker 在线
磁盘空间 df -h 高于 disk_free_limit
内存使用 free -m 低于 vm_memory_high_watermark
消息堆积 mqadmin topicStatus 无异常堆积
消费延迟 mqadmin consumerProgress 延迟在合理范围

# 健康检查脚本

Bash
# 目前内置对应的监控脚本
./bin/monitor-namesrv.sh
./bin/monitor-broker.sh
1
2
3
4

# 配置管理

# Broker 配置

# broker.conf

主配置文件，位于 conf/broker.conf。

# 集群配置
brokerClusterName=AdmqCluster
brokerName=broker-a
brokerId=0

# NameServer 地址
namesrvAddr=node1:9876;node2:9876

# 存储配置
storePathRootDir=/data/rocketmq/store
storePathCommitLog=/data/rocketmq/store/commitlog

# 刷盘配置
flushDiskType=ASYNC_FLUSH
flushIntervalCommitLog=500

# 主从配置
brokerRole=ASYNC_MASTER
haMasterAddress=

# 消息配置
defaultTopicQueueNums=8
autoCreateTopicEnable=false
autoCreateSubscriptionGroup=false

# 限流配置
sendMessageThreadPoolNums=16
pullMessageThreadPoolNums=16
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# NameServer 配置

# namesrv.properties
listenPort=9876
# 其他配置较少，主要为 JVM 参数
1
2
3

# 动态配置

# 查看 Broker 配置
bin/mqadmin getBrokerConfig -n localhost:9876 -b broker-a:10911

# 更新 Broker 配置
bin/mqadmin updateBrokerConfig -n localhost:9876 -b broker-a:10911 -k sendMessageThreadPoolNums -v 32

# 查看 NameServer 配置
bin/mqadmin getNameServerConfig -n localhost:9876

# 更新 NameServer 配置
bin/mqadmin updateNameServerConfig -n localhost:9876 -k key -v value
1
2
3
4
5
6
7
8
9
10
11

# 故障排查

# 常见问题及解决方案

# NameServer 启动失败

现象 可能原因 解决方案
端口冲突 9876 端口被占用 查找并停止占用进程
JDK 未安装 未安装 JDK 或版本过低 安装 JDK 1.8+
权限不足 目录权限不正确 确保目录权限正确

# Broker 启动失败

现象 可能原因 解决方案
NameServer 不可达 网络不通或配置错误 检查 namesrvAddr 配置
端口冲突 10911 端口被占用 修改 listenPort
磁盘空间不足 磁盘空间低于限制 清理磁盘或调整 disk_free_limit
配置错误 broker.conf 格式错误 检查配置文件

# 消息发送失败

现象 可能原因 解决方案
Topic 未创建 未提前创建 Topic 创建 Topic 或开启自动创建
Broker 不可达 网络不通或 Broker 宕机 检查 Broker 状态
权限不足 ACL 配置不正确 检查 ACL 配置
磁盘已满 CommitLog 目录满 清理磁盘或调整保留策略

# 消息消费异常

现象 可能原因 解决方案
消息堆积 消费者处理速度过慢 增加消费者或优化消费逻辑
消费延迟 网络延迟或消费逻辑复杂 优化消费逻辑
消费失败 业务逻辑异常 检查业务逻辑和重试机制
重复消费 消费者未正确返回消费状态 确保返回正确的消费状态

# 故障排查命令

# 查看集群状态
bin/mqadmin clusterList -n localhost:9876

# 查看 Broker 状态
bin/mqadmin brokerStatus -n localhost:9876 -b broker-a:10911

# 查看 Topic 状态
bin/mqadmin topicStatus -n localhost:9876 -t test-topic

# 查看消费者进度
bin/mqadmin consumerProgress -n localhost:9876 -g test-group

# 查看消费者连接
bin/mqadmin consumerConnection -n localhost:9876 -g test-group

# 查看生产者连接
bin/mqadmin producerConnection -n localhost:9876 -t test-topic -g test-group

# 查看消息
bin/mqadmin queryMsgByKey -n localhost:9876 -t test-topic -k test-key
bin/mqadmin queryMsgById -n localhost:9876 -i message-id

# 查看消息轨迹
bin/mqadmin printMsg -n localhost:9876 -t test-topic

# 查看 Broker 统计
bin/mqadmin brokerConsumeStats -n localhost:9876 -b broker-a:10911
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 备份与恢复

# 配置备份

# 导出 Topic 配置
bin/mqadmin topicList -n localhost:9876 > topics-backup.txt

# 导出消费者组配置
bin/mqadmin consumerProgress -n localhost:9876 > consumer-groups-backup.txt

# 备份 Broker 配置文件
cp conf/broker.conf backup/broker.conf.$(date +%Y%m%d)

# 备份 NameServer 配置文件
cp conf/namesrv.properties backup/namesrv.properties.$(date +%Y%m%d)
1
2
3
4
5
6
7
8
9
10
11

# 数据备份

# CommitLog 备份

# CommitLog 是消息存储文件，位于 store/commitlog 目录
# 建议定期备份整个 store 目录

# 停止 Broker 后备份
bin/rocketmq stop broker
tar czf backup/store-$(date +%Y%m%d).tar.gz store/
nohup bin/rocketmq start broker
1
2
3
4
5
6
7

# 增量备份

# 使用 rsync 进行增量备份
rsync -avz --delete store/ backup/store/
1
2

# 定期备份脚本

#!/bin/bash

BACKUP_DIR="/backup/rocketmq/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# 备份配置
cp conf/broker.conf $BACKUP_DIR/
cp conf/namesrv.properties $BACKUP_DIR/

# 备份 Topic 和消费者组
bin/mqadmin topicList -n localhost:9876 > $BACKUP_DIR/topics.txt
bin/mqadmin consumerProgress -n localhost:9876 > $BACKUP_DIR/consumer-groups.txt

# 压缩备份
tar czf $BACKUP_DIR.tar.gz $BACKUP_DIR
rm -rf $BACKUP_DIR

# 保留最近7天备份
find /backup/rocketmq -name "*.tar.gz" -mtime +7 -delete
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 安全加固

# 网络安全

# 防火墙配置

# 开放必要端口
firewall-cmd --permanent --add-port=9876/tcp    # NameServer
firewall-cmd --permanent --add-port=10911/tcp   # Broker
firewall-cmd --permanent --add-port=10909/tcp   # Broker VIP
firewall-cmd --permanent --add-port=10912/tcp   # Broker HA
firewall-cmd --permanent --add-port=12305/tcp   # 管控台 HTTP
firewall-cmd --permanent --add-port=12306/tcp   # 管控台 HTTPS
firewall-cmd --reload
1
2
3
4
5
6
7
8

# TLS 配置

# broker.conf
tls.server.mode=enforcing
tls.server.certPath=/path/to/server.crt
tls.server.keyPath=/path/to/server.key
tls.server.trustCertPath=/path/to/ca.crt

tls.client.keyPath=conf/auth/client.key
tls.client.keyPassword=123456
tls.client.certPath=conf/auth/client.pem
tls.client.trustCertPath=conf/auth/ca.pem
1
2
3
4
5
6
7
8
9
10

# 访问控制

# ACL (1.0-适用4.x)配置

# conf/plain_acl.yml
globalWhiteRemoteAddresses:
  - 10.*.*.*
  - 192.168.*.*

accounts:
  - accessKey: admin
    secretKey: admin-password
    whiteRemoteAddress:
    admin: true
    defaultTopicPerm: CREATE+WRITE+READ
    defaultGroupPerm: CREATE+WRITE+READ
    
  - accessKey: app-user
    secretKey: app-password
    whiteRemoteAddress:
    admin: false
    defaultTopicPerm: DENY
    defaultGroupPerm: SUB
    topicPerms:
      - app-topic=CREATE+WRITE+READ
    groupPerms:
      - app-group=READ
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 启用 ACL

# 更新 Broker 配置启用 ACL
bin/mqadmin updateBrokerConfig -n localhost:9876 -b broker-a:10911 -k aclEnable -v true

# 重启 Broker 生效
bin/rocketmq stop broker
nohup bin/rocketmq start broker
1
2
3
4
5
6

# ACL （2.0-适用5.x版本）配置

# 配置文件修改

修改broker.conf

# 启用认证
authenticationEnabled = true
authenticationMetadataProvider = org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider

# 启用授权
authorizationEnabled = true
authorizationMetadataProvider = org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider

# 初始化管理员用户（首次启动自动创建）
initAuthenticationUser = {"username":"rocketmq","password":"12345678"}

# 组件间认证凭证（用于Broker主从同步、集群内部通信等）
innerClientAuthenticationCredentials = {"accessKey":"rocketmq","secretKey":"12345678"}
1
2
3
4
5
6
7
8
9
10
11
12
13

通过修改broker.conf，需要重启集群

# 配置mqadmin工具

启用ACL后，需要配置mqadmin工具的认证凭证才能执行管理命令。

编辑 conf/tools.yml 文件：

# 使用初始化的管理员用户凭证
accessKey: rocketmq
secretKey: 12345678
1
2
3

# 创建业务用户和授权

生产者

# 创建生产者用户
bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
  -u producer_user \
  -p producer123 \
  -t Normal

# 授予Topic发送权限
bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
  -s User:producer_user \
  -r Topic:TestTopic \
  -a Pub \
  -d Allow
1
2
3
4
5
6
7
8
9
10
11
12

消费者

# 创建消费者用户
bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
  -u consumer_user -p consumer123 -t Normal

# 授予消费者消费权限
bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
  -s User:consumer_user -r Topic:TestTopic,Group:TestGroup -a Sub -d Allow
1
2
3
4
5
6
7

# 验证配置

使用Java客户端发送一条测试消息：

SessionCredentials credentials = new SessionCredentials("producer_user", "producer123");
StaticSessionCredentialsProvider credentialsProvider = 
    new StaticSessionCredentialsProvider(credentials);

ClientConfiguration clientConfiguration = ClientConfiguration.newBuilder()
    .setEndpoints("127.0.0.1:10911")
    .setCredentialProvider(credentialsProvider)
    .build();
// ... 创建Producer并发送消息
1
2
3
4
5
6
7
8
9

# 审计日志

# 开启审计日志
# 在 conf/logback_broker.xml 中配置 audit appender
# 审计日志记录所有管理操作和消息操作
1
2
3

# 性能监控

# Prometheus 监控

# 启用 Prometheus Exporter

# 启用 prometheus 插件
bin/mqadmin updateBrokerConfig -n localhost:9876 -b broker-a:10911 -k metricsExporterType -v PROM
1
2

# 监控信息

启用后，首先在集群的http://ip:5557/metrics地址展示对应的监控指标信息；

然后经由管控台的Prometheus组件收集对应集群的信息

image-20260617144815476

呈现对应的监控信息到监控大盘（监控大盘主要展示集群，节点，主题，订阅组四个维度的信息） image-20260617144912135

# 升级维护

# 版本升级

# 升级前准备

  1. 备份配置文件和数据
  2. 查看版本发布说明
  3. 在测试环境验证升级流程

# 升级步骤

# 1. 停止 Broker
bin/rocketmq stop broker

# 2. 备份数据
cp -r store backup/store-$(date +%Y%m%d)

# 3. 升级软件包
# 下载新版本安装包并解压
tar zxvf  ADMQ-V2.0.6.534-RocketMQ-20260625.tar.gz -C /apusic/
unzip rocketmq-V5.3.4-all.zip
mv rocketmq-V5.3.4-all nameserver
cd /apusic/nameserver

unzip rocketmq-V5.3.4-all.zip
mv rocketmq-V5.3.4-all broker
cd /apusic/broker

# 4. 迁移配置或者依赖包
cp conf/namesrv.properties /apusic/nameserver/conf/
cp conf/broker.conf /apusic/broker/conf/

# 5. 启动服务
cd /apusic/nameserver
bin/rocketmq start nameserver
cd /apusic/broker
bin/rocketmq start broker

# 6. 验证升级
bin/mqadmin brokerStatus -n localhost:9876 -b broker-a:10911
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 集群滚动升级

  1. 一次升级一个 Broker 节点
  2. 确认节点恢复正常后再升级下一个
  3. 确保集群始终有可用的 Broker
编辑页面 (opens new window)
#运维手册

← 性能优化手册→