# 快速开始

本章节将指导您从下载安装开始,快速开始使用 EMQX。

# 版本选择

EMQX 提供开源版和企业版下载安装,也提供了全托管的 MQTT 云服务 EMQX Cloud,您可以选择合适您的部署方式,快速开始使用。

# 安装 EMQX

# 在 EMQX Cloud 中运行

EMQX Cloud 是全球首个全托管的 MQTT 5.0 公有云服务。在 EMQX Cloud (opens new window) 支持下,您可以在云上创建 EMQX 集群并使用 EMQX 企业版全部功能。这使您可以将更多的时间花费在业务对接上,而将较少的时间用于 EMQX 的运维和管理。

# 通过 Docker 容器运行

EMQX 提供了一个容器镜像,您可以在 Docker Hub (opens new window)上了解该镜像的详细信息。通过容器化部署是快速开始体验 EMQX 的最快方式。

  1. 获取 Docker 镜像
1docker pull emqx/emqx:latest
1
  1. 启动 Docker 容器
1docker run -d --name emqx -p 1883:1883 -p 8081:8081 -p 8083:8083 -p 8084:8084 -p 8883:8883 -p 18083:18083 emqx/emqx:latest
1

更多 Docker 安装、Docker Compose 快速搭建集群集群请参考通过 Docker 运行 (包含简单的 docker-compose 集群)

# Kubernetes 安装部署

对于使用 Kubernetes 的用户,EMQX 提供了 EMQX Kubernetes Operator (opens new window)。该 Operator 可以帮助您在 Kubernetes 环境下快速部署一个可用于生产环境的,功能完备的 EMQX 集群。

EMQX Kubernetes Operator 是基于 Kubernetes 原生 API 的应用编排工具,用于 EMQX 集群的自动化部署和生命周期管理。您可以查阅文档 (opens new window)来了解如何使用 Operator 部署 EMQX。

# Terraform 安装部署

通过 Terraform 在主流公有云上一键部署包含 EMQX Enterprise 集群在内的所有基础设施。在公有云上部署 EMQX Enterprise 集群最快捷的方式:

更多有关 Terraform 安装部署的信息请参考 EMQX Terraform (opens new window)

# 在虚拟机或物理机中运行

EMQX 可以直接部署在物理服务器或者虚拟机上。最小仅需 2 核 4G 的机器即可运行 EMQX 程序。可支持 CentOS, Debian, Ubuntu, MacOS 等操作系统。

如果您需要 FreeBSD、国产硬件平台以及操作系统适配(如麒麟、深度、红旗等)或其他 Linux 发行版安装包,可参考 源码编译安装联系我们 (opens new window) 获取支持。

# 启动 EMQX

安装成功后,可通过 systemctlemqx 命令来启动 EMQX,更多启动方式和注意事项参考 启动 EMQX

EMQX 成功启动之后可以通过浏览器打开 http://localhost:18083/ (opens new window)(将 localhost 替换为您实际 IP 地址)以访问 EMQX Dashboard 管理控制台,进行设备连接与相关指标监控管理。

# 后台启动 EMQX

emqx start
1

启动成功后可以使用 emqx ping 命令检测节点运行状态,返回 pong 则表示正常运行:

emqx ping
1

# systemctl 启动

sudo systemctl start emqx
1

检查服务是否正常工作:

sudo systemctl status emqx
1

# ZIP 安装包启动

切换到 EMQX 解压目录,执行以下命令启动 EMQX:

./bin/emqx start
1

开发模式下可以使用 console 命令在控制台启动 EMQX,该模式可以实时查看 EMQX 启动和运行输出日志信息:

./bin/emqx console
1

# EMQX 快速体验

EMQX 提供了标准的 MQTT 协议支持,启动后即可接入 MQTT 客户端,您可以使用以下客户端工具或客户端库接入 EMQX 进行消息通信以完成某些场景或功能的测试验证。

# Dashboard Websocket 工具

打开 Dashboard,进入 工具 -> Websocket 页面中可以使用 MQTT over Websokcet 客户端快速接入 EMQX。

Websocket 页面为您提供了一个简易但有效的 WebSocket 客户端工具,它包含了连接、订阅和发布功能,同时还能查看自己发送和接收的报文数据。

emqx-mqtt-websocket-tool

# MQTT X 桌面客户端工具

MQTT X 是一款优雅的跨平台 MQTT 5.0 开源桌面客户端工具,支持在 macOS, Linux 和 Windows 上运行。

MQTT X 有诸多特性,提供了简洁的图形界面和操作逻辑,支持 MQTT/MQTT over Websocket 接入以及单/双向 SSL 认证,同时支持 Payload 格式转换、自定义脚本模拟测试数据、 $SYS 主题自动订阅查看流量统计等诸多实用功能。

下载与使用可参考 MQTT X 官网 (opens new window)

emqx-mqttx

# EMQX 客户端库

以下是各个编程语言中热门 MQTT 客户端库介绍说明,各个库的连接(包含 TLS 连接)、发布、订阅、取消订阅基本功能代码示例。

# 客户端库介绍

# 客户端库项目工程代码示例

MQTT 客户端库接入示例工程项目代码,涵盖 Android (opens new window)Csharp-MqttNet (opens new window)ESP32 (opens new window)ESP8266 (opens new window)Electron (opens new window)Flutter (opens new window)Go (opens new window)Java (opens new window)PHP (opens new window)Qt (opens new window)SpringBoot (opens new window)Vue.js (opens new window)swift (opens new window)wechat-miniprogram (opens new window) 等数十种主流编程语言和技术,详细列表请查看 MQTT-Client-Examples (opens new window)

# 进阶操作

完成基本的安装、启动、接入测试之后,您可以继续阅读以下操作文档进行进阶操作配置。

# 认证鉴权

身份认证与是大多数应用的重要组成部分,启用身份认证能有效阻止非法客户端的连接。发布订阅 ACL 可以对客户端发布 /订阅操作进行权限控制。

  • 认证简介:选择内置插件、外部数据库、JWT 或者 HTTP 服务作为认证数据源,验证客户端连接合法性。
  • 发布订阅 ACL:选择内置插件、外部数据库、或者 HTTP 服务作为 ACL 数据源,验证客户端发布订阅权限。

# 规则引擎

基于 SQL 的内置规则引擎可以实时提取、过滤、丰富和转换设备与业务系统之间的 IoT 数据,无需编写代码即可将物联网数据转发到 Webhook、其他 MQTT Broker 中,在企业版中还能够与 Kafka、各类 SQL / NoSQL / 时序数据库以及 SAP 等企业系统集成。

# HTTP API

HTTP API 是物联网平台开发与 EMQX 运维中频繁使用的功能,HTTP API 可以实现与外部系统的集成,例如查询并管理客户端信息、代理订阅、发布消息和创建规则等。

  • HTTP API:包含 HTTP API 接入点、接入认证方式。
  • 基本信息:获取 EMQX 版本、运行状态等基本信息。
  • 节点:获取 EMQX 节点信息。
  • 客户端:查看在线客户端信息,支持踢出客户端。
  • 订阅信息:查看订阅主题列表与订阅关系。
  • 路由:查看已订阅的主题。
  • 消息发布:通过 HTTP 调用 EMQX 发布 MQTT 消息,应用程序与客户端通信可靠的方式。
  • 主题订阅:动态管理客户端订阅列表,无需客户端主动发起订阅/取消订阅。
  • 插件:插件的状态管理,启动、停止操作。

接入认证方式以及更多 API 请查看 HTTP API

# 运维部署

包含官方使用指南、最佳实践等信息。

# 常见问题解答

FAQ 常见问题解答 定期收集整理 EMQX 用户常见问题和经常遇到的错误,如 Topic 数量限制、外部资源连接错误、启动失败原因等。

除此之外,您可以访问 EMQ 问答社区 (opens new window) 参与交流,提出、解答 EMQX 以及 EMQ 相关产品使用问题,与 EMQX 用户交流物联网相关技术的使用经验。