开源物联网MQTT 5.0服务器——EMQ安装及运行教程

一、安装预置条件

EMQ X 可以跨平台运行在 Linux、FreeBSD、MacOS 或 Windows 服务器甚至是树莓派上。

服务器最低配置为 512MB 内存且至少保留 1 GB 以上硬盘空间。

二、二进制包安装

EMQ 官网 提供热门 Linux 发行版、MacOS、Windows 操作系统以及 Docker 镜像的二进制包下载，当前支持的操作系统及平台请到官网下载页查阅。

三、源码编译安装

部分官网未提供二进制包的操作系统与平台如 Linux ARM、FreeBSB，可使用源码编译安装。

EMQ X 基于 Erlang/OTP 平台开发，项目托管的 GitHub 管理维护，源码编译依赖 Erlang 环境和 git 客户端。

EMQ X 3.0+ 依赖 Erlang R21+ 版本。

EMQ X Enterprise 暂未提供源码编译安装，如有特殊运行环境需求请联系 contact@emqx.io

四、首次安装 EMQ X

在安装 EMQ X 前，请确认安装的 前置条件 都已经满足。

版本选择

EMQ X 支持多种操作系统，请选择合适您的版本下载。

1、在 Linux 下安装

对于 Linux 发布，EMQ X 提供两种方式的安装。一是基于各 linux 发布的安装包。用安装包安装 EMQ X 以后，可以方便的使用系统管理工具来启停 EMQ X 服务。二是使用 zip 压缩打包的通用包。安装 zip 包只需解压 zip 文件即可。使用 zip 包可以实现在同一个系统下安装多套 EMQ X。在开发 / 实验室环境下使用 zip 包安装 EMQ X 非常实用。

CentOS/RHEL

目前 EMQ X 支持 CentOS/RHEL 6 和 7，在这两个版本上的安装过程一致。以下安装过程以 CentOS 7 为例。

使用 zip 包安装

解压 zip 文件

unzip emqx-centos7-v3.0.zip

启动以控制台调试模式 emqx，检查 EMQ X 是否可以正常启动：

cd emqx && ./bin/emqx console

如果安装成功，可以在控制台看到以下输出：

starting emqx on node 'emqx@127.0.0.1'emqx ctl is starting...[ok]emqx hook is starting...[ok]emqx router is starting...[ok]emqx pubsub is starting...[ok]emqx stats is starting...[ok]emqx metrics is starting...[ok]emqx pooler is starting...[ok]emqx trace is starting...[ok]emqx client manager is starting...[ok]emqx session manager is starting...[ok]emqx session supervisor is starting...[ok]emqx wsclient supervisor is starting...[ok]emqx broker is starting...[ok]emqx alarm is starting...[ok]emqx mod supervisor is starting...[ok]emqx bridge supervisor is starting...[ok]emqx access control is starting...[ok]emqx system monitor is starting...[ok]dashboard:http listen on 0.0.0.0:18083 with 2 acceptors.mqtt:tcp listen on 0.0.0.0:1883 with 8 acceptors.mqtt:ssl listen on 0.0.0.0:8883 with 4 acceptors.mqtt:ws listen on 0.0.0.0:8083 with 4 acceptors.Erlang MQTT Broker 3.0 is running now

CTRL+C 关闭控制台。守护进程模式启动:

./bin/emqx start

使用 rpm 包安装

在 CentOS 下使用 rpm 工具安装 EMQ X：

rpm -ivh emqx-centos7-v3.0-beta.4.rpm

在安装完成之后，EMQ X 的配置文件、日志文件和数据文件分别在以下目录：系统配置文件：/etc/emqx/emqx.conf插件配置文件： /etc/emqx/plugins/*.conf日志文件： /var/log/emqx数据文件： /var/lib/emqx/

在命令行启停 EMQ X：

systemctl start|stop|restart emqx.service

Ubuntu

目前 EMQ X 支持 Ubuntu 12.04、14.04、16.04 和 18.04，在这些版本上的安装过程一致。以下安装过程以 Ubuntu 18.04 为例。

使用 zip 包安装

解压 zip 文件

unzip emqx-ubuntu18.04-v3.0.zip

启动以控制台调试模式 emqx，检查 EMQ X 是否可以正常启动：

cd emqx && ./bin/emqx console

如果安装成功，可以在控制台看到以下输出：

starting emqx on node 'emqx@127.0.0.1'emqx ctl is starting...[ok]emqx hook is starting...[ok]emqx router is starting...[ok]emqx pubsub is starting...[ok]emqx stats is starting...[ok]emqx metrics is starting...[ok]emqx pooler is starting...[ok]emqx trace is starting...[ok]emqx client manager is starting...[ok]emqx session manager is starting...[ok]emqx session supervisor is starting...[ok]emqx wsclient supervisor is starting...[ok]emqx broker is starting...[ok]emqx alarm is starting...[ok]emqx mod supervisor is starting...[ok]emqx bridge supervisor is starting...[ok]emqx access control is starting...[ok]emqx system monitor is starting...[ok]dashboard:http listen on 0.0.0.0:18083 with 2 acceptors.mqtt:tcp listen on 0.0.0.0:1883 with 8 acceptors.mqtt:ssl listen on 0.0.0.0:8883 with 4 acceptors.mqtt:ws listen on 0.0.0.0:8083 with 4 acceptors.Erlang MQTT Broker 3.0 is running now

CTRL+C 关闭控制台。守护进程模式启动:

./bin/emqx start

使用 deb 包安装

sudo dpkg -i emqx-ubuntu18.04-v3.0_amd64.deb

在安装完成之后，EMQ X 的配置文件、日志文件和数据文件分别在以下目录：系统配置文件：/etc/emqx/emqx.conf插件配置文件： /etc/emqx/plugins/*.conf日志文件： /var/log/emqx数据文件： /var/lib/emqx/

在命令行启停 EMQ X：

service emqx start|stop|restart

Debian

目前 EMQ X 支持 Debian 7、8 和 9，在这些版本上的安装过程一致。以下安装过程以 Debian 9 为例。

使用 zip 包安装

解压 zip 文件

unzip emqx-debian9-v3.0.zip

启动以控制台调试模式 emqx，检查 EMQ X 是否可以正常启动：

cd emqx && ./bin/emqx console

如果安装成功，可以在控制台看到以下输出：

starting emqx on node 'emqx@127.0.0.1'emqx ctl is starting...[ok]emqx hook is starting...[ok]emqx router is starting...[ok]emqx pubsub is starting...[ok]emqx stats is starting...[ok]emqx metrics is starting...[ok]emqx pooler is starting...[ok]emqx trace is starting...[ok]emqx client manager is starting...[ok]emqx session manager is starting...[ok]emqx session supervisor is starting...[ok]emqx wsclient supervisor is starting...[ok]emqx broker is starting...[ok]emqx alarm is starting...[ok]emqx mod supervisor is starting...[ok]emqx bridge supervisor is starting...[ok]emqx access control is starting...[ok]emqx system monitor is starting...[ok]dashboard:http listen on 0.0.0.0:18083 with 2 acceptors.mqtt:tcp listen on 0.0.0.0:1883 with 8 acceptors.mqtt:ssl listen on 0.0.0.0:8883 with 4 acceptors.mqtt:ws listen on 0.0.0.0:8083 with 4 acceptors.Erlang MQTT Broker 3.0 is running now

CTRL+C 关闭控制台。守护进程模式启动:

./bin/emqx start

使用 deb 包安装

sudo dpkg -i emqx-debian9-v3.0_amd64.deb

在安装完成之后，EMQ X 的配置文件、日志文件和数据文件分别在以下目录：系统配置文件：/etc/emqx/emqx.conf插件配置文件： /etc/emqx/plugins/*.conf日志文件： /var/log/emqx数据文件： /var/lib/emqx/

在命令行启停 EMQ X：

service emqx start|stop|restart

2、在 MacOS 下安装

目前 EMQ X 在 MacOS 下提供 zip 包安装：解压 zip 文件

unzip emqx-macos-v3.0.zip

启动以控制台调试模式 emqx，检查 EMQ X 是否可以正常启动：

cd emqx && ./bin/emqx console

如果安装成功，可以在控制台看到以下输出：

starting emqx on node 'emqx@127.0.0.1'emqx ctl is starting...[ok]emqx hook is starting...[ok]emqx router is starting...[ok]emqx pubsub is starting...[ok]emqx stats is starting...[ok]emqx metrics is starting...[ok]emqx pooler is starting...[ok]emqx trace is starting...[ok]emqx client manager is starting...[ok]emqx session manager is starting...[ok]emqx session supervisor is starting...[ok]emqx wsclient supervisor is starting...[ok]emqx broker is starting...[ok]emqx alarm is starting...[ok]emqx mod supervisor is starting...[ok]emqx bridge supervisor is starting...[ok]emqx access control is starting...[ok]emqx system monitor is starting...[ok]dashboard:http listen on 0.0.0.0:18083 with 2 acceptors.mqtt:tcp listen on 0.0.0.0:1883 with 8 acceptors.mqtt:ssl listen on 0.0.0.0:8883 with 4 acceptors.mqtt:ws listen on 0.0.0.0:8083 with 4 acceptors.Erlang MQTT Broker 3.0 is running now

CTRL+C 关闭控制台。守护进程模式启动:

./bin/emqx start

3、在 Microsoft Windows 下安装

目前 EMQ X 在 Windows 下提供 zip 包安装。程序包下载解压后，打开 Windows 命令行窗口，cd 到程序目录。

控制台模式启动:

bin\emqx console

4、在 Docker 中安装

解压 emqx docker 镜像包：

unzip emqx-docker-v3.0.zip

加载镜像：

docker load < emqx-docker-v3.0

启动容器：

docker run -tid --name emq30 -p 1883:1883 -p 8083:8083 -p 8883:8883 -p 8084:8084 -p 18083:18083 emqx-docker-v3.0

停止容器：

docker stop emq30

开启容器：

docker start emq30

进入 Docker 控制台：

docker exec -it emq30 /bin/sh

5、使用源代码安装

EMQ X 消息服务器基于 Erlang/OTP 平台开发，项目托管的 GitHub 管理维护，源码编译依赖 Erlang 环境和 git 客户端。

本文以下说明适合 Linux 环境。

• 注意：EMQ X 3.0 依赖 Erlang R21 + 版本 *
• 如何安装 Erlang 请参考Erlang 官方网站*
• 如何安装和使用 git 客户端请参考git-scm*在准备好编译环境之后，clone 代码边并使编译：

git clone -b win30 https://github.com/emqx/emqx-rel.gitcd emqx-relx && makecd _rel/emqx && ./bin/emqx console

在编译成功后，程序包发布目录：

_rel/emqx

从控制台启动程序：

 复制代码cd _rel/emqx && ./bin/emqx console

五、首次运行 EMQ X

在安装以后您可以直接运行 EMQ X 来获得最初步的经验。除了在控制台，您也可以通过浏览器访问 http://127.0.0.1:18083 来使用 EMQ X 的 Web 管理控制界面。默认的登录名是 admin 和密码是 public。

通过浏览器访问 http://127.0.0.1:18083，您将看到一个 EMQ X 登录界面：

在输入用户名和密码后，您就可以使用 EMQ X Dashboard 的各项功能。在首次登录后，您看到的将是 EMQ X 控制台的信息汇总。这个页面显示了系统信息，节点信息，运行统计和一些统计指标。

您也可以对 EMQ X 做些简单的配置，让它适配您的运行环境和需求。

对 EMQ X 进行简单的配置

所有对 EMQ X 的配置都可以通过修改配置文件完成。配置文件的位置：

• etc/emqx.conf : EMQ X 服务器的参数设置
• etc/plugins/*.conf : EMQ X 插件配置文件，每个插件都有单独的配置文件。一些常用功能的配置也在 Web Dashboard 上进行修改。

更改 Dashboard 界面语言

在 Web 界面上选择 ADMIN -> Settings 菜单，您可以改变 Dashboard 使用的语言，点击 Apply 后生效。目前 EMQ X 支持中文和英文。

修改 Dashboard 默认登录名和密码

Dashboard 插件以 Web 界面的方式提供对 EMQ X 的管理和控制功能，是 EMQ X 的默认随系统启动的插件之一。在安装以后，您可以通过编辑配置文件的方式来改变 Dashboard 默认的用户名和密码。配置文件：

etc/plugins/emqx_dashboard.conf

修改以下两行内容，将等号右侧值改为需要的值：

dashboard.default_user.login = admindashboard.default_user.password = public

或者以 Web 方式管理 Dashboard 用户。在 ADMIN -> Users 菜单下，您可以修改用户密码和增加 / 删除用户。admin 用户只能修改密码，不能被删除。

配置端口

在安装以后，EMQ X 默认会使用以下端口：

• 1883: MQTT 协议端口
• 8883: MQTT/SSL 端口
• 8083: MQTT/WebSocket 端口
• 8080: HTTP API 端口
• 18083: Dashboard 管理控制台端口按照安装环境需要，可以修改以上端口。

修改协议端口请编辑 EMQ X 系统配置文件'etc/emqx.conf'，找到以下各行，并按需要修改端口号：

listener.tcp.external = 0.0.0.0:1883listener.ssl.external = 8883listener.ws.external = 8083

修改 HTTP API 端口请编辑 emqx_management 插件的配置文件'etc/plugins/emqx_management.conf'，找到下述行，并按需修改端口号：

management.listener.http = 8080

修改 Dashboard 管理控制台端口请编辑 emqx_dashboard 插件的配置文件'etc/plugins/emqx_dashboard.conf', 找到下述行，并按需修改端口号：

dashboard.listener.http = 18083

在 Web Dashboard 的 MANAGEMENT -> Listeners 菜单下，可以查看现在正在使用的监听器端口和属性。

启动 / 停止插件

插件是 EMQ X 的重要部分，EMQ X 的扩展功能基本都是通过插件实现的。包括 Dashbard 也是插件实现。您可以通过随软件附带的命令行工具 emqx_ctl 来启动和停止各个插件。

启动插件:

bin/emqx_ctl plugins load plugin_name

停止插件：

bin/emqx_ctl plugins unload plugin_name

您也可以在 Dashboard 的 MANAGEMENT -> plugins 菜单下启动和停止插件，或对插件进行简单的配置。

EMQ X 的 Dashboard 本身也是一个插件，如果您在 Web 界面下停止了 Dashboard 插件，您将无法再使用 dashboard，直至您使用命令行工具再次启动 Dashboard。

修改 Erlang 虚拟机启动参数

EMQ X 运行在 Erlang 虚拟机上，在'etc/emqx.conf'中有两个限定了虚拟机允许的最大连接数。在运行 EMQ X 前可以修改这两个参数以适配连接需求：

• node.process_limit : Erlang 虚拟机允许的最大进程数，EMQ X 一个连接会消耗 2 个 Erlang 进程;
• node.max_ports : Erlang 虚拟机允许的最大 Port 数量，EMQ X 一个连接消耗 1 个 Port
• 在 Erlang 虚拟机中的 Port 概念并不是 TCP 端口，可以近似的理解为文件句柄。*

这两个参数可以设置为：

• node.process_limit： 大于最大允许连接数 * 2
• node.max_ports： 大于最大允许连接数