【EMQX实践】EMQX Dashboard使用教程

EMQX Dashboard是EMQX Broker的一个内置Web管理控制台，它为用户提供了一个直观且功能丰富的界面来监控、管理和配置EMQX集群。本文主要介绍实践中常用的功能。

首页

概览：显示整个集群内数据的概况
节点：查看集群中的节点列表和节点信息
指标：查看集群或单个节点内所有的数据指标

【可以在设置修改为中文】

客户端管理

用户可在管理连接中，查看当前连接至服务器或会话尚未过期的客户端及某一连接的详细信息和指标统计。可使用 MQTTX 作为客户端连接到 EMQX 进行发布订阅。

客户端管理列表

在连接管理列表中，用户可查看当前接入服务器或会话尚未过期的的连接列表及连接的基本信息，列表将展示各客户端连接到 EMQX 时设置的 ID 及用户名，当前的连接状态，客户端的 IP 地址，连接设置的心跳时长即连接最大空闲时长，还有关于连接会话的信息，包括是否清除会话及会话过期间隔，客户端连接至 EMQX 的时间；其中客户端的 IP 地址数据由客户端的 IP 地址及客户端连接到 EMQX 时使用的客户端的端口拼接而成。

客户端详情

选择某一连接，点击客户端 ID 可进入该连接的连接详情页面。
客户端详情页面的顶部可以手动刷新该连接的连接信息，以及查看该连接的连接指标统计，也可以手动剔除或清除该连接。

订阅管理

订阅列表页面根据客户端 ID —— 主题的映射关系，展示了所有连接订阅的主题及订阅的基本信息，除了客户端 ID、主题及 QoS 外，列表还提供了 MQTT v5 新支持的订阅特性信息

控制访问

进行各类访问规则的设定

认证

EMQX Dashboard 提供了开箱即用的认证与权限管理功能，用户仅通过用户界面，就可以快速实现客户端认证授权机制的配置，无需编写代码或手动编辑配置文件，即可对接各类数据源与认证服务，实现各个级别与各类场景下的安全配置，以更高的开发效率获得更安全的保障。

创建认证

在认证页面下的右上角，点击 创建 按钮，即可进入到创建认证的页面。创建一个认证需要选择一种认证方式，选择完成后需要选择一个存储或获取认证信息的数据源（JWT 认证方式除外），认证数据可以从这些数据源包括数据库或 HTTP 服务中获取，最后再配置连接到该数据源的连接信息即可。

认证方式

目前 EMQX 提供了三种认证方式，包含有：

1. Password-Based，使用客户端 ID 或用户名加密码的认证方式；
2. JWT，客户端可以在用户名或密码字段中携带 JWT token 来进行认证；
3. SCRAM，MQTT 5.0 中的增强认证，可以实现对客户端和服务器的双向认证。

数据源

当选择 Password-Based 的认证方式后，用户可以选择存储认证数据的数据库或提供认证数据功能的 HTTP 服务器，数据库包含两类：
EMQX 的内置数据库，即选择 Built-in Database；
外部数据库，支持选择并连接到一些主流数据库，包括：MySQL、PostgreSQL、MongoDB、Redis 等。

配置参数

选择完数据源后，我们就来到了创建认证的最后一步，配置选择好的数据源，每一个数据源都有一些连接或使用时的配置信息需要用户手动配置。

认证列表

创建认证器成功后，可以在认证列表中查看和管理。列表中我们可以查看到认证器的数据源及认证方式，数据源状态，比如外部数据库没有正常部署成功和连接到的话，可看到目前数据源状态为已断开。鼠标悬浮到该字段的话，可以查看更多 EMQX 集群内所有节点连接到该数据源的状态。点击是否启用开关，可以快速开启和关闭该认证配置。

授权

EMQX 提供了强大的权限控制能力，而 EMQX Dashboard 提供了开箱即用的授权管理功能，通过可视化页面来快速配置 EMQX 的授权机制，无需编写代码或手动编辑配置文件，即可实现对 MQTT 客户端连接后的发布和订阅操作进行权限控制，实现各个级别与各类场景下的安全配置。
在左侧的访问控制菜单下，用户可以进入到授权页面，授权页面中用户可以快速创建和管理创建好的各类授权的配置资源。

创建授权

在授权页面的右上角，点击 创建 按钮，即可进入到创建授权的页面，配置数据源，以便 EMQX 查询权限数据和进行权限检查。

数据源

数据源包含了选择使用文件，内置数据库，外部数据库或外部的 HTTP 服务。
选择使用 ACL 文件来编辑和保存授权的规则内容，通过为每个发布或订阅请求扫描文件中定义的一系列规则来确定该请求是否有权限执行想要的操作。
选择使用 EMQX 内置数据库，除支持配置和存储认证数据外，同样可以使用其来配置和存储授权规则。
使用外置数据库来存储授权规则，支持以下主流数据库：MySQL、PostgreSQL、MongoDB、Redis。

配置参数

选择完后端后就到了创建授权的最后一步，配置选择好的后端，每一个后端都有一些连接或使用时的配置信息需要用户手动配置，或编辑权限规则保存到文件内。

文件

选择使用 ACL 文件后，在配置参数页面提供了一个文本编辑框，需要编辑文件的授权规则内容，是一个 Erlang 元组数据的列表。（注意每条规则后面必需有一个点号 .）元组是用花括号包起来的一个列表，各个元素用逗号分隔。

授权设置

当需要修改授权配置的数据源时，可以点击列表页中的 设置，在设置页面可以修改配置信息，如需要修改 ACL 的权限规则内容时，或当外部数据库的一些连接信息发生或查询语句发生变化时。
以ACL授权系统主题设置为例

黑名单

EMQX 除认证授权外，还提供了禁用客户端功能，可以直接拒绝对于有恶意性或攻击性的客户端连接。黑名单适合对于少量的客户端连接的封禁。

创建黑名单

点击右上角的 创建 按钮，可以打开创建黑名单的弹出框。用户可以设置禁用对象，选择是通过客户端 ID，用户名还是 IP 地址的禁用属性，并输入对应的禁用值，设置一个到期时间，并输入创建该黑名单的原因。注意：到期时间和原因为非必填项。

数据集成

EMQX Dashboard 提供集成各类数据方式

Webhook

使用 Webhook 其实就是将 EMQX 接收并处理后的数据发送到一个 HTTP 服务上，再根据预设好的 HTTP 服务来处理和集成业务数据。
同样用户需要有一个预先搭建好的 HTTP 服务，我们需要在配置信息页面填写 HTTP 请求的服务地址，选择一个请求方法 POST、GET、PUT 或 DELETE，配置请求头，将需要发送的数据使用模板语法填写到请求体（body）中即可。

数据桥接

作为 EMQX 为物联网数据基础设施构建提供的最重要能力之一，数据集成帮助用户将所有的业务数据无需额外编写代码即可快速完成处理与分发。数据集成能力由数据桥接和规则两部分组成，用户可以使用数据桥接或 MQTT 主题来接入数据，使用规则处理数据后，再通过数据桥接将数据发送到外部应用系统中。详情请查看规则引擎。
通过数据桥接，用户可以实时地将消息从 EMQX 发送到外部数据系统，或者从外部数据系统拉取数据并发送到 EMQX 的某个主题。而 EMQX Dashboard 提供了可视化创建数据桥接的能力，只需在页面中配置相关资源即可。详情请查看数据集成。
在左侧的数据集成菜单下，用户可以进入到数据桥接页面，数据桥接页面中用户可以快速创建和管理创建好的数据桥接。

创建数据桥接

点击数据桥接页面的右上角的 创建 按钮，即可进入到创建数据桥接的页面。创建桥接需要先选择一个数据桥接的类型，最后再完成对于该类型数据桥接的相关配置即可。
目前数据桥接类型包含：

• HTTP服务，发数据到 HTTP 服务；
• MQTT，使用 MQTT 服务作为数据源来获取外部 MQTT 消息，或将 EMQX 的消息发送到外部 MQTT 服务；

HTTP服务

将 EMQX 接收并处理后的数据发送到一个 HTTP 服务上，再根据预设好的 HTTP 服务来处理和集成业务数据。
同样用户需要有一个预先搭建好的 HTTP 服务，我们需要在配置信息页面填写 HTTP 请求的服务地址，选择一个请求方法 POST、GET、PUT 或 DELETE，配置请求头，将需要发送的数据使用模板语法填写到请求体（body）中即可。

MQTT

使用 MQTT 数据桥接，用户可以将 EMQX 的 MQTT 消息发送到外部的 MQTT 服务上，或者从外部的 MQTT 服务上拉取数据并发送到 EMQX 的某个主题上。
在 MQTT 数据桥接中，用户首先需要配置 MQTT 服务的连接信息，包括服务地址、端口、用户名、密码等信息。

然后，用户可以按需配置该 MQTT 服务的入口或出口配置，如果需要将该服务作为数据源的话，则手动打开入口配置，如果是数据目标则手动打开出口配置。例如，如果配置了入口，则表示从外部 MQTT 服务上拉取数据并发送到 EMQX 的某个主题上，如果配置了出口，则表示将 EMQX 的 MQTT 消息发送到外部的 MQTT 服务上。
【注意：创建时，至少选择一个入口或出口进行配置，也可以同时都配置。】

入口配置

当开启入口配置后，该 MQTT 数据桥接可以作为一个数据源，用户需要配置一个远程 MQTT 服务下的主题和 QoS 等级，远程 MQTT 服务则为上述中配置连接的 MQTT 服务。当用户向该远程服务的主题发送消息时，EMQX 就可以接收到该消息，用户可以在规则的 SQL 语句中使用该数据桥接，来接收并处理接收到的消息数据。
除远程 MQTT 服务外，还有一个本地 MQTT 服务配置，即 EMQX，用户可以配置该服务的下的主题，QoS，retain 标识和消息内容模版（这些配置项都支持模版语法）。如果当用户配置了本地的 MQTT 服务主题后，用户则不需要使用规则，连接到 EMQX 并订阅该本地主题后，也可以接收到远程服务的消息。

出口配置

当开启了出口配置后，该 MQTT 数据桥接可以作为一个数据目标，用户需要配置一个远程 MQTT 服务的主题和 QoS 等级，retain 标识和消息的内容模版（这些配置项都支持模版语法），远程 MQTT 服务则为上述中配置连接的 MQTT 服务。当用户使用规则接收和处理了消息数据后，只需要把该数据桥接添加到规则的动作列表中，EMQX 就可以将处理过的消息数据发送到该远程 MQTT 服务上。
除远程 MQTT 服务外，还有一个本地 MQTT 服务配置，即 EMQX，用户可以配置该服务的下的主题。如果当用户配置了本地的 MQTT 服务主题后，用户则不需要使用规则，连接到 EMQX 并向本地主题发送消息时，也可以将消息转发到该远程服务上。

数据桥接列表

在数据桥接列表，我们可以查看到已经创建成功的数据桥接的名称，桥接内配置的资源的状态，已连接或已断开，点按是否启用开关可以开启或停用该数据桥接，在操作栏可以快速删除数据桥接，点击 创建规则，可以使用该数据桥接快速创建一个规则，即进入到创建规则页面后，自动添加好该数据桥接。

规则引擎

规则引擎是 EMQX 内置的数据处理功能，它使用 SQL 语句编排规则，并通过消息、客户端事件以及外部数据系统触发，无需编写代码即可实现一站式的 IoT 数据提取、过滤、丰富和转换处理，并将处理完成后的数据输出到动作或外部数据系统中。
规则是构成 EMQX 强大的数据集成能力的一部分，配合使用 Sink/Source 提供了清晰、灵活的业务集成方案，能够简化业务开发流程，提升用户易用性并降低业务系统与 EMQX 的耦合度。详情请查看规则引擎。
在左侧的数据集成菜单下，用户可以进入到规则页面。规则页面中用户可以创建和管理创建好的规则。

创建规则

创建规则可以在规则页面的右上角，点击 创建 即可进入到创建规则页面。也可以在动作页面，使用已经创建好的动作，来快速创建一个包含此动作的规则。

SQL 编辑

进入到创建规则页面，我们可以看到一个 SQL 编辑器，规则是基于 SQL 语句来使用的，我们可以使用 SQL 语句来实时的查询过滤，转换和丰富客户端之间或系统业务之间的数据。顶部两个输入框分别为，规则 ID 和备注，进入创建页面后，会随机生成一个规则 ID 来标识当前规则，也可以手动输入你想要输入的规则标识，可以在备注中输入一些规则的描述信息来区分每个规则的使用。
右侧提供了一个 SQL 模版的选择，可以选择不同的 SQL 模版来快速创建规则。目前提供了 6 种比较常用的 SQL 模版，分别是：

1. 选择指定主题的消息
2. 同时处理客户端连接、断开连接事件
3. FOREACH 处理 JSON 数组并逐个输出
4. FOREACH 处理 JSON 数组选择指定字段并添加过滤条件
5. CASE-WHEN 从多个条件列表返回可能结果
6. 数组处理 - 从 JSON 格式的 payload 中获取嵌套的值

SQL 语句默认为 SELECT * FROM “t/#”，其含义为当客户端向 t/# 这个主题发送消息时，我们就取出当前事件下所有的数据信息。SELECT 关键词可以获取消息中的所有字段，例如可以获取当前消息的 Payload，则 SQL 语句可以修改为 SELECT payload from “t/#”，获取的内容可以使用内置函数来进行处理和转化，FROM 关键词后面输入数据源，即事件主题，下方规则调试部分可查看到所有可选的数据源事件，使用 WHERE 关键词，可以添加条件判断，更多详细的 SQL 语法使用，请参考 SQL 语法与示列。

规则调试

当完成 SQL 语句的编写后，可以在页面底部的调试模块选择触发规则的事件或消息来源，输入模拟的测试数据后，点击 SQL 编辑器下方的 执行 SQL 按钮，即可在页面底部的输出结果中看到规则的执行结果。
每次更改完成 SQL 语句后都可以通过调试模块来测试规则的执行结果，以确保规则的正确性。注意：执行 SQL 时如果出现 412 的错误码提示时，可能是与测试数据不匹配造成的，且当数据来源与 SQL 语句不匹配时也会提示选择与其对应的事件或消息来源。更新数据来源事件后，测试数据会自动更新为对应的数据格式。
当用户选择完成数据来源后，可以在右侧的按钮中来查看，使用当前数据源的 SQL 语句，快速访问对应的使用文档，重置模拟数据，JSON 数据格式话及将模拟数据切换为表单模式等，在表单模式下，用户可以直接输入对应的字段值来模拟数据。
调试时的数据来源与真实使用场景下的一致，包含有一些 MQTT 事件，对于消息部分，我们可以选择不同的消息来源来模拟数据，包括：

• 消息发布（mqtt topic）
• 消息投递（$events/message_delivered）
• 消息确认（$events/message_acked）
• 消息丢弃（$events/message_dropped）

对于其它事件，我们可以选择不同的客户端和会话事件来模拟数据，包括：

• 连接完成（$events/client_connected）
• 连接断开（$events/client_disconnected）
• 连接确认（$events/client_connack）
• 鉴权完成（$events/client_check_authz_complete）
• 认证完成（$events/client_check_authn_complete）
• 订阅（$events/session_subscribed）
• 取消订阅（$events/session_unsubscribed）

此外还支持使用 Source 作为数据来源，通过 $bridges/* 开头的主题选取来自 Source 的消息：

• Source（$bridge/:）

对应的数据源需要与编辑器中的 SQL 语句保持一致，当需要使用上述中的一些消息事件或 Source 来获取数据时，需要将对应的事件主题（括号中的内容）填写到 SQL 语句中， FROM 关键词的后面，规则支持使用多个事件。更多详细的数据源与事件解释，请参考 SQL 数据源和字段。

规则动作

完成 SQL 语句的编辑和规则调试后，我们可以得到一个符合我们需求的输出结果，这时可以在页面右侧的 动作 模块中选择规则触发执行后，需要继续执行的动作。点击 添加动作 按钮，我们可以选择动作来继续处理规则的输出结果。
其中两个内置动作包含：

1. 控制台输出，可以打印结果输出到控制台，可以用于真实场景下的调试；
2. 消息重发布，可以将规则处理后的输出结果，再次发布到指定的主题中。

如果使用外部动作转发数据，可以创建一个新的动作，也可以选择已经创建好的动作。选择动作后，规则的输出结果将转发到对应的外部数据系统上，有关每个动作的配置可参考动作页签。
更多关于规则动作的详情，请参考动作。

规则列表

当创建完成一个规则后，可以在规则列表中查看到该规则的基本信息，包含规则 ID、规则接入数据的输入（例如事件，主题和 Source 等）、规则的备注、启动状态、规则创建时间, 规则列表中的规则可以进行设置、删除、启用、禁用等操作。点击规则 ID 可以查看规则的详细信息。还可以在更多操作里，选择快速复制一个规则并修改，最大程度提升规则的复用性。
列表顶部包含有一个搜索栏，我们可以使用规则的 ID，接入数据的主题，是否启用和备注来进行多条件的规则查询，帮助用户快速找到符合条件的规则并进行查看和设置等。注意：规则 ID 和备注支持模糊查询，主题支持切换为使用通配符来搜索。

规则概览

在规则列表页面，点击规则 ID，可以快速进入规则的概览页面，规则概览页面包含了规则的基本数据统计包括：规则的运行时的统计，当前规则下动作的执行统计。例如规则的命中数，命中并通过的数量，规则的执行速率，失败数，执行动作成功和失败数等。点击右上角的 刷新 可以实时的查看当前规则的运行数据统计。

规则设置

点击操作栏设置，可以进入到规则的设置页面，规则设置页面包含了规则的基本信息，设置页面可以进行规则的修改和调试，与创建页面相同。例如需要修改当前规则下的执行动作，修改规则的备注，重新编辑 SQL 语句等。

【官网规则引擎】

管理

MQTT 配置

点击左侧配置菜单下的 MQTT，可以来到 MQTT 协议相关的配置页面。在 MQTT 配置页面中，我们可以配置 MQTT 协议相关的配置项。实践中没有什么特殊需要可以保留默认配置，不做更改。

监听器

点击左侧配置菜单下的监听器，可以来到监听器页面，该页面默认是一个监听器的列表页。EMQX 默认提供了四个常用的监听器：

• 使用 1883 端口的 TCP 类型监听器
• 使用 8883 端口的 SSL/TLS 安全连接类型监听器
• 使用 8083 端口的 WebSocket 类型监听器
• 使用 8084 端口的 WebSocket 安全类型监听器

正常我们使用以上默认的监听器，输入对应端口和协议类型即可。如果需要添加其他类型的监听器，可以点击右上角的添加监听器按钮，添加一个新的监听器。
在实践运营中主要使用1883 端口的 TCP 类型监听器，所以选择关闭其它监听器。

【需要了解更多EMQX更多的管理功能可以查阅官方文档】

系统设置

EMQX Dashboard 的系统菜单包括用户、API 密钥和设置子菜单。每个子菜单都允许您在其各自的页面上高效管理和配置用户帐户、API密钥和仪表板设置首选项。

用户

用户页面提供了所有活跃的 Dashboard 用户的概览，包括通过命令行生成的用户。
要添加新用户，只需点击页面右上角的创建按钮。一个弹出的对话框将提示您输入必要的用户详细信息。输入完毕后，点击创建按钮即可生成用户帐户。对于进一步的用户管理，如编辑用户信息、更新密码或删除用户，您可以通过操作列轻松访问这些选项。

API 密钥

点击左侧系统设置菜单下的 API 密钥，可以来到 API 密钥页面。如果需要 API 密钥来创建一些脚本调用 HTTP API，可以在此页面进行创建获取操作。点击页面右上角创建按钮打开创建 API 密钥弹框，填写 API 密钥相关数据，如果到期时间未填写 API 密钥将永不过期，点击确定提交数据，提交成功后页面上将提供此次创建的 API 密钥的 API Key 和 Secret Key，其中 Secret Key 后续将不再显示，用户需立即将 API Key 和 Secret Key 保存至安全的地方；保存数据完毕可点击关闭按钮关闭弹框。
在 API 密钥页面上，您可以按照以下步骤生成用于访问 HTTP API 的 API 密钥和 Secret key。

• 单击页面右上角的创建按钮，弹出创建 API 密钥的对话框。

• 在创建 API 密钥对话框上，配置 API 密钥的详细信息。

    如果到期时间文本框留空，API 密钥将永不过期。
   您可以指定密钥的角色（可选，仅适用于企业版）。
  

• 单击确认按钮，API 密钥和密钥将被创建并显示在创建成功对话框中。

【注意：您需要将 API Key 和 Secret Key 保存在安全的地方，因为 Secret Key 将不再显示。】

其它

关注公众号【 java程序猿技术】获取EMQX实践系列文章