安装部署和迁移
本章将向您介绍如何下载和安装 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/amd64 | arm64 |
|---|---|---|---|
| Ubuntu | Ubuntu 18.04 Ubuntu 20.04 Ubuntu 22.04 Ubuntu 24.04 | 是 | 是 |
| Debian | Debian 10 Debian 11 Debian 12 | 是 | 是 |
| CentOS/RHEL | CentOS 7 Rocky Linux 8 Rocky Linux 9 | 是 | 是 |
| Amazon Linux | Amazon Linux 2 Amazon Linux 2023 | 是 | 是 |
| macOS | macOS 13 macOS 14 | 是 | 是 |
安装环境
EMQX 所使用的 Erlang 虚拟机依赖于系统区域设置来启用各种功能的 Unicode 支持，包括交互式 Erlang Shell 中的文件名和终端 IO。
如果您使用的是 Linux 操作系统，在启动 EMQX 前建议确认系统环境中已启用了 UTF-8 区域设置。关于如何在不同平台上启用 UTF-8 区域设置，点击下列标签：
端口占用
EMQX 默认使用以下端口，请确保这些端口未被其他应用程序占用，并按照需求开放防火墙以保证 EMQX 正常运行。
| 端口 | 协议 | 描述 |
|---|---|---|
| 1883 | TCP | MQTT over TCP 监听器端口，主要用于未加密的 MQTT 连接。 |
| 8883 | TCP | MQTT over SSL/TLS 监听器端口，用于加密的 MQTT 连接。 |
| 8083 | TCP | MQTT over WebSocket 监听器端口，使 MQTT 能通过 WebSocket 进行通信。 |
| 8084 | TCP | MQTT over WSS (WebSocket over SSL) 监听器端口，提供加密的 WebSocket 连接。 |
| 18083 | HTTP | EMQX Dashboard 和 REST API 端口，用于管理控制台和 API 接口。 |
| 4370 | TCP | Erlang 分布式传输端口，根据节点名称不同实际端口可能是 BasePort (4370) + Offset。 |
| 5370 | TCP | 集群 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 |
lib | Erlang 代码 | ./lib | /usr/lib/emqx/lib |
erts-* | Erlang 虚拟机文件 | ./erts-* | /usr/lib/emqx/erts-* |
plugins | 插件 | ./plugins | /usr/lib/emqx/plugins |
TIP
- 压缩包解压安装时，目录相对于软件所在目录；
- Docker 容器使用压缩包解压安装的方式，软件安装于
/opt/emqx目录中； data、log、plugins目录可以通过配置文件设置，建议将data目录挂载至高性能磁盘以获得更好的性能。但对于属于同一集群的节点，data目录的配置应该相同。更多关于集群的介绍，见集群章节。
接下来我们将详细介绍下其中的部分目录，其中包含的文件和子文件夹。
| 目录 | 描述 | 权限 | 目录文件 |
|---|---|---|---|
| bin | 存放可执行文件 | 读 | emqx 和emqx.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 的配置项存储在 etc 和 data/configs 目录下，二者的主要区别是 etc 目录存储只读的配置文件，用户通过 Dashboard 和 REST API 提交的配置将被保存到 data/configs 目录下，并支持在运行时进行热更新。
etc/emqx.confdata/configs/cluster.hocon
EMQX 读取这些配置并将其合并转化为 Erlang 原生配置文件格式，以便在运行时应用这些配置。