EMQX 详细安装指南：从零搭建 MQTT 消息服务器

适用于 CentOS 7/8、Rocky Linux 8/9、RHEL 8/9 等主流 Linux 发行版。本文以 EMQX 5.8.x 为例，涵盖从环境准备到安全加固的完整流程。

1. 环境准备

1.1 系统要求

项目	最低配置	推荐配置
CPU	1 核	4 核及以上
内存	512 MB	4 GB 及以上
磁盘	1 GB 可用空间	10 GB 及以上（含日志与数据持久化）
操作系统	CentOS 7+ / Rocky Linux 8+ / RHEL 8+	Rocky Linux 9 / Ubuntu 22.04

提示：对于 2 核 2 GB 的低配云服务器，EMQX 完全可以正常运行。如果仅用于少量设备连接，资源绰绰有余；设备数超过 1000 台时，建议参考第 7 节进行调优。

1.2 检查系统版本

bash

# 查看操作系统版本
cat /etc/os-release

# 查看 CPU 架构（需为 x86_64 或 aarch64）
uname -m

# 查看可用内存
free -h

1.3 云服务器安全组配置（阿里云 / 腾讯云等）

登录云控制台，为 ECS 实例的安全组添加以下 入方向 规则：

端口	协议	用途	建议
`1883`	TCP	MQTT 标准协议端口	按需开放（仅客户端所在 IP 段）
`8883`	TCP	MQTT over TLS/SSL 加密端口	生产环境推荐开放
`8083`	TCP	MQTT over WebSocket 端口	如需 Web 端接入则开放
`8084`	TCP	MQTT over WebSocket (TLS) 端口	如需 Web 安全接入则开放
`18083`	TCP	Dashboard HTTP 管理后台	建议仅对运维 IP 开放

⚠️ 安全提示：Dashboard 端口（18083）切勿对所有 IP（0.0.0.0/0）开放。建议只允许办公网络或跳板机的 IP 地址访问。

2. 安装 EMQX

2.1 下载 RPM 安装包

首先确认你的操作系统与 EMQX 包的对应关系：

操作系统	推荐 EMQX 包后缀
CentOS 8 / Rocky Linux 8 / RHEL 8	`el8-amd64.rpm`
CentOS 7	`el7-amd64.rpm`
Rocky Linux 9 / RHEL 9	`el9-amd64.rpm`

bash

# 以 CentOS 8 / Rocky Linux 8 为例，下载 EMQX 5.8.0
# 建议先访问 https://www.emqx.com/zh/downloads/broker 确认最新版本号
wget https://www.emqx.com/zh/downloads/broker/5.8.0/emqx-5.8.0-el8-amd64.rpm

# 如果 wget 下载失败，检查网络连接或尝试使用 curl：
# curl -L -o emqx-5.8.0-el8-amd64.rpm \
#   https://www.emqx.com/zh/downloads/broker/5.8.0/emqx-5.8.0-el8-amd64.rpm

校验文件完整性（可选）：下载页面同时提供了 SHA256 校验值，可使用 sha256sum emqx-5.8.0-el8-amd64.rpm 核对。

2.2 执行安装

bash

# 使用 yum 本地安装（自动处理依赖）
sudo yum install ./emqx-5.8.0-el8-amd64.rpm -y

说明：如果你使用 root 账户登录，可省略 sudo。使用 ./ 前缀明确指定为本地文件，避免 yum 从远程仓库搜索同名包。

2.3 验证安装

bash

# 查看 EMQX 版本
emqx --version

# 查看安装的文件路径
rpm -ql emqx | head -20

关键目录说明：

路径	用途
`/etc/emqx/`	配置文件目录
`/var/log/emqx/`	日志文件目录
`/var/lib/emqx/`	数据持久化目录
`/usr/lib/emqx/bin/`	可执行文件目录

3. 启动与健康检查

3.1 启动服务

bash

# 启动 EMQX
sudo systemctl start emqx

# 设置开机自启
sudo systemctl enable emqx

# 查看运行状态
sudo systemctl status emqx

正常启动后，systemctl status emqx 输出中应包含 active (running)。

3.2 健康检查

bash

# 方式一：通过 systemctl 检查
sudo systemctl is-active emqx
# 输出 "active" 表示正常运行

# 方式二：通过 emqx 命令检查
emqx ping
# 输出 "pong" 表示 EMQX 正在运行

# 方式三：检查端口监听状态
ss -tlnp | grep -E '1883|18083|8083'
# 预期看到所有默认端口处于 LISTEN 状态

# 方式四：HTTP API 健康检查
curl -s http://localhost:18083/api/v5/status | python3 -m json.tool
# 返回 JSON 状态信息

3.3 查看日志

bash

# 实时查看 EMQX 日志
tail -f /var/log/emqx/emqx.log.*

# 查看最近的错误日志
grep -i error /var/log/emqx/emqx.log.* | tail -20

4. Dashboard 管理后台

4.1 首次访问

在浏览器中访问 http://<你的服务器公网IP>:18083
默认凭据：
- 用户名：admin
- 密码：public

4.2 首次登录后必做

⚠️ 强烈建议：登录后立即修改默认密码，防止未授权访问！

Dashboard 内修改路径：系统设置 → 用户管理 → 点击 admin 用户 → 修改密码。

5. 安全加固

5.1 关闭匿名访问 + 配置客户端认证

这是最重要的一步，确保只有持有合法凭据的客户端才能连接。

Dashboard 操作路径：

左侧菜单 → 访问控制 → 认证
点击创建按钮
选择认证方式：Password-Based（密码认证）
数据源选择：Built-in Database（内置数据库）
点击 下一步，进入 用户管理 标签页
点击添加，输入用户名和密码，点击保存

等价命令行方式（可选）：

bash

# 通过 EMQX CLI 添加用户
emqx ctl authentication create password-based \
  built_in_database mech=password_based

# 添加用户（需先完成上一步的认证器创建）
emqx ctl authentication add_user password-based:built_in_database \
  username='sanker' password='YourStrongPassword'

5.2 启用 TLS/SSL 加密（强烈推荐）

生产环境务必启用 TLS 加密，防止数据在传输过程中被窃听。

bash

# 1. 准备证书文件（以 Let's Encrypt 免费证书为例）
# 将证书和私钥放置到 EMQX 可读取的目录
sudo mkdir -p /etc/emqx/certs
sudo cp /path/to/fullchain.pem /etc/emqx/certs/
sudo cp /path/to/privkey.pem /etc/emqx/certs/
sudo chown -R emqx:emqx /etc/emqx/certs/
sudo chmod 600 /etc/emqx/certs/privkey.pem

# 2. 在 Dashboard 中配置 TLS 监听器：
#    左侧菜单 → 管理 → 监听器 → 找到 "SSL Default" 监听器（端口 8883）
#    → 编辑 → 开启 TLS → 填写证书和私钥路径

5.3 配置访问控制（ACL）

精细控制每个客户端对特定主题的读写权限。

Dashboard 操作路径：

左侧菜单 → 访问控制 → 授权
点击创建，选择 File 作为数据源
编辑授权规则，例如：

bash

# /etc/emqx/acl.conf 示例
# 允许所有客户端发布数据到自己的 data 主题
{allow, {username, "{username}"}, publish, ["data/{clientid}"]}.

# 允许所有订阅者订阅 data 主题
{allow, all, subscribe, ["data/#"]}.

# 仅允许特定用户订阅命令主题
{allow, {username, "admin"}, subscribe, ["cmd/#"]}.

# 拒绝其他所有操作
{deny, all}.

6. 防火墙与 SELinux 配置

6.1 服务器本地防火墙

即使云安全组已放行端口，服务器自身的防火墙（firewalld / iptables）也需配置，否则连接仍会被拦截。

bash

# 检查 firewalld 状态
sudo systemctl status firewalld

# 如果 firewalld 正在运行，添加端口规则
sudo firewall-cmd --permanent --add-port=1883/tcp
sudo firewall-cmd --permanent --add-port=8883/tcp
sudo firewall-cmd --permanent --add-port=8083/tcp
sudo firewall-cmd --permanent --add-port=8084/tcp
sudo firewall-cmd --permanent --add-port=18083/tcp
sudo firewall-cmd --reload

# 验证规则已生效
sudo firewall-cmd --list-ports

6.2 SELinux 处理

CentOS / RHEL 系统默认启用 SELinux，可能会阻止 EMQX 绑定端口或读写文件。

bash

# 查看 SELinux 当前状态
getenforce

# 方案一（推荐）：安装 SELinux 管理工具并放行 EMQX 端口
sudo yum install policycoreutils-python-utils -y
sudo semanage port -a -t http_port_t -p tcp 18083
sudo semanage port -a -t http_port_t -p tcp 8083

# 方案二（不推荐）：临时关闭 SELinux（仅用于紧急排查）
# sudo setenforce 0

# 方案三：永久关闭 SELinux（不推荐，降低系统安全性）
# 编辑 /etc/selinux/config，设置 SELINUX=disabled，然后重启

如果 EMQX 启动后 Dashboard 无法访问，优先检查 sudo ausearch -m avc | grep emqx 查看 SELinux 审计日志。

7. 性能调优（低配服务器）

7.1 调整 EMQX 节点参数

编辑 /etc/emqx/emqx.conf：

bash

# 备份原配置
sudo cp /etc/emqx/emqx.conf /etc/emqx/emqx.conf.bak

# 编辑配置文件
sudo vi /etc/emqx/emqx.conf

重点调整以下参数：

ini

## 节点连接数限制（按需设置，默认无限制）
## listener.tcp.default.max_connections = 1000

## MQTT 会话最大缓存消息数（降低以节省内存）
## 默认 1000，低配服务器可设为 100 ~ 500
mqtt.max_mqueue_len = 200

## 关闭不必要的监听器
## 如果不需要 TLS，可关闭 8883 端口
## listener.ssl.default.bind = 0.0.0.0:8883
## 改为注释掉或删除

## 如果不需要 WebSocket，可关闭 8083 端口
## listener.ws.default.bind = 0.0.0.0:8083

## 日志级别（生产环境建议设为 warning 或 error，减少磁盘 I/O）
log.default.level = warning

bash

# 修改后重启 EMQX
sudo systemctl restart emqx

7.2 系统级优化

bash

# 提高文件描述符限制（EMQX 每个连接消耗一个 fd）
echo "emqx soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "emqx hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# 优化内核 TCP 参数
cat << 'EOF' | sudo tee -a /etc/sysctl.conf
# EMQX 推荐参数
net.core.somaxconn = 4096
net.ipv4.tcp_max_syn_backlog = 4096
net.ipv4.ip_local_port_range = 1024 65535
net.ipv4.tcp_tw_reuse = 1
EOF

sudo sysctl -p

8. 客户端连接配置（以 EdgeLink 为例）

本节以 Advantech EdgeLink Studio 中的 ECU-1051 网关为例，展示客户端侧 MQTT 连接参数配置。

8.1 连接参数

在 EdgeLink Studio 中打开 SimpleMQTT 配置页面，填写以下信息：

参数	值	说明
启用此连接	✅ 勾选	确保连接处于激活状态
Host	`你的服务器公网IP`	阿里云 / 腾讯云 ECS 的公网地址
Port	`1883`	标准 MQTT 端口；如使用 TLS，填 `8883`
Client Identifier	`ECU1051_Gateway_001`	全局唯一的设备标识，建议有意义的命名
Username	EMQX 中创建的用户名	与 5.1 节中创建的一致
Password	EMQX 中创建的密码	同上
Keep Alive	`60`（秒）	心跳间隔，推荐 30~120 秒

8.2 主题规划建议

推荐使用层次化主题命名，便于管理和 ACL 控制：

# 数据上报主题（设备 → 云端）
data/{device_id}/{sensor_type}
# 示例：data/ECU1051_Gateway_001/temperature

# 命令下发主题（云端 → 设备）
cmd/{device_id}/{command_type}
# 示例：cmd/ECU1051_Gateway_001/reboot

# 设备状态主题
status/{device_id}
# 示例：status/ECU1051_Gateway_001

8.3 通配符说明

MQTT 主题支持两种通配符，方便订阅端灵活匹配：

通配符	含义	示例
`+`	匹配单层主题	`data/+/temperature` 匹配所有设备的温度数据
`#`	匹配多层主题（必须放在末尾）	`data/#` 匹配所有设备的所有传感器数据

9. 运维管理

9.1 常用运维命令

bash

# 查看所有连接的客户端
emqx ctl clients list

# 查看某个客户端的详细信息
emqx ctl clients show <ClientID>

# 强制踢出某个客户端
emqx ctl clients kick <ClientID>

# 查看订阅列表
emqx ctl subscriptions list

# 查看内置数据库中的所有认证用户
emqx ctl authentication list_users password-based:built_in_database

# 查看集群状态（集群部署时）
emqx ctl cluster status

9.2 数据备份

bash

# 备份配置文件
sudo cp -r /etc/emqx /backup/emqx_config_$(date +%Y%m%d)/

# 备份数据目录（含 Dashboard 用户、认证信息、规则等）
sudo cp -r /var/lib/emqx /backup/emqx_data_$(date +%Y%m%d)/

9.3 升级 EMQX

bash

# 1. 备份（参见上一节）
# 2. 下载新版本 RPM
wget https://www.emqx.com/zh/downloads/broker/5.8.x/emqx-5.8.x-el8-amd64.rpm

# 3. 停止旧版本
sudo systemctl stop emqx

# 4. 升级安装
sudo yum install ./emqx-5.8.x-el8-amd64.rpm -y

# 5. 启动新版本
sudo systemctl start emqx

# 6. 验证
emqx --version && emqx ping

9.4 卸载 EMQX

bash

# 停止服务
sudo systemctl stop emqx
sudo systemctl disable emqx

# 卸载软件包
sudo yum remove emqx -y

# (可选) 清理残留数据和配置
sudo rm -rf /var/lib/emqx /var/log/emqx /etc/emqx

10. 常见问题排查

10.1 EMQX 无法启动

bash

# 查看详细错误日志
sudo journalctl -u emqx -n 50 --no-pager

# 检查端口冲突
ss -tlnp | grep -E '1883|18083'
# 如果端口被占用，编辑 /etc/emqx/emqx.conf 更改端口后重启

# 检查 SELinux 拦截
sudo ausearch -m avc -ts recent | grep emqx

10.2 Dashboard 无法访问

云安全组：检查入方向是否放行了 18083 端口
本地防火墙：sudo firewall-cmd --list-ports 确认 18083 已添加
SELinux：sudo ausearch -m avc | grep 18083 检查是否被拦截
监听地址：确认 EMQX 是否监听在 0.0.0.0 而非 127.0.0.1：bashss -tlnp | grep 18083 # 应显示 0.0.0.0:18083 而非 127.0.0.1:18083

10.3 客户端连接被拒绝

确认用户名密码是否正确
检查认证器是否已正确创建（Dashboard → 访问控制 → 认证）
确认 没有启用 “匿名访问”（默认安装后匿名访问是开启的，创建认证器会自动关闭）
查看 EMQX 日志：bashgrep -i 'auth\|login\|denied' /var/log/emqx/emqx.log.* | tail -20

10.4 WebSocket 客户端连接失败

Dashboard 内置 WebSocket 客户端的连接路径为 /mqtt，完整地址：ws://服务器IP:8083/mqtt。

如果连接失败：

确认安全组已放行 8083 端口
确认 firewalld 已放行：sudo firewall-cmd --list-ports | grep 8083
Dashboard WebSocket 客户端默认连接 127.0.0.1:8083，仅适用于 EMQX 本机访问；远程访问需手动修改 Host 为服务器公网 IP

11. 轻量级替代方案

如果你的服务器资源配置较低（1 核 1 GB 或更低），或仅需连接少量设备，以下方案更节省资源：

11.1 Mosquitto

经典轻量 MQTT Broker，内存占用极低（通常 < 10 MB）。

bash

# CentOS / RHEL 安装
sudo yum install epel-release -y
sudo yum install mosquitto -y

# 启动并设置开机自启
sudo systemctl start mosquitto
sudo systemctl enable mosquitto

# 注意：Mosquitto 默认允许匿名连接，需手动配置密码文件
# 创建密码文件
sudo mosquitto_passwd -c /etc/mosquitto/passwd <用户名>
# 编辑 /etc/mosquitto/mosquitto.conf，添加：
#   password_file /etc/mosquitto/passwd
#   allow_anonymous false
sudo systemctl restart mosquitto

11.2 NanoMQ

EMQ 官方出品的超轻量 MQTT Broker，专为边缘计算和资源受限环境设计。

bash

# 下载并安装
wget https://github.com/nanomq/nanomq/releases/latest/download/nanomq-latest-linux-amd64.rpm
sudo rpm -ivh nanomq-latest-linux-amd64.rpm

# NanoMQ 默认无 Dashboard，通过配置文件管理：
# /etc/nanomq/nanomq.conf

11.3 选型对比

特性	EMQX	Mosquitto	NanoMQ
Dashboard	✅ 功能全面	❌ 无	❌ 无
规则引擎	✅ 内置	❌ 无	❌ 无
集群支持	✅ 支持	❌ 需插件	❌ 需 SDN
内存占用	~200 MB+	< 10 MB	< 30 MB
适用场景	中大规模生产环境	小规模 / 资源受限	边缘计算 / IoT
MQTT 5.0	✅ 完整支持	✅ 2.0+ 支持	✅ 部分支持

附录：端口速查表

端口	协议	说明
`1883`	TCP	MQTT 标准端口
`8883`	TCP	MQTT over TLS/SSL
`8083`	TCP	MQTT over WebSocket
`8084`	TCP	MQTT over WebSocket (TLS)
`18083`	HTTP	Dashboard 管理后台
`4370`	TCP	Erlang 分布式集群通信（集群部署时）
`5370`	TCP	Erlang 分布式集群发现（集群部署时）

总结：完成以上所有步骤后，你就拥有了一套功能完整、安全可靠的 MQTT 消息服务。从设备连接到数据流转，EMQX 提供了开箱即用的能力；而本章涵盖的防火墙、认证、ACL、TLS、备份与运维等内容，将帮助你从”能跑”提升到”生产可用”。

下一步建议阅读：MQTT 协议核心概念详解和 MQTT 数据获取与调试实战。

EMQX 详细安装指南：从零搭建 MQTT 消息服务器

目录

1. 环境准备

1.1 系统要求

1.2 检查系统版本

1.3 云服务器安全组配置（阿里云 / 腾讯云等）

2. 安装 EMQX

2.1 下载 RPM 安装包

2.2 执行安装

2.3 验证安装

3. 启动与健康检查

3.1 启动服务

3.2 健康检查

3.3 查看日志

4. Dashboard 管理后台

4.1 首次访问

4.2 首次登录后必做

5. 安全加固

5.1 关闭匿名访问 + 配置客户端认证

5.2 启用 TLS/SSL 加密（强烈推荐）

5.3 配置访问控制（ACL）

6. 防火墙与 SELinux 配置

6.1 服务器本地防火墙

6.2 SELinux 处理

7. 性能调优（低配服务器）

7.1 调整 EMQX 节点参数

7.2 系统级优化

8. 客户端连接配置（以 EdgeLink 为例）

8.1 连接参数

8.2 主题规划建议

8.3 通配符说明

9. 运维管理

9.1 常用运维命令

9.2 数据备份

9.3 升级 EMQX

9.4 卸载 EMQX

10. 常见问题排查

10.1 EMQX 无法启动

10.2 Dashboard 无法访问

10.3 客户端连接被拒绝

10.4 WebSocket 客户端连接失败

11. 轻量级替代方案

11.1 Mosquitto

11.2 NanoMQ

11.3 选型对比

附录：端口速查表

散 客

散客