一、安装预置条件

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...emqx hook is starting...emqx router is starting...emqx pubsub is starting...emqx stats is starting...emqx metrics is starting...emqx pooler is starting...emqx trace is starting...emqx client manager is starting...emqx session manager is starting...emqx session supervisor is starting...emqx wsclient supervisor is starting...emqx broker is starting...emqx alarm is starting...emqx mod supervisor is starting...emqx bridge supervisor is starting...emqx access control is starting...emqx system monitor is starting...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...emqx hook is starting...emqx router is starting...emqx pubsub is starting...emqx stats is starting...emqx metrics is starting...emqx pooler is starting...emqx trace is starting...emqx client manager is starting...emqx session manager is starting...emqx session supervisor is starting...emqx wsclient supervisor is starting...emqx broker is starting...emqx alarm is starting...emqx mod supervisor is starting...emqx bridge supervisor is starting...emqx access control is starting...emqx system monitor is starting...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...emqx hook is starting...emqx router is starting...emqx pubsub is starting...emqx stats is starting...emqx metrics is starting...emqx pooler is starting...emqx trace is starting...emqx client manager is starting...emqx session manager is starting...emqx session supervisor is starting...emqx wsclient supervisor is starting...emqx broker is starting...emqx alarm is starting...emqx mod supervisor is starting...emqx bridge supervisor is starting...emqx access control is starting...emqx system monitor is starting...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...emqx hook is starting...emqx router is starting...emqx pubsub is starting...emqx stats is starting...emqx metrics is starting...emqx pooler is starting...emqx trace is starting...emqx client manager is starting...emqx session manager is starting...emqx session supervisor is starting...emqx wsclient supervisor is starting...emqx broker is starting...emqx alarm is starting...emqx mod supervisor is starting...emqx bridge supervisor is starting...emqx access control is starting...emqx system monitor is starting...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 到程序目录。

控制台模式启动:

binemqx 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： 大于最大允许连接数