开源版 EMQX（单机版）搭建和客户端认证配置

MQTT 是机器对机器的连接协议，它被设计为一个极其轻量级的发布订阅模式的消息传输协议，广泛应用于物联网、移动互联网、智能硬件、车联网等领域。对于需要较小代码占用空间以及网络带宽非常宝贵的远程连接非常有用，是专为受限设备和低带宽、高延迟或不可靠的网络而设计。

目前市场上基于 MQTT 设计的消息队列软件有很多，使用较多且比较流行的主要是 EMQX 软件，分为开源版和企业版。从 5.9.0 版本开始 EMQX 将开源版融入到了企业版中，只提供企业版下载。企业版虽然可以免费使用，但是有一些限制，建议认真仔细查看 EMQX 企业版未付费使用限制

本篇博客基于最新的开源版（EMQX 5.8.9 版本）介绍单机部署搭建和客户端认证配置，开源版已经能够满足绝大多数场景和需求。

有关开源版和企业版之间的功能对比，可以参考：https://docs.emqx.com/zh/emqx/v5.8/getting-started/feature-comparison.html

下面提供一些 EXMQ 官网的一些相关资料，方便在使用时快速查阅：

EMQX 官网：https://www.emqx.com/zh

github：https://github.com/emqx/emqx

开源版EMQX下载：https://www.emqx.com/zh/downloads-and-install/broker

开源版EMQX文档：https://docs.emqx.com/zh/emqx/v5.8/deploy/install-open-source.html

MQTT客户端下载：https://mqttx.app/zh/downloads

一、开源版单机部署

本篇博客采用 docker-compose 在虚拟机中部署，虚拟机 ip 地址是 192.168.136.128，具体文件和目录如下：

为了避免写入权限问题，所以将 3 个文件夹（data、log、plugins）都赋予了 777 的权限，编写 docker-compose.yml 文件内容如下：

services:emqx:# 使用开源版镜像的最新版本image: emqx/emqx:5.8.9# 容器服务名称container_name: emqx# 这个很重要，数据存储目录需要使用主机名# 如果主机名发生变化，数据目录下会创建一个新的目录存放数据hostname: docker.jobs.comprivileged: truerestart: always#使用宿主机的ip和端口#network_mode: "host"#将docker中的端口映射出来ports:# web管理界面访问- "18083:18083"# 程序访问端口- "1883:1883"# WebSocket访问端口- "8083:8083"volumes:# 插件目录- ./plugins:/opt/emqx/plugins:rw# 数据目录- ./data:/opt/emqx/data:rw# 日志目录- ./log:/opt/emqx/log:rw# 使容器内的时间相关设置与宿主机保持一致- /etc/localtime:/etc/localtimeenvironment:# 跟上面 hostname 配置保持一致- EMQX_HOST=docker.jobs.com# 启用文件日志- EMQX_LOG__FILE__DEFAULT__ENABLE=true# 关闭控制台日志- EMQX_LOG__CONSOLE__ENABLE=false# 禁用遥测（遥测是官方对用户收集系统使用相关信息，开源版特有的功能，建议禁用）- EMQX_TELEMETRY__ENABLE=false# 设置中国时区- TZ=Asia/Shanghai# 自定义配置 tcp 端口#- EMQX_LISTENERS__TCP__DEFAULT__BIND=1883# 自定义配置加密安全的 tcp 端口#- EMQX_LISTENERS__SSL__DEFAULT__BIND=8883# 自定义配置 WebSocket 的端口#- EMQX_LISTENERS__WS__DEFAULT__BIND=8083# 自定义配置加密安全的 WebSocket 的端口#- EMQX_LISTENERS__WSS__DEFAULT__BIND=8084# 自定义配置Web后台工具的访问端口#- EMQX_DASHBOARD__LISTENERS__HTTP__BIND=18083

为了提升性能，在实际应用中，很少使用加密的 TLS 和 加密的 SSL 协议，所以就只映射出了普通的 TCP 和 WebSocket 端口。

需要注意的是：开源版默认情况下是启用遥测功能的，官方会通过网络收集你部署的 EMQX 服务使用情况相关信息。我这里也禁用了遥测。

有关遥测的相关介绍可以参考官网：https://docs.emqx.com/zh/emqx/v5.8/telemetry/telemetry.html

最后在 docker-compose.yml 文件所在目录运行 docker-compose up -d 启动服务即可，我的虚拟机 ip 地址是 192.168.136.128，映射出来的 web 后台工具的访问端口是 18083，因此访问 http://192.168.136.128:18083 验证部署是否成功。

用户名是 admin 密码是 public ，登录成功后需要修改 admin 用户的密码，至少 8 个字符。登录成功后访问的首页如下所示：

如果你不小心忘记了自己设置的登录密码，没关系，可以进入 docker 容器内，运行命令重新设置密码即可。

# 进入容器中
docker exec -it emqx /bin/bash
# 默认进入的是 /opt/emqx 目录，命令行工具都在 /opt/emqx/bin 目录中
# 修改密码的命令行格式为：/opt/emqx/bin/emqx_ctl admins passwd 用户名 密码
# 比如将 admin 账号的密码修改为 Jobs9527
/opt/emqx/bin/emqx_ctl admins passwd admin Jobs9527

在 Web 后台工具中有收发消息的测试诊断工具，在左侧菜单点击【诊断工具】，点击【WebSocket 客户端】如下图：

输入正确的参数（目前不需要输入用户名和密码就能连接，在本篇博客的下面会介绍使用账户和密码认证后才能连接的安全方案）连接成功后，就可以收发消息。由于是网页版后台工具，因此只能使用 WebSocket 协议收发消息。

二、客户端工具下载和部署

访问 https://mqttx.app/zh/downloads 页面，下载自己需要的客户端工具，一般下载 Windows 桌面版 x86-64 的安装文件。

安装完成后界面如下所示，使用起来很简单，这里就不介绍了。

我们也可以使用 docker 容器单独部署 web 版的客户端工具：https://mqttx.app/zh/downloads

我这里使用 docker-compose 部署 web 版客户端工具（只支持 WebSocket 连接服务器），docker-compose.yml 文件编写如下：

services:mqttweb:image: emqx/mqttx-web:latestcontainer_name: mqtt-webrestart: alwaysports:- "18082:80"

容器里面使用的是 80 端口，我这里使用 18082 映射到宿主机上，因此访问 http://192.168.136.128:18082 即可

三、设置必须使用账号连接服务器

访问 http://192.168.136.128:18083 进入 Web 后台管理工具中，左侧菜单选择【访问控制】下的【客户端认证】菜单，进入客户端认证页面。在页面右上角点击【创建】按钮，选择【Password-Based】后点击【下一步】

在用户认证数据存储方面，可以先选择【内置数据库】，然后点击【下一步】

采用默认的参数设置，使用用户名和密码进行认证连接即可，直接点击【创建】即可

然后就可以点击【内置数据库】记录后面的【用户管理】按钮，在用户管理页面中添加一个或多个账号。后续任何【客户端】就必须使用你添加的账号经过密码验证无误后才能连接到 EMQX 服务，增强了系统的安全性。

四、使用 Mysql 存储账号数据

由于【内置数据库】这种方式只适用于单机版，后续我们还得使用 EMQX 开源版部署集群，因此我们可以使用 Mysql 数据库存储用户账号密码数据。

官网提供了使用 Mysql 进行密码认证的文档：https://docs.emqx.com/zh/emqx/v5.8/access-control/authn/mysql.html

有关 mysql 数据库的部署，这里就不赘述了。我们需要创建一个名称为 mqtt_user 的数据库，然后运行以下 SQL 脚本创建一张表即可：

CREATE TABLE `mqtt_user` (`id` int(11) unsigned NOT NULL AUTO_INCREMENT,`username` varchar(100) DEFAULT NULL,`password_hash` varchar(100) DEFAULT NULL,`salt` varchar(35) DEFAULT NULL,`is_superuser` tinyint(1) DEFAULT 0,`created` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,PRIMARY KEY (`id`),UNIQUE KEY `mqtt_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

各字段解释如下：

• id 自增长的主键
• username 用户名
• password_hash 加密后的密码
• salt 加密算法使用的盐值，如果该字段是 null 或空字符串，表示加密算法中不加盐
• is_superuser 标记当前账号是否是超级用户，1 表示是，0 表示否。如果是超级用户，则忽略任何授权限制，可以发布和订阅任意 topic
• created 用户账号创建时间

可以使用以下 sql 语句，创建一个示例的账号：

# 创建 jobs 账号，采用 SHA256 加密算法，对密码字符串 jobsloveyou 加盐 slat_foo123 进行加密，生成账号密码
INSERT INTO mqtt_user(username, password_hash, salt, is_superuser) 
VALUES ('jobs', SHA2(concat('jobsloveyou', 'slat_foo123'), 256), 'slat_foo123', 1);

然后在 Web 后台工具中，左侧菜单选择【访问控制】下的【客户端认证】菜单，进入客户端认证页面。在页面右上角点击【创建】按钮，选择【Password-Based】后点击【下一步】，然后选择【Mysql】继续点击【下一步】。

输入 mysql 服务器连接信息，账号密码采用 sha256 ，加盐方式为在密码后面加盐，因此选择 suffix ，页面底部的高级设置中还可以设置连接池大小，最后在页面底部点击【创建】即可。我们需要通过 sql 语句或者程序编码方式，向数据库中添加账号，界面中没有提供添加用户的可视化操作。

上面我们已经通过示例 sql 语句，添加了一个 jobs 账号，客户端工具目前可以通过 jobs 账号（密码是 jobsloveyou）连接 EMQX 服务，已经不支持匿名连接了。


OK，有关 EMQX 开源版的单机部署和客户端认证配置已经介绍完毕，EMQX 使用起来很简单方便，有关更多的帮助内容请参考官网。