EMQX 安装详解：从零搭建你的 MQTT 消息服务器

从"设备互联"说起

你有没有遇到过这样的场景------家里的智能灯和传感器用的是不同品牌，手机上的智能家居 App 开了五六个，但设备之间却"老死不相往来"？或者在开发物联网项目时，几十台设备同时上报数据，服务器却扛不住频繁的断连和吞吐压力？

这些问题的背后，其实都指向同一个核心需求：一个轻量、稳定、高并发的消息中间件。而 MQTT 协议正是为解决这类场景而生的，EMQX 则是这个领域里最值得关注的开源实现之一。

今天我们就来详细讲讲 EMQX 的安装部署，从 Docker 一键启动到 Linux 生产部署，再到 Windows 上的开发环境搭建，一次性帮你搞定。

一、EMQX 是什么？

EMQX（原名 EMQ X）是一个大规模可弹性伸缩的云原生分布式物联网 MQTT 消息服务器，基于 Erlang/OTP 语言开发，采用 Apache 2.0 开源协议。

说人话就是：它是物联网设备之间传递消息的"中间人"。设备 A 发一条消息，EMQX 负责把它准确投递给需要收到这条消息的设备 B、C、D......不管有多少设备，它都能撑得住。

EMQX 目前已经被超过 20,000 家企业采用，连接了超过 2.5 亿台物联网设备，客户包括 HPE、VMware、上汽大众、Ericsson 等世界 500 强企业。

它的核心性能指标：

单节点支持 500 万并发 MQTT 连接
单集群支持 1 亿并发连接
消息投递延迟低于 1 毫秒
完整支持 MQTT v3.1、v3.1.1、v5.0 协议

二、安装方式总览

EMQX 的安装方式非常灵活，覆盖了主流平台：

安装方式	适用场景	难度
Docker	开发测试 / 快速体验	低
Linux APT/YUM	生产环境部署	中
Linux 二进制包	内网 / 自定义安装	中
Windows WSL2+Docker	Windows 开发环境	较高
Kubernetes Operator	云原生容器编排	高

下面我们逐一详细介绍。

三、Docker 安装（最快上手）

如果你只是想快速体验 EMQX，或者用于开发测试，Docker 是最快的途径。

3.1 拉取镜像

bash 复制代码

docker pull emqx/emqx:5.3.2

建议使用带具体版本号的镜像，而不是 latest 标签，这样可以避免未来版本升级带来的不兼容问题。

3.2 启动容器

bash 复制代码

docker run -d --name emqx \
  -p 1883:1883 \
  -p 8083:8083 \
  -p 8084:8084 \
  -p 8883:8883 \
  -p 18083:18083 \
  emqx/emqx:5.3.2

各端口的用途：

1883：MQTT 未加密连接（最常用）
8883：MQTT over SSL/TLS（加密连接）
8083：MQTT over WebSocket（浏览器连接用）
8084：MQTT over WSS（加密 WebSocket）
18083：Dashboard 管理控制台

启动后打开浏览器访问 http://localhost:18083 ，默认用户名 admin，密码 public，就能看到 EMQX 的管理界面了。

3.3 数据持久化

Docker 容器的数据默认是临时的，容器删除后配置和数据就全丢了。生产环境一定要做持久化：

bash 复制代码

docker run -d --name emqx \
  -p 1883:1883 -p 8083:8083 \
  -p 8084:8084 -p 8883:8883 \
  -p 18083:18083 \
  -v $(pwd)/emqx/data:/opt/emqx/data \
  -v $(pwd)/emqx/log:/opt/emqx/log \
  -v $(pwd)/emqx/etc:/opt/emqx/etc \
  emqx/emqx:5.3.2

三个挂载目录各有分工：data 存运行时数据，log 存日志，etc 放自定义配置。

3.4 Docker Compose 搭建集群

需要高可用的话，Docker Compose 几分钟就能拉起一个双节点集群：

yaml 复制代码

version: '3'
services:
  emqx1:
    image: emqx/emqx:5.3.2
    environment:
      - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
      - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@emqx1, emqx@emqx2]"
    ports:
      - "1883:1883"
      - "18083:18083"
    volumes:
      - ./emqx1_data:/opt/emqx/data

  emqx2:
    image: emqx/emqx:5.3.2
    environment:
      - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
      - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@emqx1, emqx@emqx2]"
    ports:
      - "1884:1883"
    volumes:
      - ./emqx2_data:/opt/emqx/data

启动命令：

bash 复制代码

docker-compose up -d

两个节点会自动发现、自动组网，完全不需要手动配置复杂的集群参数。我之前在机房部署时，十几分钟就搭好了一套三节点集群，确实省心。

四、Linux 安装（生产环境推荐）

生产服务器上推荐用包管理器安装，后续升级和维护都方便。

4.1 APT 安装（Debian / Ubuntu）

bash 复制代码

# 安装依赖
sudo apt update
sudo apt install -y wget gnupg

# 添加 EMQX GPG 密钥
wget -q -O - https://repos.emqx.io/emqx-ce/debian/emqx-ce.gpg.key | sudo apt-key add -

# 添加 APT 源
echo "deb https://repos.emqx.io/emqx-ce/debian/ bullseye main" | sudo tee /etc/apt/sources.list.d/emqx-ce.list

# 安装 EMQX
sudo apt update
sudo apt install emqx

# 启动并设置开机自启
sudo systemctl start emqx
sudo systemctl enable emqx

4.2 YUM 安装（CentOS / Rocky Linux）

bash 复制代码

# 添加仓库
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://repos.emqx.io/emqx-ce/redhat/centos/7/emqx-ce.repo

# 安装
sudo yum install emqx

# 启动
sudo systemctl start emqx
sudo systemctl enable emqx

4.3 二进制包安装（通用方案）

这个方法不挑操作系统版本，也是我个人的首选方案：

bash 复制代码

# 下载最新版本
wget https://www.emqx.io/downloads/latest/emqx-latest-linux-amd64.tar.gz

# 解压
tar -zxvf emqx-latest-linux-amd64.tar.gz
cd emqx

# 启动
./bin/emqx start

# 检查状态
./bin/emqx_ctl status

二进制包的好处是不污染系统的包管理数据库，卸载时直接删目录就行。之前帮客户部署时，他们的服务器是内网环境，没有外网访问权限。我就是在自己的机器上下好 tar.gz 包，然后用 U 盘拷进去解压启动，前后不到 5 分钟就搞定了。

4.4 防火墙配置

别忘了开放端口。以 Ubuntu 的 ufw 为例：

bash 复制代码

sudo ufw allow 1883/tcp  # MQTT
sudo ufw allow 8883/tcp  # MQTT over TLS
sudo ufw allow 8083/tcp  # WebSocket
sudo ufw allow 18083/tcp # Dashboard

五、Windows 安装

官方不推荐在生产环境把 EMQX 直接部署在 Windows 上，但本地开发测试完全没问题。推荐用 WSL2 + Docker 的方式。

5.1 ZIP 包直接运行（仅测试）

从官网 https://www.emqx.io/downloads 下载 Windows ZIP 包：

cmd 复制代码

cd D:\emqx
.\bin\emqx start

然后访问 http://localhost:18083 就能看到 Dashboard。

5.2 WSL2 + Docker（推荐方案）

Windows 上开发体验最好的方式，没有之一。

第一步：启用 WSL2

以管理员身份打开 PowerShell：

powershell 复制代码

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

重启后设置 WSL2 为默认版本：

powershell 复制代码

wsl --set-default-version 2

第二步：安装 Ubuntu

从 Microsoft Store 安装 Ubuntu 22.04 LTS，启动后设置好用户名和密码。

第三步：限制 WSL2 内存占用

在 C:\Users\你的用户名\.wslconfig 中写入：

ini 复制代码

[wsl2]
memory=4GB
processors=4
swap=2GB
localhostForwarding=true

然后重启 WSL：

powershell 复制代码

wsl --shutdown

这一步很重要。之前我没配内存限制的时候，WSL 经常把 16G 内存吃光，Windows 直接卡死。加上限制之后，EMQX 跑得稳稳的，两边互不影响。

第四步：安装 Docker 并启动 EMQX

在 Ubuntu 终端中：

bash 复制代码

sudo apt update
sudo apt install -y docker.io
sudo service docker start
sudo usermod -aG docker $USER

退出终端重新进入，然后拉取镜像并启动：

bash 复制代码

docker pull emqx/emqx:5.3.2
docker run -d --name emqx -p 1883:1883 -p 18083:18083 emqx/emqx:5.3.2

在 Windows 浏览器中访问 http://localhost:18083 就能看到管理界面了。

六、安装后验证

检查服务状态

bash 复制代码

# Docker 方式
docker ps | grep emqx

# Linux 包管理器方式
sudo systemctl status emqx

# 二进制方式
./bin/emqx_ctl status

用 MQTTX 客户端测试

推荐使用 EMQX 官方开发的 MQTTX 客户端（https://mqttx.app/），这是一款跨平台 MQTT 桌面客户端：

打开 MQTTX，点击"新建连接"
填入名字，服务器地址填 localhost:1883
点击"连接"
订阅主题 test/topic
向同一主题发送消息 Hello EMQX

如果能正常收发消息，恭喜你，EMQX 已经成功运行了。

总结

EMQX 的安装方式非常灵活，从开发环境到生产集群都有对应的方案：

Docker 安装：5 分钟搞定，适合快速体验
Linux 包管理器：生产部署首选，方便运维
二进制包：内网部署神器，不挑系统
Windows WSL2+Docker：本地开发的最佳体验

上手 EMQX 其实比想象中简单，最难的反而是理解 MQTT 的发布/订阅模型------数据生产者和消费者之间通过"主题"来解耦，这个思路一旦搞明白，后面所有的安装配置就水到渠成了。

EMQX 官方文档：https://docs.emqx.com/zh/emqx/latest/