本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# MQTT 5 代理（EMQX）
<a name="mqtt-broker-emqx-component"></a>

EMQX MQTT 代理组件 (`aws.greengrass.clientdevices.mqtt.EMQX`) 处理客户端设备与 Greengrass 核心设备之间的 MQTT 消息。此组件提供 [EMQX MQTT 5.0 代理](https://www.emqx.com/en/mqtt/mqtt5)的修改版本。部署此 MQTT 代理，以便在客户端设备与核心设备的通信中使用 MQTT 5 功能。有关如何选择 MQTT 代理的更多信息，请参阅[选择 MQTT 代理](choose-local-mqtt-broker.md)。

此代理实施 MQTT 5.0 协议。它支持会话和消息过期间隔、用户属性、共享订阅、主题别名等功能。MQTT 5 向后兼容 MQTT 3.1.1，因此，如果您运行 [Moquette MQTT 3.1.1 代理](mqtt-broker-moquette-component.md)，您可以将其替换为 EMQX MQTT 5 代理，并且客户端设备可以继续照常连接和运行。

<a name="note-local-mqtt-broker-mqtt-5-features"></a>

**注意**  <a name="client-device-component-context"></a>
客户端设备是本地 IoT 设备，连接到 Greengrass 核心设备以发送 MQTT 消息和数据进行处理。有关更多信息，请参阅 [与本地 IoT 设备交互](interact-with-local-iot-devices.md)。

**Topics**
+ [版本](#mqtt-broker-emqx-component-versions)
+ [Type](#mqtt-broker-emqx-component-type)
+ [操作系统](#mqtt-broker-emqx-component-os-support)
+ [要求](#mqtt-broker-emqx-component-requirements)
+ [依赖项](#mqtt-broker-emqx-component-dependencies)
+ [配置](#mqtt-broker-emqx-component-configuration)
+ [本地日志文件](#mqtt-broker-emqx-component-log-file)
+ [许可证](#mqtt-broker-emqx-component-licenses)
+ [更改日志](#mqtt-broker-emqx-component-changelog)

## 版本
<a name="mqtt-broker-emqx-component-versions"></a>

此组件具有以下版本：
+ 2.0.x
+ 1.2.x
+ 1.1.x
+ 1.0.x

## Type
<a name="mqtt-broker-emqx-component-type"></a>

<a name="public-component-type-generic"></a>此<a name="public-component-type-generic-phrase"></a>组件是一个通用组件 (`aws.greengrass.generic`)。[Greengrass Nucleus](greengrass-nucleus-component.md) 运行组件的生命周期脚本。

<a name="public-component-type-more-information"></a>有关更多信息，请参阅[组件类型](develop-greengrass-components.md#component-types)。

## 操作系统
<a name="mqtt-broker-emqx-component-os-support"></a>

此组件可以安装在运行以下操作系统的核心设备上：
+ Linux
+ Windows

## 要求
<a name="mqtt-broker-emqx-component-requirements"></a>

此组件具有以下要求：
+ 核心设备必须能够接受 MQTT 代理运行端口的连接。默认情况下，此组件在端口 8883 运行 MQTT 代理。配置此组件时，您可以指定其他端口。

  <a name="mqtt-broker-configuration-mqtt-bridge-requirement"></a>如果您指定其它端口，并且使用 [MQTT 网桥组件](mqtt-bridge-component.md)将 MQTT 消息中继到其它代理，您必须使用 MQTT 网桥 v2.1.0 或更高版本。将其配置为使用 MQTT 代理运行的端口。

  <a name="mqtt-broker-configuration-ip-detector-requirement"></a>如果您指定其它端口，并使用 [IP 检测器组件](ip-detector-component.md)管理 MQTT 代理端点，则必须使用 IP 检测器 v2.1.0 或更高版本。将其配置为报告 MQTT 代理运行的端口。
+ 在 Linux 核心设备上，在核心设备上安装并配置 Docker：
  + <a name="docker-engine-requirement"></a>Greengrass 核心设备上安装的 [Docker Engine](https://docs.docker.com/engine/) 1.9.1 或更高版本。版本 20.10 是经验证可与 AWS IoT Greengrass 核心软件配合使用的最新版本。在部署运行 Docker 容器的组件之前，必须直接在核心设备上安装 Docker。
  + <a name="docker-daemon-requirement"></a>在部署此组件之前，Docker 进程守护程序已启动并在核心设备上运行。
  + 运行此组件的系统用户必须具有根权限或管理员权限。或者，您可以以 `docker` 组中系统用户的身份运行此组件，并将此组件的 `requiresPrivileges` 选项配置为 `false`，以在没有权限的情况下运行 EQMX MQTT 代理。
+ 支持在 VPC 中运行 EMQX MQTT 网桥组件。
+ `armv7` 平台不支持 EMQX MQTT 代理组件。

## 依赖项
<a name="mqtt-broker-emqx-component-dependencies"></a>

部署组件时， AWS IoT Greengrass 还会部署其依赖项的兼容版本。这意味着您必须满足组件及其所有依赖关系的要求，才能成功部署组件。本部分列出了此组件的[已发布版本](#mqtt-broker-emqx-component-changelog)的依赖关系，以及定义每个依赖关系的组件版本的语义版本约束。您还可以在 [AWS IoT Greengrass 控制台](https://console.aws.amazon.com//greengrass)中查看每个组件版本的依赖关系。在组件详细信息页面上，查找**依赖关系**列表。

------
#### [ 2.0.2 – 2.0.3 ]

下表列出了此组件版本 2.0.2 和 2.0.3 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [客户端设备身份验证](client-device-auth-component.md) | >=2.2.0 <2.6.0 | 软性 | 

------
#### [ 2.0.1 ]

下表列出了此组件的版本 2.0.1 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [客户端设备身份验证](client-device-auth-component.md) | >=2.2.0 <2.6.0 | 硬性 | 

------
#### [ 2.0.0 ]

下表列出了此组件版本 2.0.0 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [客户端设备身份验证](client-device-auth-component.md) | >=2.2.0 <2.5.0 | 硬性 | 

------
#### [ 1.2.2 – 1.2.3 ]

下表列出了此组件的版本 1.2.2 至 1.2.3 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [客户端设备身份验证](client-device-auth-component.md) | >=2.2.0 <2.5.0 | 硬性 | 

------
#### [ 1.2.0 and 1.2.1 ]

下表列出了此组件的版本 1.2.0 和 1.2.1 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [客户端设备身份验证](client-device-auth-component.md) | >=2.2.0 <2.4.0 | 硬性 | 

------
#### [ 1.0.0 and 1.1.0 ]

下表列出了此组件的版本 1.0.0 和 1.1.0 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [客户端设备身份验证](client-device-auth-component.md) | >=2.2.0 <2.3.0 | 硬性 | 

------

有关组件依赖关系的更多信息，请参阅[组件配方参考](component-recipe-reference.md#recipe-reference-component-dependencies)。

## 配置
<a name="mqtt-broker-emqx-component-configuration"></a>

------
#### [ 2.0.0 - 2.0.3 ]

此组件提供您可以在部署组件时自定义的以下配置参数。

**重要**  
如果您使用版本 2 的 MQTT 5 代理（EMQX）组件，则必须更新您的配置文件。版本 1 配置文件不适用于版本 2。

emqxConfig  
 （可选）要使用的 [EMQX MQTT 代理](https://www.emqx.io/docs/en/v5.1/configuration/configuration.html)配置。您可以在此组件中设置 EMQX 配置选项。  
当您使用 EMQX 代理时，Greengrass 使用默认配置。除非您使用此字段对其进行修改，否则将使用此配置。  
修改以下配置设置会导致 EMQX 代理组件重新启动。其它配置更改无需重新启动组件即可生效。  
+ `emqxConfig/cluster`
+ `emqxConfig/node`
+ `emqxConfig/rpc`
`aws.greengrass.clientdevices.mqtt.EMQX` 允许您配置对安全敏感的选项。这些包括 TLS 设置、身份验证和授权提供程序。我们推荐默认配置，使用双向 TLS 身份验证和 Greengrass 客户端设备身份验证提供程序。

**Example 示例：默认配置**  
以下示例显示为 MQTT 5（EMQX）代理设置的默认值。您可以使用 `emqxConfig` 配置设置覆盖这些设置。  

```
{
  "authorization": {
    "no_match": "deny",
    "sources": []
  },
  "node": {
    "cookie": "<placeholder>"
  }, 
  "listeners": {
     "ssl": {
       "default": {
         "ssl_options": {
           "keyfile": "{work:path}\\data\\key.pem",
           "certfile": "{work:path}\\data\\cert.pem",
           "cacertfile": null,
           "verify": "verify_peer",
           "versions": ["tlsv1.3", "tlsv1.2"],
           "fail_if_no_peer_cert": true
         }
       }
     },
     "tcp": {
       "default": {
         "enabled": false
       }
     },
     "ws": {
       "default": {
         "enabled": false
       }
     },
     "wss": {
       "default": {
         "enabled": false
       }
     }
  },
  "plugins": {
    "states": [{"name_vsn": "gg-1.0.0", "enable": true}],
    "install_dir": "plugins"
  }
}
```

authMode  
（可选）为代理设置授权提供程序。可以是以下任一值：  
+ `enabled` –（默认）使用 Greengrass 身份验证和授权提供程序。
+ `bypass_on_failure` – 使用 Greengrass 身份验证提供程序，如果 Greengrass 拒绝身份验证或授权，则使用 EMQX 提供程序链中剩余的任何身份验证提供程序。
+ `bypass` – 禁用 Greengrass 提供程序。身份验证和授权由 EMQX 提供程序链处理。

`requiresPrivilege`  
（可选）在 Linux 核心设备上，您可以指定在没有根权限或管理员权限的情况下运行 EMQX MQTT 代理。如果将此选项设置为 `false`，则运行此组件的系统用户必须是 `docker` 组的成员。  
默认值：`true`

`startupTimeoutSeconds`  
（可选）EMQX MQTT 代理启动的最长时间（以秒为单位）。如果时间超过此超时时间，则组件的状态将更改为 `BROKEN`。  
默认值：`90`

`ipcTimeoutSeconds`  
（可选）组件等待 Greengrass Nucleus 响应进程间通信（IPC）请求的最长时间（以秒为单位）。如果此组件在检查客户端设备是否获得授权时报告超时错误，请增加此数字。  
默认值：`5`

`crtLogLevel`  
（可选） AWS 公共运行时 (CRT) 库的日志级别。  
默认为 EMQX MQTT 代理日志级别（`emqx` 中的 `log.level`）。

`restartIdentifier`  
（可选）配置此选项可重新启动 EMQX MQTT 代理。当此配置值更改时，此组件会重新启动 MQTT 代理。您可以使用此选项强制客户端设备断开连接。

`dockerOptions`  
（可选）仅在 Linux 操作系统上配置此选项，以便向 Docker 命令行添加参数。例如，要映射其它端口，请使用 `-p` Docker 参数：  

```
"-p 1883:1883"
```

**Example 示例：将 v1.x 配置文件更新为 v2.x**  
以下示例显示了将 v1.x 配置文件更新到 2.x 版本所需的更改。  
版本 1.x 配置文件：  

```
{
    "emqx": {
        "listener.ssl.external": "443",
        "listener.ssl.external.max_connections": "1024000",
        "listener.ssl.external.max_conn_rate": "500",
        "listener.ssl.external.rate_limit": "50KB,5s",
        "listener.ssl.external.handshake_timeout": "15s",
        "log.level": "warning"
    },
    "mergeConfigurationFiles": {
        "etc/plugins/aws_greengrass_emqx_auth.conf": "auth_mode=enabled\n use_greengrass_managed_certificates=true\n"
    }
}
```
v2 的等效配置文件：  

```
{
    "emqxConfig": {
        "listeners": {
            "ssl": {
                "default": {
                   "bind": "8883",
                   "max_connections": "1024000",
                   "max_conn_rate": "500",
                   "ssl_options": {
                        "handshake_timeout": "15s"
                   }
                }
            }
        },
        "log": {
            "console": {
              "enable": true,
              "level": "warning"
            }
        }
    },
    "authMode": "enabled"
}
```
没有与 `listener.ssl.external.rate_limit` 配置条目对应的内容。已删除 `use_greengrass_managed_certificates` 配置选项。

**Example 示例：为代理设置新端口**  
以下示例将 MQTT 代理运行的端口从默认的 8883 更改为端口 1234。如果您使用的是 Linux，请包含 `dockerOptions` 字段。  

```
{
  "emqxConfig": {
    "listeners": {
      "ssl": {
        "default": {
          "bind": 1234
        }
      }
    }
  },
  "dockerOptions": "-p 1234:1234"
}
```

**Example 示例：调整 MQTT 代理的日志级别**  
以下示例将 MQTT 代理的日志级别更改为 `debug`。您可从以下日志级别中进行选择：  
+ `debug`
+ `info`
+ `notice`
+ `warning`
+ `error`
+ `critical`
+ `alert`
+ `emergency`
默认日志级别为 `warning`。  

```
{
  "emqxConfig": {
    "log": {
      "console": {
         "level": "debug"
      }
    }
  }
}
```

**Example 示例：启用 EMQX 控制面板**  
以下示例启用 EMQX 控制面板，以便您可以监控和管理您的代理。如果您使用的是 Linux，请包含 `dockerOptions` 字段。  

```
{
  "emqxConfig": {
    "dashboard": {
      "listeners": {
        "http": {
          "bind": 18083
        }
      }
    }
  },
  "dockerOptions": "-p 18083:18083"
}
```

------
#### [ 1.0.0 - 1.2.2 ]

此组件提供您可以在部署组件时自定义的以下配置参数。

`emqx`  
（可选）要使用的 [EMQX MQTT 代理](https://www.emqx.io/docs/en/v4.4/configuration/configuration.html)配置。您可以在此组件中配置 EMQX 配置选项的子集。  
该对象包含以下信息：    
`listener.ssl.external`  
（可选）MQTT 代理运行的端口。  
<a name="mqtt-broker-configuration-mqtt-bridge-requirement"></a>如果您指定其它端口，并且使用 [MQTT 网桥组件](mqtt-bridge-component.md)将 MQTT 消息中继到其它代理，您必须使用 MQTT 网桥 v2.1.0 或更高版本。将其配置为使用 MQTT 代理运行的端口。  
<a name="mqtt-broker-configuration-ip-detector-requirement"></a>如果您指定其它端口，并使用 [IP 检测器组件](ip-detector-component.md)管理 MQTT 代理端点，则必须使用 IP 检测器 v2.1.0 或更高版本。将其配置为报告 MQTT 代理运行的端口。
默认值：`8883`  
`listener.ssl.external.max_connections`  
（可选）MQTT 代理支持的最大并行连接数。  
默认值：`1024000`  
`listener.ssl.external.max_conn_rate`  
（可选）MQTT 代理每秒可以接收的最大新连接数。  
默认值：`500`  
`listener.ssl.external.rate_limit`  
（可选）与 MQTT 代理的所有连接的带宽限制。按以下格式指定带宽及其持续时间，用逗号 (`,`) 分隔：`bandwidth,duration`。例如，您可以指定 `50KB,5s` 将 MQTT 代理限制为每 5 秒 50 千字节（KB）的数据。  
`listener.ssl.external.handshake_timeout`  
（可选）MQTT 代理等待完成对新连接的身份验证的时长。  
默认值：`15s`  
`mqtt.max_packet_size`  
（可选）MQTT 消息的最大大小。  
默认值：`268435455`（256MB 减去 1）  
`log.level`  
（可选）MQTT 代理的日志级别。从以下选项中进行选择：  
+ `debug`
+ `info`
+ `notice`
+ `warning`
+ `error`
+ `critical`
+ `alert`
+ `emergency`
默认日志级别为 `warning`。

`requiresPrivilege`  
（可选）在 Linux 核心设备上，您可以指定在没有根权限或管理员权限的情况下运行 EMQX MQTT 代理。如果将此选项设置为 `false`，则运行此组件的系统用户必须是 `docker` 组的成员。  
默认值：`true`

`startupTimeoutSeconds`  
（可选）EMQX MQTT 代理启动的最长时间（以秒为单位）。如果时间超过此超时时间，则组件的状态将更改为 `BROKEN`。  
默认值：`90`

`ipcTimeoutSeconds`  
（可选）组件等待 Greengrass Nucleus 响应进程间通信（IPC）请求的最长时间（以秒为单位）。如果此组件在检查客户端设备是否获得授权时报告超时错误，请增加此数字。  
默认值：`5`

`crtLogLevel`  
（可选） AWS 公共运行时 (CRT) 库的日志级别。  
默认为 EMQX MQTT 代理日志级别（`emqx` 中的 `log.level`）。

`restartIdentifier`  
（可选）配置此选项可重新启动 EMQX MQTT 代理。当此配置值更改时，此组件会重新启动 MQTT 代理。您可以使用此选项强制客户端设备断开连接。

`dockerOptions`  
（可选）仅在 Linux 操作系统上配置此选项，以便向 Docker 命令行添加参数。例如，要映射其它端口，请使用 `-p` Docker 参数：  

```
"-p 1883:1883"
```

`mergeConfigurationFiles`  
（可选）配置此选项可添加或覆盖指定 EMQX 配置文件中的默认值。有关配置文件及其格式的信息，请参阅 *EMQX 4.0* 文档中的[配置](https://www.emqx.io/docs/en/v4.4/configuration/configuration.html)。您指定的值将附加到配置文件中。  
以下示例将更新 `etc/emqx.conf` 文件。  

```
"mergeConfigurationFiles": {
    "etc/emqx.conf": "broker.sys_interval=30s\nbroker.sys_heartbeat=10s"
},
```
除 EMQX 支持的配置文件外，Greengrass 还支持一个文件，为 EMQX 配置 Greengrass 身份验证插件，名为 `etc/plugins/aws_greengrass_emqx_auth.conf`。有两个支持的选项，即 `auth_mode` 和 `use_greengrass_managed_certificates`。要使用其它身份验证提供程序，请将 `auth_mode` 选项设置为以下选项之一：  
+ `enabled` –（默认）使用 Greengrass 身份验证和授权提供程序。
+ `bypass_on_failure` – 使用 Greengrass 身份验证提供程序，如果 Greengrass 拒绝身份验证或授权，则使用 EMQX 提供程序链中剩余的任何身份验证提供程序。
+ `bypass` – 禁用 Greengrass 提供程序。然后，身份验证和授权由 EMQX 提供程序链处理。
如果 `use_greengrass_managed_certificates` 为 `true`，则此选项表示 Greengrass 管理代理 TLS 证书。如果为 `false`，则表示您通过其它来源提供证书。  
以下示例更新了 `etc/plugins/aws_greengrass_emqx_auth.conf` 配置文件中的默认值。  

```
"mergeConfigurationFiles": {
    "etc/plugins/aws_greengrass_emqx_auth.conf": "auth_mode=enabled\n use_greengrass_managed_certificates=true\n"
  },
```
`aws.greengrass.clientdevices.mqtt.EMQX` 允许您配置对安全敏感的选项。这些包括 TLS 设置、身份验证和授权提供程序。推荐的配置是默认配置，使用双向 TLS 身份验证和 Greengrass 客户端设备身份验证提供程序。

`replaceConfigurationFiles`  
（可选）配置此选项可替换指定的 EMQX 配置文件。您指定的值替换整个现有配置文件。您无法在此部分中指定 `etc/emqx.conf` 文件。您必须使用 `mergeConfigurationFile` 才能修改 `etc/emqx.conf`。

**Example 示例：配置合并更新**  
以下示例配置指定在端口 443 运行 MQTT 代理。  

```
{
  "emqx": {
    "listener.ssl.external": "443",
    "listener.ssl.external.max_connections": "1024000",
    "listener.ssl.external.max_conn_rate": "500",
    "listener.ssl.external.rate_limit": "50KB,5s",
    "listener.ssl.external.handshake_timeout": "15s",
    "log.level": "warning"
  },
  "requiresPrivilege": "true",
  "startupTimeoutSeconds": "90",
  "ipcTimeoutSeconds": "5"
}
```

------

## 本地日志文件
<a name="mqtt-broker-emqx-component-log-file"></a>

此组件使用以下日志文件。

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.greengrass.clientdevices.mqtt.EMQX.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.greengrass.clientdevices.mqtt.EMQX.log
```

------

**查看此组件的日志**
+ 在核心设备上运行以下命令可实时查看此组件的日志文件。将`/greengrass/v2`或*C:\$1greengrass\$1v2*替换为 AWS IoT Greengrass 根文件夹的路径。

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.clientdevices.mqtt.EMQX.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.greengrass.clientdevices.mqtt.EMQX.log -Tail 10 -Wait
  ```

------

## 许可证
<a name="mqtt-broker-emqx-component-licenses"></a>

在 Windows 操作系统上，该软件包括根据 [Microsoft 软件许可条款 – Microsoft Visual Studio Community 2022](https://visualstudio.microsoft.com/license-terms/vs2022-ga-community) 分发的代码。下载此软件，即表示您同意该代码的许可条款。

<a name="component-core-software-license"></a>此组件在 [Greengrass Core 软件许可协议](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)下发行。

## 更改日志
<a name="mqtt-broker-emqx-component-changelog"></a>

下表介绍每个组件版本的更改。

------
#### [ v2.x ]


|  **版本**  |  **更改**  | 
| --- | --- | 
|  2.0.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/mqtt-broker-emqx-component.html)  | 
|  2.0.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/mqtt-broker-emqx-component.html)  | 
|  2.0.1  |  对[客户端设备身份验证](client-device-auth-component.md)版本 2.5.0 发行版进行了版本更新。  | 
| 2.0.0 | 此版本的 MQTT 5 代理（EMQX）需要的配置参数与版本 1.x 不同。如果您为版本 1.x 使用非默认配置，您必须为 2.x 更新组件的配置。有关更多信息，请参阅 [配置](#mqtt-broker-emqx-component-configuration)。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/mqtt-broker-emqx-component.html) | 

------
#### [ v1.x ]


|  **版本**  |  **更改**  | 
| --- | --- | 
|  1.2.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/mqtt-broker-emqx-component.html)  | 
|  1.2.2  |  对[客户端设备身份验证](client-device-auth-component.md)版本 2.4.0 发行版进行了版本更新。  | 
|  1.2.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/mqtt-broker-emqx-component.html)  | 
|  1.2.0  |  添加了对证书链的支持。  | 
|  1.1.0  | <a name="changelog-emqx-1.1.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/mqtt-broker-emqx-component.html) | 
|  1.0.1  |  修复了在 TLS 握手期间导致某些 MQTT 客户端无法连接的问题。  | 
|  1.0.0  |  初始版本。  | 

------