Skip to content

安装部署和迁移

本章将向您介绍如何下载和安装 EMQX,支持的操作系统和平台,以及安装完成后 EMQX 所在目录的文件夹结构,以便后续的配置和维护操作。本章还介绍了 EMQX 企业版 License 的配置,以及如何从 EMQX 4.4 迁移至 EMQX 5.1。

下载

EMQX 每个版本会发布各个操作系统与平台程序包以及 Docker 镜像,并在 EMQX 官网提供下载,您可以点击以下链接下载:

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

EMQX 企业版:https://www.emqx.com/zh/downloads-and-install/enterprise

此外,您还可在我们的 GitHub Release 页面 下载 alpha、beta、rc 等版本的安装包。

TIP

除了私有部署外,我们也提供了全托管的 EMQX Cloud 服务,您只需几步注册即可轻松体验 EMQX 提供的 MQTT 消息服务,欢迎前往 EMQX Cloud 门户页面免费试用。

支持的操作系统与平台

EMQX 可以跨平台的在多种操作系统和硬件平台上运行,以下是支持情况:

操作系统支持版本x86_64/amd64arm64
UbuntuUbuntu 18.04
Ubuntu 20.04
Ubuntu 22.04
Ubuntu 24.04
DebianDebian 10
Debian 11
Debian 12
CentOS/RHELCentOS 7
Rocky Linux 8
Rocky Linux 9
Amazon LinuxAmazon Linux 2
Amazon Linux 2023
macOSmacOS 13
macOS 14

安装环境

EMQX 所使用的 Erlang 虚拟机依赖于系统区域设置来启用各种功能的 Unicode 支持,包括交互式 Erlang Shell 中的文件名终端 IO

如果您使用的是 Linux 操作系统,在启动 EMQX 前建议确认系统环境中已启用了 UTF-8 区域设置。关于如何在不同平台上启用 UTF-8 区域设置,点击下列标签:

端口占用

EMQX 默认使用以下端口,请确保这些端口未被其他应用程序占用,并按照需求开放防火墙以保证 EMQX 正常运行。

端口协议描述
1883TCPMQTT over TCP 监听器端口,主要用于未加密的 MQTT 连接。
8883TCPMQTT over SSL/TLS 监听器端口,用于加密的 MQTT 连接。
8083TCPMQTT over WebSocket 监听器端口,使 MQTT 能通过 WebSocket 进行通信。
8084TCPMQTT over WSS (WebSocket over SSL) 监听器端口,提供加密的 WebSocket 连接。
18083HTTPEMQX Dashboard 和 REST API 端口,用于管理控制台和 API 接口。
4370TCPErlang 分布式传输端口,根据节点名称不同实际端口可能是 BasePort (4370) + Offset
5370TCP集群 RPC 端口(在 Docker 环境下为 5369),根据节点名称不同实际端口可能是 BasePort (5370) + Offset

提示

即使没有组建集群,EMQX 也会监听 4370 跟 5370 端口。这 2 个端口固定无法修改,且会根据节点名称(Name@Host)中 Name 部分的数字后缀决定 Offset,没有数字后缀则默认为 0。更多信息请参考集群内通信端口

文件和目录

EMQX 安装完成后会创建一些目录用来存放运行文件和配置文件,存储数据以及记录日志。

不同安装方式得到的文件和目录位置有所不同,具体如下:

目录描述压缩包解压安装二进制包安装
etc静态配置文件./etc/etc/emqx
data数据和配置文件./data/var/lib/emqx
log日志文件./log/var/log/emqx
releases启动相关的脚本./releases/usr/lib/emqx/releases
bin可执行文件./bin/usr/lib/emqx/bin
libErlang 代码./lib/usr/lib/emqx/lib
erts-*Erlang 虚拟机文件./erts-*/usr/lib/emqx/erts-*
plugins插件./plugins/usr/lib/emqx/plugins

TIP

  1. 压缩包解压安装时,目录相对于软件所在目录;
  2. Docker 容器使用压缩包解压安装的方式,软件安装于 /opt/emqx 目录中;
  3. datalogplugins 目录可以通过配置文件设置,建议将 data 目录挂载至高性能磁盘以获得更好的性能。但对于属于同一集群的节点, data 目录的配置应该相同。更多关于集群的介绍,见集群章节

接下来我们将详细介绍下其中的部分目录,其中包含的文件和子文件夹。

目录描述权限目录文件
bin存放可执行文件emqxemqx.cmd:EMQX 的可执行文件,具体使用可以查看命令行接口
etc存放配置文件emqx.conf:EMQX 的主配置文件,默认包含常用的配置项。

emqx-example-en.conf:EMQX 示例配置文件,包含所有可选的配置项。

acl.conf:默认 ACL 规则。

vm.args:Erlang 虚拟机的运行参数。

certs/:X.509 的密钥和证书文件。这些文件被用于 EMQX 的 SSL/TLS 监听器;当要与和外部系统集成时,也可用于建立 SSL/TLS 连接。
data存放 EMQX 的运行数据authz:Dashboard 或 REST API 上传的 基于文件进行授权 规则内容。

certs:Dashboard 或 REST API 上传的证书。

configs:启动时生成的配置文件,或者从 Dashboard/REST API/CLI 进行功能设置时覆盖的配置文件。

mnesia:内置数据库目录,用于存储自身运行数据,例如告警记录、客户端认证与权限数据、Dashboard 用户信息等数据,一旦删除该目录,所有业务数据将丢失。

— 可包含以节点命名的子目录,如 emqx@127.0.0.1;如节点被重新命名,应手动将旧的目录删除或移走。

— 可通过 emqx_ctl mnesia 命令查询 EMQX 中 Mnesia 数据库的系统信息,具体请查看 管理命令 CLI

patches:用于存储热补丁 .beam 文件,用于补丁修复。

trace: 在线日志追踪文件目录。


在生产环境中,建议定期备份该文件夹下除 trace 之外的所有目录。
log日志文件emqx.log.*:EMQX 运行时产生的日志文件,具体请查看日志

TIP

EMQX 的配置项存储在 etcdata/configs 目录下,二者的主要区别是 etc 目录存储只读的配置文件,用户通过 Dashboard 和 REST API 提交的配置将被保存到 data/configs 目录下,并支持在运行时进行热更新。

  • etc/emqx.conf
  • data/configs/cluster.hocon

EMQX 读取这些配置并将其合并转化为 Erlang 原生配置文件格式,以便在运行时应用这些配置。