运维手册

# 前言

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

# 适用对象

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

# 相关文档

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

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

# 技术支持

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

  • 网址：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. 出现异常及错误的日志、截图等详细信息

# 日常运维

# 服务管理

# 启动服务

# 启动 MQTT 服务
bin/admq-service start

# 启动应用
bin/admq-mqtt start
1
2
3
4
5

# 停止服务

# 停止应用
bin/admq-mqtt stop

# 停止 MQTT 服务
bin/admq-service stop
1
2
3
4
5

# 查看服务状态

# 查看服务状态
bin/admq-service status

# 查看节点状态
bin/admq-mqtt ctl status

# 查看集群状态
bin/admq-mqtt ctl cluster status
1
2
3
4
5
6
7
8

# 重启服务

# 重启服务
bin/admq-service restart
1
2

# 日志管理

# 日志位置

日志类型 路径 说明
服务日志 log/admq-mqtt.log MQTT Broker 主日志
崩溃日志 log/erlang.log.* Erlang VM 崩溃日志
管控台日志 /opt/admq-manager-V3.0.2/logs/ 管控台运行日志

# 日志级别配置

# 查看当前日志级别
bin/admq-mqtt ctl log handlers list

# 动态调整日志级别
bin/admq-mqtt ctl log set-level debug
bin/admq-mqtt ctl log set-level info
bin/admq-mqtt ctl log set-level warning
bin/admq-mqtt ctl log set-level error
1
2
3
4
5
6
7
8

# 日志轮转

# etc/admq-mqtt.conf
log.file {
  path = "log/admq-mqtt.log"
  rotation_size = "10MB"
  rotation_count = 5
  level = warning
}
1
2
3
4
5
6
7

# 监控检查

# 日常检查清单

检查项 检查命令 正常标准
节点状态 admq-mqtt ctl cluster status 所有节点在线
连接数 admq-mqtt ctl stats 在正常范围内
内存使用 admq-mqtt ctl status 低于内存上限
磁盘空间 df -h 高于最低要求
消息吞吐 运行时监控 无异常波动
慢订阅 慢订阅管理 无大量慢订阅

# 健康检查脚本

#!/bin/bash

# 节点健康检查
bin/admq-mqtt ctl status

# 连接数检查
CONN_COUNT=$(bin/admq-mqtt ctl stats | grep connections.count | awk '{print $2}')
if [ "$CONN_COUNT" -gt 500000 ]; then
    echo "WARNING: Connection count $CONN_COUNT exceeds threshold"
fi

# 内存使用检查
MEM_USAGE=$(bin/admq-mqtt ctl status | grep memory.used | awk '{print $2}')
echo "Memory usage: $MEM_USAGE"
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 配置管理

# 配置文件

# admq-mqtt.conf

主配置文件，位于 etc/admq-mqtt.conf。

# 节点配置
node.name = admq@mqtt-node1
node.cookie = your-secret-cookie

# 集群配置
cluster.discovery = static
cluster.static.seeds = admq@mqtt-node1,admq@mqtt-node2,admq@mqtt-node3

# 监听器配置
listeners.tcp.default {
  bind = "0.0.0.0:1883"
  max_connections = 1024000
}

listeners.ssl.default {
  bind = "0.0.0.0:8883"
  ssl_options {
    certfile = "etc/certs/server.crt"
    keyfile = "etc/certs/server.key"
    cacertfile = "etc/certs/ca.crt"
  }
}

# 认证器配置
authentication = [
  {
    mechanism = password_based
    backend = built_in_database
    enable = true
  }
]

# 授权源配置
authorization {
  sources = [
    {
      type = built_in_database
      enable = true
    }
  ]
}
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
30
31
32
33
34
35
36
37
38
39
40
41

# 动态配置

# 查看当前配置
bin/admq-mqtt ctl conf show

# 更新配置
bin/admq-mqtt ctl conf update "log.level=info"

# 重置配置
bin/admq-mqtt ctl conf reset
1
2
3
4
5
6
7
8

# 故障排查

# 常见问题及解决方案

# 服务无法启动

现象 可能原因 解决方案
端口被占用 1883/8883/8083 端口被占用 查找并停止占用进程，或修改监听端口
Erlang Cookie 不一致 集群节点 Cookie 不匹配 同步 .erlang.cookie 文件
内存不足 系统内存不足 增加内存或优化配置
配置错误 admq-mqtt.conf 格式错误 检查配置文件语法

# 客户端无法连接

现象 可能原因 解决方案
认证失败 用户名密码错误 检查用户配置
ACL 拒绝 权限不足 检查 ACL 规则
监听器未启动 监听器未启用 检查监听器状态
网络不通 防火墙或网络问题 检查网络连通性

# 消息投递异常

现象 可能原因 解决方案
订阅者收不到消息 主题不匹配 检查主题和通配符
消息重复 QoS 1 正常行为 业务侧实现幂等处理
消息丢失 QoS 0 不保证到达 改用 QoS 1/2
消费延迟 慢订阅或网络延迟 检查慢订阅和网络状况

# 集群异常

现象 可能原因 解决方案
节点离线 网络故障或服务异常 检查网络连通性，重启服务
脑裂 网络分区导致集群分裂 检查网络分区，必要时重建集群
会话不同步 网络延迟 等待自动同步

# 故障排查命令

# 查看节点状态
bin/admq-mqtt ctl status

# 查看集群状态
bin/admq-mqtt ctl cluster status

# 查看在线客户端
bin/admq-mqtt ctl clients list

# 查看订阅列表
bin/admq-mqtt ctl subscriptions list

# 查看保留消息
bin/admq-mqtt ctl retained list

# 查看告警
bin/admq-mqtt ctl alarms list

# 查看日志
bin/admq-mqtt ctl log handlers list
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 备份与恢复

# 配置备份

# 导出当前配置
bin/admq-mqtt ctl conf show > admq-mqtt-config-backup.json

# 备份配置文件
cp etc/admq-mqtt.conf backup/admq-mqtt.conf.$(date +%Y%m%d)
1
2
3
4
5

# 数据备份

# 创建数据备份
bin/admq-mqtt ctl data backup

# 查看备份列表
bin/admq-mqtt ctl data backup list
1
2
3
4
5

# 定期备份脚本

#!/bin/bash

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

# 备份配置
bin/admq-mqtt ctl conf show > $BACKUP_DIR/config.json
cp etc/admq-mqtt.conf $BACKUP_DIR/

# 创建数据备份
bin/admq-mqtt ctl data backup $BACKUP_DIR/data-backup

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

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

# 安全加固

# 网络安全

# 防火墙配置

# 开放必要端口
firewall-cmd --permanent --add-port=1883/tcp    # MQTT TCP
firewall-cmd --permanent --add-port=8883/tcp    # MQTT over SSL
firewall-cmd --permanent --add-port=8083/tcp    # MQTT over WebSocket
firewall-cmd --permanent --add-port=8084/tcp    # MQTT over WSS
firewall-cmd --permanent --add-port=14567/tcp   # MQTT over QUIC
firewall-cmd --permanent --add-port=18083/tcp   # Dashboard
firewall-cmd --permanent --add-port=12305/tcp   # 管控台 HTTP
firewall-cmd --permanent --add-port=12306/tcp   # 管控台 HTTPS
firewall-cmd --permanent --add-port=4370/tcp    # Erlang Distribution
firewall-cmd --permanent --add-port=5370/tcp    # Erlang Distribution SSL
firewall-cmd --reload
1
2
3
4
5
6
7
8
9
10
11
12

# SSL/TLS 配置

# etc/admq-mqtt.conf
listeners.ssl.default {
  bind = "0.0.0.0:8883"
  ssl_options {
    certfile = "etc/certs/server.crt"
    keyfile = "etc/certs/server.key"
    cacertfile = "etc/certs/ca.crt"
    verify = verify_peer
    fail_if_no_peer_cert = false
    versions = ["tlsv1.2", "tlsv1.3"]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

# 访问控制

# 默认拒绝策略

# etc/admq-mqtt.conf
authorization {
  no_match = deny
  deny_action = ignore
  sources = [
    {
      type = built_in_database
      enable = true
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11

# 超级用户管理

# 创建超级用户
bin/admq-mqtt ctl admins add admin password

# 谨慎使用超级用户权限
1
2
3
4

# 审计日志

# etc/admq-mqtt.conf
log.audit {
  enable = true
  path = "log/audit.log"
  rotation_size = "10MB"
  rotation_count = 10
}
1
2
3
4
5
6
7

# 性能监控

# Prometheus 监控

# 启用 Prometheus 指标

# etc/admq-mqtt.conf
prometheus {
  enable = true
  bind = "0.0.0.0:18083"
  push_gateway_server = "http://localhost:9091"
  interval = "15s"
}
1
2
3
4
5
6
7

# 监控指标

指标 说明
emqx_connections_count 当前连接数
emqx_sessions_count 当前会话数
emqx_topics_count 当前主题数
emqx_subscriptions_count 当前订阅数
emqx_messages_received 接收消息数
emqx_messages_sent 发送消息数
emqx_messages_dropped 丢弃消息数
emqx_bytes_received 接收字节数
emqx_bytes_sent 发送字节数

# Grafana 仪表盘

导入 EMQX 官方 Grafana 仪表盘，监控集群状态。

# 告警规则

# Prometheus 告警规则示例
groups:
  - name: mqtt_alerts
    rules:
      - alert: MQTTNodeDown
        expr: up{job="admq-mqtt"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "MQTT node is down"
      
      - alert: MQTTHighConnections
        expr: emqx_connections_count > 800000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "MQTT connection count is high"
      
      - alert: MQTTMessagesDropped
        expr: rate(emqx_messages_dropped[5m]) > 100
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "MQTT messages are being dropped"
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

# 升级维护

# 版本升级

# 升级前准备

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

# 升级步骤

# 1. 停止服务
bin/admq-service stop

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

# 3. 升级软件包
# 下载新版本安装包并解压
tar zxvf admq-mqtt-V2.0.7.tar.gz -C /opt/

# 4. 迁移配置
cp etc/admq-mqtt.conf /opt/admq-mqtt-V2.0.7/etc/

# 5. 启动服务
cd /opt/admq-mqtt-V2.0.7
bin/admq-service start

# 6. 验证升级
bin/admq-mqtt ctl status
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 集群滚动升级

  1. 一次升级一个节点
  2. 确认节点恢复正常后再升级下一个
  3. 确保集群始终有可用的节点

# 运维最佳实践

  1. 定期检查：建立日常检查机制，及时发现潜在问题
  2. 监控告警：配置完善的监控和告警体系
  3. 备份策略：制定定期备份策略，确保数据安全
  4. 文档记录：记录所有运维操作和变更
  5. 容量规划：定期评估集群容量，提前扩容
  6. 安全更新：及时更新安全补丁
  7. 灾难演练：定期进行故障恢复演练
编辑页面 (opens new window)
#运维手册

← 性能优化手册→