本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # MQTT 5 代理程式 (EMQX) 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 代理程式，而且用戶端裝置可以繼續照常連線和操作。 **注意** 用戶端裝置是連線至 Greengrass 核心裝置的本機 IoT 裝置，用於傳送 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) + [Configuration](#mqtt-broker-emqx-component-configuration) + [本機日誌檔案](#mqtt-broker-emqx-component-log-file) + [授權](#mqtt-broker-emqx-component-licenses) + [變更記錄](#mqtt-broker-emqx-component-changelog) ## 版本此元件具有下列版本： + 2.0.x + 1.2.x + 1.1.x + 1.0.x ## Type 此元件是一般元件 (`aws.greengrass.generic`)。[Greengrass 核](greengrass-nucleus-component.md)會執行元件的生命週期指令碼。如需詳細資訊，請參閱[元件類型](develop-greengrass-components.md#component-types)。 ## 作業系統此元件可以安裝在執行下列作業系統的核心裝置上： + Linux + Windows ## 要求此元件有下列需求： + 核心裝置必須能夠在 MQTT 中介裝置操作的連接埠上接受連線。此元件預設會在連接埠 8883 上執行 MQTT 代理程式。您可以在設定此元件時指定不同的連接埠。如果您指定不同的連接埠，並使用 [MQTT 橋接器元件](mqtt-bridge-component.md)將 MQTT 訊息轉送至其他代理程式，則必須使用 MQTT 橋接器 v2.1.0 或更新版本。將其設定為使用 MQTT 代理程式操作所在的連接埠。如果您指定不同的連接埠，並使用 [IP 偵測器元件](ip-detector-component.md)來管理 MQTT 代理程式端點，則必須使用 IP 偵測器 v2.1.0 或更新版本。將其設定為報告 MQTT 中介裝置操作所在的連接埠。 + 在 Linux 核心裝置上，Docker 已安裝並設定在核心裝置上： + [Docker 引擎](https://docs.docker.com/engine/) 1.9.1 或更新版本安裝在 Greengrass 核心裝置上。20.10 版是經過驗證可與 AWS IoT Greengrass Core 軟體搭配使用的最新版本。您必須先直接在核心裝置上安裝 Docker，才能部署執行 Docker 容器的元件。 + 在部署此元件之前，Docker 協助程式會在核心裝置上啟動和執行。 + 執行此元件的系統使用者必須具有根或管理員許可。或者，您可以在 `docker`群組中以系統使用者身分執行此元件，並將此元件`requiresPrivileges`的選項設定為 `false`，以在沒有權限的情況下執行 EQMX MQTT 代理程式。 + EMQX MQTT 代理程式元件支援在 VPC 中執行。 + `armv7` 平台不支援 EMQX MQTT 代理程式元件。 ## 相依性當您部署元件時， 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)。 ## Configuration ------ #### [ 2.0.0 - 2.0.3 ] 此元件提供下列組態參數，您可以在部署元件時自訂這些參數。 **重要** 如果您使用 MQTT 5 代理程式 (EMQX) 元件的第 2 版，則必須更新組態檔案。第 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": "" }, "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 核回應程序間通訊 (IPC) 請求的秒數上限。如果此元件在檢查用戶端裝置是否獲得授權時回報逾時錯誤，請增加此數字。預設：`5` `crtLogLevel` （選用） AWS 一般執行期 (CRT) 程式庫的日誌層級。預設為 EMQX MQTT 代理程式日誌層級 (`log.level` 中的 `emqx`)。 `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 中介裝置操作所在的連接埠。如果您指定不同的連接埠，並使用 [MQTT 橋接器元件](mqtt-bridge-component.md)將 MQTT 訊息轉送給其他代理程式，則必須使用 MQTT 橋接器 v2.1.0 或更新版本。將其設定為使用 MQTT 代理程式操作所在的連接埠。如果您指定不同的連接埠，並使用 [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 (KB) 的資料。 `listener.ssl.external.handshake_timeout` （選用） MQTT 代理程式等待完成驗證新連線的時間長度。預設：`15s` `mqtt.max_packet_size` （選用） MQTT 訊息的大小上限。預設：`268435455`(256 MB 減去 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 核回應程序間通訊 (IPC) 請求的秒數上限。如果此元件在檢查用戶端裝置是否獲得授權時回報逾時錯誤，請增加此數字。預設：`5` `crtLogLevel` （選用） AWS 一般執行期 (CRT) 程式庫的日誌層級。預設為 EMQX MQTT 代理程式日誌層級 (`log.level` 中的 `emqx`)。 `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" } ``` ------ ## 本機日誌檔案此元件使用以下日誌檔案。 ------ #### [ 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 ``` ------ ## 授權在 Windows 作業系統上，本軟體包含根據 [Microsoft 軟體授權條款 - Microsoft Visual Studio Community 2022 ](https://visualstudio.microsoft.com/license-terms/vs2022-ga-community)分佈的程式碼。下載本軟體即表示您同意該程式碼的授權條款。此元件根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。 ## 變更記錄下表說明每個版本元件的變更。 ------ #### [ v2.x ] | **版本** | **變更** | | --- | --- | | 2.0.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/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 的元件組態。如需詳細資訊，請參閱[Configuration](#mqtt-broker-emqx-component-configuration)。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/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_tw/greengrass/v2/developerguide/mqtt-broker-emqx-component.html) | | 1.2.0 | 新增憑證鏈的支援。 | | 1.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/mqtt-broker-emqx-component.html) | | 1.0.1 | 修正 TLS 交握期間導致某些 MQTT 用戶端無法連線的問題。 | | 1.0.0 | 初始版本。 | ------