
一、安裝預置條件
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 暫未提供源碼編譯安裝,如有特殊運行環境需求請聯系 [email protected]
四、首次安裝 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 '[email protected]'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 '[email protected]'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 '[email protected]'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 '[email protected]'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: 大于最大允許連接數
