Share via

針對 IoT Edge 裝置進行疑難排解

  • 發行項

適用於：IoT Edge 1.5 複選標記 IoT Edge 1.5 IoT Edge 1.4 複選標記 IoT Edge 1.4

重要

支援 IoT Edge 1.5 LTS 和 IoT Edge 1.4 LTS 版本。 IoT Edge 1.4 LTS 於 2024 年 11 月 12 日結束生命週期。 如果您是舊版，請參閱更新 IoT Edge。

如果您在環境中執行 Azure IoT Edge 時遇到問題，請使用本文作為疑難解答和診斷指南。

執行 『check』 命令

針對IoT Edge進行疑難解答的第一個步驟應該是使用 check 命令，以針對常見問題執行組態和連線測試的集合。 命令check可在 1.0.7 版和更新版本中取得。

注意

疑難解答工具無法執行連線能力檢查 IoT Edge 裝置是否位於 Proxy 伺服器後方。

您可以執行 check 命令，如下所示，或包含 --help 旗標，以查看完整的選項清單：

sudo iotedge check

疑難解答工具會執行許多已排序成下列三個類別的檢查：

  • 設定檢查 會檢查可能導致IoT Edge裝置無法連線到雲端的詳細數據，包括組態檔和容器引擎的問題。
  • 連線 檢查會確認IoT Edge執行時間可以存取主機裝置上的埠，而且所有IoT Edge元件都可以連線到 IoT 中樞。 如果 IoT Edge 裝置位於 Proxy 後方，這組檢查會傳回錯誤。
  • 生產整備檢查 會尋找建議的生產最佳做法，例如裝置證書頒發機構單位 （CA） 憑證的狀態和模組記錄檔組態。

IoT Edge 檢查工具會使用容器來執行其診斷。 容器映像 mcr.microsoft.com/azureiotedge-diagnostics:latest可透過 Microsoft Container Registry 取得。 如果您需要在裝置上執行檢查，而不需要直接存取因特網，您的裝置將需要存取容器映像。

在使用巢狀 IoT Edge 裝置的案例中，您可以透過透過父裝置路由傳送映像來存取下游裝置上的診斷映像。

sudo iotedge check --diagnostics-image-name <parent_device_fqdn_or_ip>:<port_for_api_proxy_module>/azureiotedge-diagnostics:1.2

如需此工具所執行之每個診斷檢查的相關信息，包括當您收到錯誤或警告時要執行的動作，請參閱 IoT Edge 疑難解答檢查。

使用 'support-bundle' 命令收集偵錯資訊

當您需要從IoT Edge裝置收集記錄時，最方便的方式是使用 support-bundle 命令。 根據預設，此命令會收集模組、IoT Edge 安全性管理員和容器引擎記錄、 iotedge check JSON 輸出和其他有用的偵錯資訊。 它會將它們壓縮成單一檔案，以便輕鬆共用。 命令support-bundle可在 1.0.9 版和更新版本中取得。

使用旗標執行 support-bundle 命令， --since 以指定您想要取得記錄的過去時間長度。 例如 6h ，從過去六個小時起， 6d 自過去六天起， 6m 自過去六分鐘之後，就會取得記錄。 --help包含旗標，以查看完整的選項清單。

sudo iotedge support-bundle --since 6h

根據預設， support-bundle 命令會在呼叫命令的目錄中建立名為 support_bundle.zip 的 zip 檔案。 使用旗標 --output 來指定輸出的不同路徑或檔名。

如需命令的詳細資訊，請檢視其說明資訊。

iotedge support-bundle --help

您也可以使用內建直接方法呼叫 UploadSupportBundle，將 support-bundle 命令的輸出上傳至 Azure Blob 儲存體。

警告

命令的 support-bundle 輸出可以包含主機、裝置和模組名稱、模組記錄的資訊等等。在公用論壇中共享輸出時，請注意這一點。

檢閱從運行時間收集的計量

IoT Edge 運行時間模組會產生計量，以協助您監視及瞭解 IoT Edge 裝置的健康情況。 將 metrics-collector 模組新增至您的部署，以處理收集這些計量，並將其傳送至雲端以方便監視。

如需詳細資訊，請參閱 收集及傳輸計量。

檢查 IoT Edge 版本

如果您執行的是舊版 IoT Edge，升級可能會解決您的問題。 此工具 iotedge check 會檢查 IoT Edge 安全性精靈是否為最新版本，但不會檢查 IoT Edge 中樞和代理程式模組的版本。 若要檢查裝置上的執行時間模組版本，請使用 命令 iotedge logs edgeAgent 和 iotedge logs edgeHub。 模組啟動時，會在記錄中宣告版本號碼。

如需如何更新裝置的指示，請參閱 更新IoT Edge安全性精靈和運行時間。

確認在您的裝置上安裝IoT Edge

您可以監視 edgeAgent模組對應項，確認裝置上的IoT Edge安裝。

若要取得最新的 edgeAgent 模組對應項，請從 Azure Cloud Shell 執行下列命令：

az iot hub module-twin show --device-id <edge_device_id> --module-id '$edgeAgent' --hub-name <iot_hub_name>

此命令會輸出所有edgeAgent 報告的屬性。 以下是一些實用的監視裝置狀態：

  • 運行時間狀態
  • 運行時間開始時間
  • 運行時間上次結束時間
  • 運行時間重新啟動計數

檢查 IoT Edge 安全性管理員及其記錄的狀態

IoT Edge 安全性管理員負責在啟動時初始化IoT Edge系統及布建裝置等作業。 如果 IoT Edge 未啟動，安全性管理員記錄可能會提供有用的資訊。

  • 檢視 IoT Edge 系統服務的狀態：

    sudo iotedge system status

  • 檢視 IoT Edge 系統服務的記錄：

    sudo iotedge system logs -- -f

  • 啟用偵錯層級記錄，以檢視 IoT Edge 系統服務的更詳細記錄：

    1. 啟用偵錯層級記錄。

      sudo iotedge system set-log-level debug
sudo iotedge system restart

    2. 在偵錯之後切換回預設資訊層級記錄。

      sudo iotedge system set-log-level info
sudo iotedge system restart

檢查容器記錄中是否有問題

IoT Edge 安全性精靈執行之後，請查看容器的記錄來偵測問題。 從已部署的容器開始，然後查看組成 IoT Edge 運行時間的容器：edgeAgent 和 edgeHub。 IoT Edge 代理程式記錄通常會提供每個容器生命週期的相關信息。 IoT Edge 中樞記錄提供訊息和路由的資訊。

您可以從數個位置擷取容器記錄：

清除容器記錄

根據預設，Moby 容器引擎不會設定容器記錄大小限制。 經過一段時間，大量記錄可能會導致裝置填滿記錄，並用盡磁碟空間。 如果大型容器記錄會影響IoT Edge裝置效能，請使用下列命令來強制移除容器及其相關記錄。

如果您仍在進行疑難解答，請等到檢查容器記錄之後再執行此步驟。

警告

如果您在edgeHub容器有未傳遞的訊息待辦專案且未設定任何 主機記憶體 時強制移除edgeHub容器，則會遺失未傳遞的訊息。

docker rm --force <container name>

針對進行中的記錄維護和生產案例， 請設定預設記錄驅動程式。

檢視通過IoT Edge中樞的訊息

您可以檢視通過IoT Edge中樞的訊息，並從運行時間容器的詳細記錄收集深入解析。 若要在這些容器上開啟詳細信息記錄，請在部署指令清單中設定 RuntimeLogLevel 環境變數。

若要檢視通過IoT Edge 中樞的訊息，請將 RuntimeLogLevel edgeHub模組的環境變數 debug 設定為 。

edgeHub 和 edgeAgent 模組都有此執行時間記錄環境變數，預設值設定為 info。 此環境變數可以採用下列值：

  • 致命
  • error
  • warning
  • 資訊
  • 偵錯
  • verbose

您也可以檢查 IoT 中樞 與 IoT 裝置之間正在傳送的訊息。 使用適用於 Visual Studio Code 的 Azure IoT 中樞 擴充功能來檢視這些訊息。 如需詳細資訊，請參閱 使用 Azure IoT 進行開發時方便的工具。

重新啟動容器

調查記錄和訊息以取得信息之後，您可以嘗試重新啟動容器。

在 IoT Edge 裝置上，使用下列命令來重新啟動模組：

iotedge restart <container name>

重新啟動 IoT Edge 執行時間容器：

iotedge restart edgeAgent && iotedge restart edgeHub

您也可以從 Azure 入口網站遠端重新啟動模組。 如需詳細資訊，請參閱從 Azure 入口網站監視 IoT Edge 裝置並進行疑難排解。

檢查防火牆和埠設定規則

Azure IoT Edge 允許使用支援的 IoT 中樞 通訊協定從內部部署伺服器到 Azure 雲端的通訊，請參閱選擇通訊協定。 為了增強安全性，Azure IoT Edge 與 Azure IoT 中樞 之間的通道一律會設定為輸出。 此設定是以服務輔助通訊模式為基礎，可將惡意實體探索的攻擊面降到最低。 只有在 Azure IoT 中樞 必須將訊息推送至 Azure IoT Edge 裝置的特定案例中，才需要輸入通訊。 雲端到裝置訊息會使用安全的 TLS 通道來保護，而且可以使用 X.509 憑證和 TPM 裝置模組進一步保護。 Azure IoT Edge 安全性管理員會控管如何建立此通訊，請參閱 IoT Edge 安全性管理員。

雖然 IoT Edge 提供增強的設定來保護 Azure IoT Edge 運行時間和已部署的模組，但仍相依於基礎機器和網路組態。 因此，請務必確保已設定適當的網路和防火牆規則，以便安全邊緣到雲端通訊。 下表可作為裝載 Azure IoT Edge 運行時間之基礎伺服器的設定防火牆規則時的指導方針：

通訊協定 連接埠 連入 連出 指引
MQTT 8883 BLOCKED （預設值） BLOCKED （預設值）
  • 使用 MQTT 作為通訊協定時，將傳出 （輸出） 設定為 Open。
  • IoT Edge 不支援 MQTT 的 1883。
  • 應封鎖連入 （輸入） 連線。
AMQP 5671 BLOCKED （預設值） OPEN （預設值）
  • IoT Edge 的預設通訊協定。
  • 如果未針對其他支持的通訊協定設定 Azure IoT Edge，或 AMQP 是所需的通訊協定，則必須設定為 Open。
  • IoT Edge 不支援適用於AMQP的5672。
  • 當 Azure IoT Edge 使用不同的 IoT 中樞 支援的通訊協定時，請封鎖此埠。
  • 應封鎖連入 （輸入） 連線。
HTTPS 443 BLOCKED （預設值） OPEN （預設值）
  • 將傳出 （輸出） 設定為在 443 上開啟以進行 IoT Edge 布建。 使用手動腳本或 Azure IoT 裝置佈建服務 （DPS） 時，需要此設定。
  • 傳入 （輸入） 連線 應該只在特定案例中開啟：
    • 如果您有具有可傳送方法要求的下游裝置的透明網關。 在此情況下，埠 443 不需要向外部網路開放，即可連線到 IoTHub 或透過 Azure IoT Edge 提供 IoTHub 服務。 因此，傳入規則只能從內部網路開啟傳入（輸入）。
    • 針對客戶端到裝置 （C2D） 案例。
  • IoT Edge 不支援 80 for HTTP。
  • 如果企業中無法設定非 HTTP 通訊協定（例如 AMQP 或 MQTT），訊息可以透過 WebSocket 傳送。 在此情況下，埠 443 將用於 WebSocket 通訊。

最後手段：停止並重新建立所有容器

有時候，系統可能需要進行顯著的特殊修改，才能使用現有的網路或操作系統條件約束。 例如，系統可能需要不同的數據磁碟掛接和 Proxy 設定。 如果您嘗試了所有先前的步驟，但仍發生容器失敗，Docker 系統快取或保存的網路設定可能無法使用最新的重新設定。 在此情況下，最後一個手段選項是使用 docker prune 從頭開始取得乾淨開始。

下列命令會停止IoT Edge系統（因此所有容器），使用 「all」 和 「volume」 選項 docker prune 來移除所有容器和磁碟區。 檢閱命令在就緒時發出並確認的 y 警告。

sudo iotedge system stop
docker system prune --all --volumes

WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all volumes not used by at least one container
  - all images without at least one container associated to them
  - all build cache

Are you sure you want to continue? [y/N]

再次啟動系統。 若要安全，請套用任何可能剩餘的組態，並使用一個命令啟動系統。

sudo iotedge config apply

請稍候幾分鐘，然後再檢查一次。

sudo iotedge list

下一步

您認為您在 IoT Edge 平台中發現錯誤嗎？ 提交問題 ，以便我們可以繼續改善。

如果您有更多問題，請建立 支援要求 以取得協助。