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

  • 發行項

適用于： IoT Edge 1.4 checkmark IoT Edge 1.4

重要

支援的版本是 IoT Edge 1.4。 如果您是舊版，請參閱更新 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
  • info
  • 偵錯
  • 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 執行時間之基礎伺服器的設定防火牆規則時的指導方針：

通訊協定 Port 傳入 傳出 指引
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 平臺中發現錯誤嗎？ 提交問題 ，以便我們可以繼續改善。

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