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

發行項
08/25/2022

適用於： IoT Edge 1.1

重要

IoT Edge 1.1 終止支援日期為 2022 年 12 月 13 日。如需此產品、服務、技術或 API 的支援資訊，請參閱 Microsoft 產品生命週期。如需更新至最新版IoT Edge的詳細資訊，請參閱更新IoT Edge。

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

執行 'check' 命令

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

注意

如果 IoT Edge 裝置位於 Proxy 伺服器後方，則疑難排解工具無法執行連線檢查。

您可以依照下列方式執行 check 命令，或包含 --help 旗標以查看完整的選項清單：

在 Linux 上：

sudo iotedge check

在 Windows 上：

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 疑難排解檢查。

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

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

搭配 --since 旗標執行 support-bundle 命令，以指定您想要取得多久以前的記錄。例如，6h 會取得過去六小時的記錄、6d 會取得過去六天的記錄、6m 會取得過去六分鐘的記錄，以此類推。包含 --help 旗標以查看完整的選項清單。

在 Linux 上：

sudo iotedge support-bundle --since 6h

在 Windows 上：

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 未啟動，安全性管理員記錄可能會提供有用的資訊。

在 Linux 上：

檢視 IoT Edge 安全性管理員的狀態：
```
sudo systemctl status iotedge
```
檢視 IoT Edge 安全性管理員的記錄：
```
sudo journalctl -u iotedge -f
```

檢視 IoT Edge 安全性管理員的詳細記錄：

編輯 IoT Edge 精靈設定：
```
sudo systemctl edit iotedge.service
```

更新下列幾行：

[Service]
Environment=IOTEDGE_LOG=debug

重新啟動 IoT Edge 安全性精靈：

sudo systemctl cat iotedge.service
sudo systemctl daemon-reload
sudo systemctl restart iotedge

在 Windows 上：

檢視 IoT Edge 安全性管理員的狀態：
```
Get-Service iotedge
```

檢視 IoT Edge 安全性管理員的記錄：

. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog

僅檢視 IoT Edge 安全性管理員記錄的最後 5 分鐘：

. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog -StartTime ([datetime]::Now.AddMinutes(-5))

檢視 IoT Edge 安全性管理員的詳細記錄：

新增系統層級環境變數：

[Environment]::SetEnvironmentVariable("IOTEDGE_LOG", "debug", [EnvironmentVariableTarget]::Machine)

重新啟動 IoT Edge 安全性精靈：
```
Restart-Service iotedge
```

檢查容器記錄的問題

在 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中樞的訊息，並從運行時間容器的詳細記錄收集深入解析。若要在這些容器上開啟詳細資訊記錄，請在 yaml 組態檔中設定 RuntimeLogLevel 。若要開啟檔案：

在 Linux 上：

sudo nano /etc/iotedge/config.yaml

在 Windows 上：

notepad C:\ProgramData\iotedge\config.yaml

根據預設，元素 agent 看起來會像下列範例：

agent:
  name: edgeAgent
  type: docker
  env: {}
  config:
    image: mcr.microsoft.com/azureiotedge-agent:1.1
    auth: {}

取代為 env: {} ：

env:
  RuntimeLogLevel: debug

警告

YAML 檔案不能包含索引標籤做為縮排。請改用 2 個空格。最上層專案不能有前置空格符。

儲存盤案並重新啟動IoT Edge安全性管理員。

您也可以檢查在 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 Hub 通訊協定進行從內部部署伺服器到 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	已封鎖 (預設值)	已封鎖 (預設值)	使用 MQTT 作為通訊協定時，請將「傳出」(輸出) 設定為「開放」。 IoT Edge 不支援 MQTT 的 1883。應該將傳入 (輸入) 連線封鎖。
AMQP	5671	已封鎖 (預設值)	開放 (預設值)	IoT Edge 的預設通訊協定。如果未針對其他支持的通訊協定設定 Azure IoT Edge，或 AMQP 是所需的通訊協定，則必須設定為 Open。 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 不支援 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 平台中發現到錯誤嗎？提交問題，讓我們可以持續進行改善。

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

共用方式為

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

執行 'check' 命令

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

檢閱從執行階段收集的計量

檢查您的 IoT Edge 版本

確認裝置上的 IoT Edge 安裝

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

檢查容器記錄的問題

清除容器記錄

檢視通過 IoT Edge 中樞的訊息

重新啟動容器

檢查您的防火牆和連接埠設定規則

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

下一步

其他資源