EMQX消息服务器开源项目教程

一、系统简介

EMQX 是高性能、分布式 MQTT 消息中间件，支持 MQTT 3.1/3.1.1/5.0，同时兼容 MQTT-SN、CoAP、LwM2M、WebSocket 等物联网协议。 EMQX 管理系统（Dashboard）是 EMQX 内置 Web 可视化后台，不需要额外单独安装，部署 EMQX 之后直接开启即可访问。作用：可视化查看连接设备、消息流量、主题订阅、客户端管理、规则引擎、权限配置、集群管理、监控告警，替代命令行操作。

默认地址：http://IP:18083 默认账号密码：admin / public（生产环境必须立刻修改密码）

端口说明：

· 18083：Dashboard Web 管理端口

· 1883：MQTT TCP 端口

· 8083：MQTT over WebSocket

· 8883：MQTT TLS 加密端口

二、EMQX 管理系统核心功能

1. 概览（Dashboard 首页）

· 实时指标：在线连接数、消息收发速率、消息总数、订阅数量、节点状态

· 监控图表：消息吞吐量、连接数变化、内存 / CPU 占用

· 告警面板：异常连接、消息堆积、节点离线提示

2. 客户端管理（Clients）

查看所有接入设备：客户端 ID、IP、连接时间、协议版本、是否在线、清理会话标记、心跳时间。支持操作：踢下线指定设备、查询该客户端订阅的所有主题。

3. 订阅管理（Subscriptions）

查看全量设备主题订阅关系，可以按主题、客户端筛选，查看哪些设备订阅了哪个 topic。

4. 主题路由（Topics）

查看系统中存在的 MQTT 主题，统计每个主题消息流量。

5. 规则引擎（Rules）⭐最核心功能

消息流转处理，MQTT 消息到达后，触发自定义规则：

· 消息转发：写入 MySQL/PostgreSQL/Redis/InfluxDB/Kafka

· Webhook：把设备消息推送到后端 HTTP 接口

· 消息过滤：按主题、payload 条件筛选消息

· 消息转换：修改 payload 字段、新增字段

· 桥接：转发消息到另一个 MQTT 服务器（EMQX 桥接）

常用场景：设备上报传感器数据 → EMQX 规则引擎 → 存入数据库。

6. 认证与授权（Access Control）

控制设备能不能连接、能不能发布 / 订阅主题：

1. 认证（Authentication）：设备登录校验，支持密码、数据库、JWT、HTTP 接口认证

2. 授权（Authorization）：连接成功后，限制设备只能发布 / 订阅哪些主题

默认是public匿名访问，生产务必关闭匿名，否则任何人都可以连上来收发消息！

7. 集群管理

多节点 EMQX 集群可视化：查看集群所有节点状态、节点负载，增加 / 移除节点。

8. 消息测试工具（Web 客户端）

Dashboard 内置 MQTT 测试客户端，可以直接在网页上：

· 创建测试客户端

· 订阅主题、发布消息

· 调试设备通信，不用额外装 MQTTX

9. 告警 & 监控

支持配置告警：连接突降、消息堆积、节点 CPU 过高，支持邮件 / Webhook 推送告警。

10. 插件管理

启用 / 禁用 EMQX 插件：比如 prometheus 监控、日志插件、桥接插件等。

11. 日志

查看系统日志、客户端连接日志、规则引擎执行日志，排查设备连不上、消息丢包问题。

三、EMQX 优缺点

✅ 优点

1. 性能极强：单节点可承载百万级 MQTT 长连接，分布式横向扩展，适合海量物联网设备。

2. 协议丰富：原生支持 MQTT5，websocket MQTT，方便前端网页直接连接设备消息。

3. 内置 Dashboard 可视化管理，开箱即用，不用自己开发运维后台。

4. 强大规则引擎：消息落地数据库、转发第三方服务非常方便。

5. 开源免费：社区版开源，商用也免费（社区版协议 Apache2.0）。

6. 跨平台：支持 Linux、Windows、Docker、K8s 部署。

7. 丰富的认证授权方案，支持 TLS 加密连接，保障物联网通信安全。

❌ 缺点

1. 资源占用：百万长连接场景，内存消耗较高；大量消息吞吐对服务器 CPU 要求高。

2. 学习成本：MQTT 协议本身有 QoS、保留消息、遗嘱消息等概念，新手容易踩坑。

3. 持久化限制：社区版消息持久化能力有限，不适合当作数据库，只做消息转发。消息堆积过多会导致性能暴跌。

4. Windows 生产稳定性一般，官方推荐 Linux 作为生产环境。

5. 高级企业功能（审计、高级集群、技术支持）需要购买企业版。

6. 规则引擎语法为 HCL，上手需要学习。

四、保姆级部署教程（3 种方式，推荐 Docker 最简部署）

环境建议：生产使用 Ubuntu / CentOS Linux；测试可用 Windows。防火墙放行端口：18083,1883,8083

方式一：Docker 部署（推荐，最简单，快速体验）

前提：服务器已经装好 docker、docker-compose

1. 创建文件夹，新建docker-compose.yml

version: '3'

services:

emqx:

image: emqx/emqx:5.8.0

container_name: emqx

restart: always

ports:

- "1883:1883" # MQTT TCP

- "8083:8083" # MQTT over websocket

- "18083:18083" # Dashboard管理后台

environment:

EMQX_DASHBOARD__DEFAULT_USER__PASSWORD: "Admin@123456" #自定义初始密码，不要用默认public

volumes:

- ./emqx_data:/opt/emqx/data

- ./emqx_log:/opt/emqx/log

1. 启动 EMQX

docker-compose up -d

1. 访问管理后台浏览器打开 http://服务器IP:18083 账号：admin，密码：Admin@123456

停止命令：docker-compose down

方式二：Linux 二进制包部署（生产裸机部署，Ubuntu 示例）

1. 下载 EMQX 5.x 安装包

# 导入EMQX GPG密钥

curl -fsSL https://www.emqx.com/en/downloads/broker/v5.8.0/emqx-5.8.0-ubuntu22.04-amd64.deb -o emqx.deb

1. 安装

sudo apt install ./emqx.deb

1. 启动服务，设置开机自启

sudo systemctl start emqx

sudo systemctl enable emqx

1. 修改默认管理员密码

emqx ctl admins update admin Admin@123456

1. 访问：http://服务器IP:18083

常用命令：

emqx ctl status #查看状态

sudo systemctl stop emqx #停止服务

sudo systemctl restart emqx #重启

方式三：Windows 部署（仅本地测试，不建议生产）

1. 官网下载 EMQX windows zip 包

2. 解压，打开 cmd 进入 bin 目录

3. 启动：emqx start

4. 浏览器访问

五、EMQX 管理系统保姆级使用流程（部署后必做步骤）

第一次登录系统，按顺序操作：

步骤 1：修改管理员密码（必做！）

步骤 2：关闭匿名访问（生产必做）

左侧菜单【访问控制】→【认证】

· 找到password_based:built_in_database内置数据库认证，启用

· 关闭【匿名认证】，否则设备不需要账号密码就能接入。

步骤 3：创建设备账号

访问控制 → 认证 → 用户点击创建用户：填写客户端用户名、密码，设备连接时需要填写这个账号密码。

区分：管理员账号是登录 Dashboard 后台；设备账号是 MQTT 客户端连接使用。

步骤 4：测试收发消息（内置 Web 客户端调试）

左侧【工具】→【MQTT 客户端】

1. 新建连接：填入 MQTT 连接信息，使用刚才创建的设备账号密码连接

2. 订阅主题：例如 device/+/data

3. 发布消息：向主题发消息，观察接收，验证通信是否正常

步骤 5：配置规则引擎（消息入库示例）

左侧【规则引擎】→【规则】新建规则，编写 SQL，示例：

SELECT

payload,

clientid,

topic,

timestamp

FROM

"t/#"

然后添加动作，比如发送到 HTTP Webhook 或者写入 MySQL 数据库。

步骤 6：查看监控

首页看连接数，【监控】面板查看消息吞吐，排查设备断线、消息丢失。

六、常见坑 & 排错指南

1. 无法访问 18083 页面

· 服务器防火墙没有放行 18083 端口

· 云服务器安全组（阿里云 / 腾讯云）没开放端口

· EMQX 没有正常启动，emqx ctl status查看状态

2. MQTT 客户端连不上 1883

· 检查安全组 / 防火墙放行 1883

· 匿名关闭后，客户端必须填写正确用户名密码

· MQTT 版本不匹配（老设备 MQTT3.1）

3. 消息发出去收不到

· 检查主题大小写！MQTT 主题区分大小写

· QoS 0 消息不保证送达，网络波动会丢消息

· 客户端订阅主题写错

4. 大量设备频繁断线

· 心跳时间设置不合理

· 服务器带宽不足

· 服务器内存打满

七、安全最佳实践（生产环境）

1. 修改 Dashboard 管理员密码，不要弱密码

2. 关闭匿名访问，所有设备必须账号认证

3. 使用 TLS 加密（8883 端口），避免明文传输

4. 使用授权策略，限制设备只能发布自己的主题，防止越权订阅

5. Dashboard 后台端口 18083 不要对公网直接开放，建议内网访问 + VPN

6. 定期备份 emqx 内置数据库

八、附录：术语简释

· ClientID：设备唯一 ID，MQTT 客户端标识

· Topic：消息主题，类似消息路由地址

· QoS：消息服务质量（0 最多一次 /1 至少一次 /2 仅一次）