安装部署和迁移

本章将向您介绍如何下载和安装 EMQX，支持的操作系统和平台，以及安装完成后 EMQX 所在目录的文件夹结构，以便后续的配置和维护操作。

本章还介绍了如何从 EMQX 4.4 迁移至 EMQX 5.1。

安装环境

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

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

使用 cloud-init 配置启用 UTF-8 locale 区域设置：

cat <<EOF | sudo tee /etc/cloud/cloud.cfg.d/99_locale.cfg
#cloud-config
locale: C.utf8
EOF

通过 systemd，通常可以使用 localectl 命令启用 UTF-8 locale 区域设置：

sudo localectl set-locale LANG=C.UTF-8

UTF-8 区域设置可以通过两种方式启用。

• 通过 systemd，通常使用 localectl 命令启用：

  sudo localectl set-locale LANG=C.UTF-8

• 或者，使用 update-locale 命令启用：

  sudo update-locale LANG=C.UTF-8

可以使用 update-locale 命令启用：

sudo update-locale LANG=C.UTF-8

下载

在每个 EMQX 版本中，我们都会针对不同的操作系统与平台发布不同的安装包选项，您可点击以下链接下载：

• 官网下载：https://www.emqx.io/zh/downloads

此外，您还可在我们的 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	是	是
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 12 macOS 13 (Homebrew)	是	是

文件和目录

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

1. 压缩包解压安装时，目录相对于软件所在目录；
2. Docker 容器使用压缩包解压安装的方式，软件安装于 /opt/emqx 目录中；
3. 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.conf
• data/configs/cluster.hocon

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