安装手册

# 前言

本文档为金蝶Apusic分布式消息队列for MQTT（Apusic Distributed Message Queue，简称：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. 出现异常及错误的日志、截图等详细信息

# 环境准备

# 系统要求

组件 最低要求 推荐配置
CPU 4 核 8 核及以上
内存 8 GB 16 GB 及以上
磁盘 100 GB SSD 500 GB 及以上 SSD
网络 1 Gbps 10 Gbps
操作系统 Linux (CentOS 7+, Ubuntu 18.04+, 麒麟, 统信) -

# 依赖软件

软件 版本要求 说明
OpenSSL 1.1.1+ SSL/TLS 加密依赖
Java 1.8+ 管控台运行依赖(已内置)

# 网络要求

端口 用途 说明
1883 MQTT TCP 标准 MQTT 接入
8883 MQTT over SSL 加密 MQTT 接入
8083 MQTT over WebSocket WebSocket 接入
8084 MQTT over WSS 加密 WebSocket 接入
14567 MQTT over QUIC QUIC 协议接入
18083 MQTT Http API 管理后台API
4370 集群节点间通信 集群节点间通信
5370 集群节点间通信（SSL） 集群节点间通信（SSL）

# 单机部署

# 安装 ADMQ for MQTT

1.修改主机名称

要求是 FQDN（完全限定域名）：如 mqtt.apusic.com

 # 查看主机名称 
 hostname  
 # 修改主机名 
 hostname mqtt.apusic.com
1
2
3
4

2.解压安装包

# 解压安装包
mkdir -p /apusic
tar zxvf ADMQ-V2.0.6.587-MQTT-20260617.tar.gz -C /apusic/
cd /apusic/admq-mqtt
1
2
3
4

3.修改节点名称、监听端口等信息（可选）

vi config/mqtt.conf
---
# 节点名称,name修改为完全限定域名
node {
  name = "emqx@mqtt.apusic.com"
  cookie = "mqttpnuvjvgg"
}

# MQTT TCP 监听
listeners.tcp.default {
  bind = "10.0.0.196:1883"
  max_connections = 1024000
}

# WebSocket 监听
listeners.ws.default {
  bind = "10.0.0.196:8083"
  max_connections = 1024000
}

# WebSocket over TLS 监听
listeners.wss.default {
  bind = "10.0.0.196:8084"
  max_connections = 512000
}
---
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

4.授权许可

将获取到的 license.xml 文件上传至部署目录根路径

# 确认文件位置
ls -l /apusic/admq-mqtt/license.xml
1
2

5.启动服务

bin/admq-daemon start mqtt server
1

6.服务验证

  • 检查进程状态
ps -ef | grep admq-mqtt
1

image-20260702141411116

  • 检查端口监听

使用 netstat 确认 1883 端口是否处于 LISTEN 状态：

ss -nltp | grep 1883
1

预期输出：

image-20260702141553489

# 集群部署

# 集群架构说明

ADMQ for MQTT 支持以下集群模式：

集群模式 节点数 说明
普通集群 3+ 无状态节点集群，支持水平扩展
高可用集群 3+ 多节点部署，自动故障转移

# 集群部署步骤

1.各节点安装ADMQ for MQTT

参考单机安装步骤在各节点安装ADMQ for MQTT，先不用启动

提示：各节点的hostname需要设置不同的域名

2.配置各节点 hosts 文件

# /etc/hosts
192.168.1.101 mqtt1.apusic.com
192.168.1.102 mqtt2.apusic.com
192.168.1.103 mqtt3.apusic.com
1
2
3
4

3.配置各节点 Erlang Cookie

# 创建data目录
cd /apusic/admq-mqtt
mkdir -p data
# 设置 Erlang Cookie 
echo "mqttpnuvjvgg" > data/.erlang.cookie
1
2
3
4
5

4.配置各节点集群发现

以下是某一节点的配置示例

# 节点名称（每台不同，格式：emqx@IP或主机名）
node {
    name = "emqx@mqtt1.apusic.com"
    cookie = "mqttpnuvjvgg"   # 和上一步的Cookie保持一致
}

# 集群配置（所有节点完全一致）
cluster {
    discovery_strategy = static
    static {
        seeds = ["emqx@mqtt1.apusic.com", "emqx@mqtt2.apusic.com", "emqx@mqtt3.apusic.com"]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

5.启动各节点服务

bin/admq-daemon start mqtt server
1

6.验证集群状态

bin/admq mqtt admin ctl cluster status
1

# 常见问题及排查

# 服务启动失败

可能原因 解决方案
端口冲突 检查 1883、8883、8083、8084、18083 端口是否被占用
权限不足 确保 admq-mqtt 目录权限正确
内存不足 检查系统内存，确保满足最低要求

# 集群加入失败

可能原因 解决方案
Erlang Cookie 不一致 确保所有节点的 .erlang.cookie 内容一致
网络不通 检查节点间网络连通性和防火墙设置
主机名解析失败 确保 /etc/hosts 或 DNS 配置正确

# 客户端无法连接

可能原因 解决方案
监听器未启动 检查监听器管理页面，确认监听器已启用
认证失败 检查用户名密码、认证器配置
ACL 权限不足 检查 ACL 规则是否允许对应主题访问
防火墙阻挡 开放 MQTT 相关端口
编辑页面 (opens new window)
#安装手册

← 快速使用手册→