📚 课程目录第4章 EMQX安装与基础配置

4. EMQX 安装与基础配置：Docker 部署、Dashboard 介绍、基础集群配置

好，咱们进入实战环节。这一章我会带你亲手把 EMQX 跑起来。

很多初学者喜欢在物理机上直接装，但我个人强烈建议——先用 Docker。为什么？因为干净、快速、好清理。我在项目中吃过亏，有一次测试环境装了一堆依赖，最后跟生产环境版本对不上，排查了一整天。从那以后，我所有中间件的原型验证都走容器化。

4.1 环境准备与 Docker 部署

先确认你的机器上已经装了 Docker。没装的话去官网下个 Docker Desktop，或者用包管理器装一下，这里不展开了。

拉取镜像很简单：

docker pull emqx/emqx:5.7.1

我个人习惯用 5.7.1 这个版本，稳定且文档齐全。你如果喜欢尝鲜，也可以用 latest，但生产环境我建议锁定版本号。

启动一个单节点实例：

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

这里我解释一下端口映射：

端口	协议/用途	说明
1883	MQTT TCP	客户端直连端口，最常用
8083	MQTT over WebSocket	浏览器或 Web 应用连接用
8084	MQTT over WSS	WebSocket 加密版
8883	MQTT over TLS	加密 TCP 连接
18083	Dashboard	管理控制台，HTTP 协议

小提示： 如果你只是本地测试，只映射 1883 和 18083 就够了。其他端口等需要时再开，减少攻击面。

启动后，用 docker ps 看看容器状态。如果显示 Up，说明跑起来了。

4.2 Dashboard 介绍：你的第一块控制面板

打开浏览器，访问 http://localhost:18083。默认用户名 admin，密码 public。第一次登录会强制你改密码，这个设计挺好的——我见过太多人用默认密码上线生产环境，结果被扫了。

Dashboard 长什么样？我带你走一遍核心区域：

左侧导航栏：监控、客户端、主题、规则引擎、插件等模块入口。
首页仪表盘：实时显示连接数、消息吞吐量、订阅数。我每次部署完第一件事就是看这里，确认数据在动。
客户端页面：列出所有连接的 MQTT 客户端，可以查看在线状态、IP、协议版本。
主题页面：查看当前集群中所有活跃的主题，以及每个主题的订阅者数量。
工具区：内置 WebSocket 客户端，可以直接在浏览器里发消息、订阅主题，调试非常方便。

重点记住： Dashboard 的「监控」模块是你排查问题的第一站。如果客户端连不上，先看连接数有没有变化；如果消息丢了，看消息速率是否异常。别一上来就翻日志，先看仪表盘。

嗯，这里有个小细节——Dashboard 本身也是 EMQX 的一个插件，叫 emqx_dashboard。如果你在容器里把 18083 映射错了，或者防火墙没开，那就进不去。我曾经在客户现场排查了半天，最后发现是安全组没放行 18083……

4.3 基础集群配置：从单点到多节点

单节点能跑，但扛不住生产压力。咱们得搭集群。

EMQX 5.x 的集群机制基于 Erlang 的分布式能力，节点之间通过 Cluster RPC 通信。说白了，就是每个节点都知道其他节点的状态，消息路由自动同步。

下面这张图展示了集群的核心逻辑：

集群搭建有两种方式：手动加入 和 自动发现。咱们先讲手动方式，因为更容易理解原理。

4.3.1 手动集群：三步搞定

假设你已经在两台机器上（或两个容器里）启动了 EMQX。节点 A 叫 emqx@node1，节点 B 叫 emqx@node2。

第一步，进入节点 A 的容器：

docker exec -it emqx-node1 bash

第二步，查看节点状态：

emqx_ctl status

如果返回 Node 'emqx@node1' is started，说明正常。

第三步，在节点 A 上执行加入集群命令：

emqx_ctl cluster join emqx@node2

注意，这里是在 节点 A 上执行，参数是 节点 B 的名字。执行完后，节点 A 会主动联系节点 B，然后合并成一个集群。

避坑指南： 我曾经在集群时遇到 Connection refused 错误。排查下来发现是两台机器的 /etc/hosts 里没有互相解析节点名。EMQX 集群依赖 Erlang 的分布式通信，节点名必须能通过 DNS 或 hosts 文件解析到 IP。你如果用的是容器，记得用 --network host 模式，或者把容器加入同一个自定义网络。

4.3.2 自动集群：用环境变量搞定

手动方式适合测试，生产环境我推荐用自动发现。EMQX 5.x 支持多种发现策略：static、dns、etcd、k8s 等。

最常用的是 static 模式，你只需要在配置里写死节点列表。比如用 Docker Compose 启动三个节点：

version: '3.8'
services:
  emqx1:
    image: emqx/emqx:5.7.1
    environment:
      - EMQX_CLUSTER__DISCOVERY_STRATEGY=static
      - EMQX_CLUSTER__STATIC__SEEDS=emqx@node1,emqx@node2,emqx@node3
      - EMQX_NODE__NAME=emqx@node1
    ports:
      - "1883:1883"
      - "18083:18083"

  emqx2:
    image: emqx/emqx:5.7.1
    environment:
      - EMQX_CLUSTER__DISCOVERY_STRATEGY=static
      - EMQX_CLUSTER__STATIC__SEEDS=emqx@node1,emqx@node2,emqx@node3
      - EMQX_NODE__NAME=emqx@node2

  emqx3:
    image: emqx/emqx:5.7.1
    environment:
      - EMQX_CLUSTER__DISCOVERY_STRATEGY=static
      - EMQX_CLUSTER__STATIC__SEEDS=emqx@node1,emqx@node2,emqx@node3
      - EMQX_NODE__NAME=emqx@node3

启动后，三个节点会自动发现并组网。你可以在任意一个节点的 Dashboard 上看到集群成员。

4.4 验证集群状态

集群搭好了，怎么确认它真的在工作？

方法一：用命令行

emqx_ctl cluster status

返回结果会列出所有节点，以及它们的状态（running / stopped）。

方法二：看 Dashboard

登录任意节点的 Dashboard，左侧导航栏找到「集群」菜单。里面会显示节点列表、角色（核心/复制）、连接数分布。你想想看，如果三个节点都在，而且连接数大致均匀，那就说明集群正常。

我的经验： 验证集群最直接的办法——在节点 A 上订阅一个主题，然后在节点 B 上向这个主题发消息。如果节点 A 收到了，说明集群路由没问题。这个测试我每次部署完都会做一遍，花不了 30 秒，但能避免很多隐性问题。

4.5 本章小结

这一章我们做了三件事：用 Docker 跑起了 EMQX 单节点、熟悉了 Dashboard 的核心功能、搭建了一个三节点集群。

嗯，这里要提醒你——集群不是搭完就完事了。你还需要考虑节点间的网络延迟、防火墙规则、证书同步等问题。不过这些咱们后面章节会逐个展开。

现在，你的 EMQX 已经能跑了。下一件事，就是给它加上授权和策略。别急，咱们一步步来。