📚 课程目录第2章 EMQX单节点快速部署

2. EMQX单节点快速部署

EMQX 的单节点部署是后续集群、桥接、规则引擎等所有实验的起点。所谓“单节点”，是指一台 Linux 主机上只运行一个 EMQX 实例，它同时承担 MQTT 接入、会话管理、消息路由和 Dashboard 管理。本节围绕三种主流部署方式展开：二进制包（zip/tar.gz）、Docker 容器和系统包管理器（deb/rpm）。三者的核心差异不在 EMQX 本身，而在于安装位置、服务托管方式、升级路径和配置文件的落点。理解这些差异，才能在实际工程中选对方式。

部署前的环境确认

无论哪种方式，先确认主机满足基本条件。EMQX 5.x 要求 64 位 Linux，建议 2 核 4GB 以上；需要开放 1883（MQTT）、8083（WebSocket）、8883（MQTT over TLS）、8084（WSS）和 18083（Dashboard）端口。用以下命令检查系统信息与端口占用：

uname -m                      # 期望输出 x86_64 或 aarch64
cat /etc/os-release           # 确认发行版与版本
ss -lntp | grep -E '1883|8083|8883|8084|18083'
ulimit -n                     # 建议不低于 1024，生产建议 65536

如果端口被占用，需要先停止冲突进程或调整 EMQX 监听端口。此外，EMQX 默认以非 root 用户运行更安全，二进制包方式尤其要注意运行用户对数据目录的写权限。

方式一：二进制包部署

二进制包适合需要精确控制安装路径、希望同一台机器并存多个版本、或不便使用包管理器的场景。以 EMQX 5.8 为例，从官网下载对应架构的 zip 包后解压即可：

wget https://www.emqx.com/zh/downloads/broker/5.8.0/emqx-5.8.0-ubuntu22.04-amd64.zip
unzip emqx-5.8.0-ubuntu22.04-amd64.zip -d /opt
cd /opt/emqx
./bin/emqx start          # 后台启动
./bin/emqx ctl status     # 查看运行状态

二进制包的关键目录结构是：bin/ 存放 emqx 与 emqx ctl 命令，etc/ 存放 emqx.conf 与 acl.conf，data/ 存放 Mnesia 数据与持久化会话，log/ 存放日志。启动后可用 ./bin/emqx ctl status 看到 Node 'emqx@127.0.0.1' is started 字样，说明节点已就绪。停止用 ./bin/emqx stop，前台调试用 ./bin/emqx console，此时日志直接打印到终端，便于排查启动失败。

方式二：Docker 部署

Docker 方式隔离性好、启动快，适合快速验证和 CI 环境。官方镜像为 emqx/emqx，推荐指定具体版本而非 latest：

docker run -d --name emqx \
  -p 1883:1883 -p 8083:8083 -p 8883:8883 \
  -p 8084:8084 -p 18083:18083 \
  -v /data/emqx/data:/opt/emqx/data \
  -v /data/emqx/log:/opt/emqx/log \
  emqx/emqx:5.8.0

这里把 data 和 log 挂载到宿主机，避免容器重建后会话与配置丢失。查看启动日志用 docker logs -f emqx，进入容器执行管理命令用 docker exec -it emqx emqx ctl status。需要注意：容器内 EMQX 默认监听 0.0.0.0，端口映射必须与 emqx.conf 中的监听器一致，否则会出现“容器在跑但连不上”的情况。

方式三：包管理器部署

deb/rpm 方式把 EMQX 注册为 systemd 服务，开机自启、日志交给 journald，最贴近生产运维习惯。以 Ubuntu 为例：

wget https://www.emqx.com/zh/downloads/broker/5.8.0/emqx-5.8.0-ubuntu22.04-amd64.deb
sudo apt install ./emqx-5.8.0-ubuntu22.04-amd64.deb
sudo systemctl start emqx
sudo systemctl enable emqx
systemctl status emqx

安装后配置文件位于 /etc/emqx/emqx.conf，数据目录为 /var/lib/emqx，日志在 /var/log/emqx。管理命令仍可用 emqx ctl status，但服务生命周期建议统一用 systemctl 控制，避免两套机制冲突。升级时直接安装新版本 deb 包，systemd 会接管重启。

启动后的验证与基础管理

三种方式启动后，验证逻辑是一致的。第一步看状态：二进制包用 ./bin/emqx ctl status，Docker 用 docker exec -it emqx emqx ctl status，包管理器用 systemctl status emqx，都应看到节点已启动。第二步看端口：ss -lntp | grep 1883 应显示 EMQX 进程在监听。第三步登录 Dashboard：浏览器访问 http://主机IP:18083，默认账号 admin、密码 public，首次登录会强制修改密码。第四步做一次真实收发：

# 终端 A 订阅
mosquitto_sub -h 127.0.0.1 -p 1883 -t test/topic -v
# 终端 B 发布
mosquitto_pub -h 127.0.0.1 -p 1883 -t test/topic -m "hello emqx"

终端 A 收到 test/topic hello emqx，说明消息链路完整。此时在 Dashboard 的“连接”页可以看到订阅客户端，在“监控”页能看到消息收发计数增长。基础管理还包括：在 Dashboard 中查看节点信息、在线客户端数、主题数；用 emqx ctl clients list 列出客户端；用 emqx ctl topics list 查看主题。若需要修改监听端口或开启认证，编辑 emqx.conf 后执行 emqx ctl reload 热加载，或重启服务。

选择建议：学习与快速验证优先 Docker；需要长期运行且希望开机自启，选包管理器；需要在一台机器上并存多个版本做对比测试，选二进制包。三者不要混装在同一目录，否则数据目录和端口会互相干扰。

常见问题：Dashboard 打不开，先确认 18083 端口是否放行、防火墙是否拦截；客户端连不上，检查 1883 监听地址是否为 0.0.0.0 而非仅 127.0.0.1；Docker 方式数据丢失，通常是忘记挂载 /opt/emqx/data。启动失败时优先看 log/emqx.log 或 docker logs，错误信息通常直接指出端口冲突或权限不足。

完成本节后，你应该能在一台干净的 Linux 主机上，用任意一种方式把 EMQX 跑起来，并通过状态命令、端口检查、Dashboard 登录和一次真实消息收发确认它工作正常。这套验证动作也是后续排查集群、桥接和认证问题时的基础手段。