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

發行項
06/13/2024

適用於： IoT Edge 1.5 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 版和更新版本中使用。

搭配 --since 旗標執行 support-bundle 命令，以指定您想要取得多久以前的記錄。例如 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 中樞記錄會提供傳訊和路由的相關資訊。

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

在 IoT Edge 裝置上，執行下列命令來檢視記錄：
```
iotedge logs <container name>
```
在 Azure 入口網站上，使用內建疑難排解工具。從 Azure 入口網站監視 IoT Edge 裝置並進行疑難排解
使用 UploadModuleLogs 直接方法，將模組的記錄上傳至 Azure Blob 儲存體。

清除容器記錄

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

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

警告

如果您強制移除 edgeHub 容器時，其中有待處理的未傳遞訊息，且未設定任何主機儲存體，則未傳遞的訊息會遺失。

docker rm --force <container name>

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

檢視通過 IoT Edge 中樞的訊息

您可以檢視通過 IoT Edge 中樞的訊息，以及透過執行階段容器的詳細記錄來收集見解。若要開啟這些容器上的詳細記錄，請在部署資訊清單中設定 RuntimeLogLevel 環境變數。

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

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

fatal
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 執行階段和已部署的模組，但其仍然倚賴基礎的機器和網路設定。因此，請務必確保設定適當的網路和防火牆規則，以提供安全的「Edge 到雲端」通訊。為裝載 Azure IoT Edge 執行階段的基礎伺服器設定防火牆規則時，可以使用下表作為指導方針：

通訊協定	Port	傳入	傳出	指引
MQTT	8883	已封鎖 (預設值)	已封鎖 (預設值)	使用 MQTT 作為通訊協定時，請將「傳出」(輸出) 設定為「開放」。 IoT Edge 不支援適用於 MQTT 的 1883。應該將傳入 (輸入) 連線封鎖。
AMQP	5671	已封鎖 (預設值)	開放 (預設值)	IoT Edge 的預設通訊協定。如果未設定 Azure IoT Edge 使用其他支援的通訊協定，或 AMQP 是所需的通訊協定，則必須設定為「開放」。 IoT Edge 不支援適用於 AMQP 的 5672。當 Azure IoT Edge 使用不同的 IoT Hub 已支援通訊協定時，請封鎖此連接埠。應該將傳入 (輸入) 連線封鎖。
HTTPS	443	已封鎖 (預設值)	開放 (預設值)	設定連出 (輸出) 在 443 上開啟以進行 IoT Edge 佈建。使用手動指令碼或 Azure IoT 裝置佈建服務 (DPS) 時，就需要此設定。傳入 (輸入) 連線應該只有針對特定案例才設定為「開放」：假設您具有透明的閘道，其中具有可能會傳送方法要求的下游裝置。在此情況下，無須對外部網路開放連接埠 443，即可連線至 IoTHub 或透過 Azure IoT Edge 提供 IoTHub 服務。因此，可將傳入規則限制成只從內部網路開放「傳入」(輸入)。針對「用戶端到裝置」(C2D) 案例。 IoT Edge 不支援適用於 HTTP 的 80。如果無法在企業中設定非 HTTP 通訊協定 (例如 AMQP 或 MQTT)；則可透過 WebSocket 傳送訊息。在此情況下，埠 443 會用於 WebSocket 通訊。

最後一個方法：停止並重新建立所有容器

有時候，系統可能需要大量特殊修改，才能使用現有的網路或作業系統條件約束。例如，系統可能需要不同的資料磁碟掛接和 Proxy 設定。如果您嘗試了所有前述的步驟，但仍發生容器失敗，則 Docker 系統快取或持續性網路設定可能未與最新的重新設定保持同步。在此情況下，最後一個選項是使用 docker prune 來完全從頭開始。

後續命令會停止 IoT Edge 系統 (因此所有容器也會停止)，使用 docker prune 的 "all" 和 "volume" 選項以移除所有容器和磁碟區。檢閱命令發出的警告，並在就緒時透過 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 平台中發現到錯誤嗎？提交問題，讓我們可以持續進行改善。

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

共用方式為