Azure IoT Edge常見問題的解決方案

發行項
11/17/2022

適用於：IoT Edge 1.1

重要

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

使用本文來識別及解決使用IoT Edge解決方案時的常見問題。如果您需要如何從IoT Edge裝置尋找記錄和錯誤的資訊，請參閱針對IoT Edge裝置進行疑難排解。

布建和部署

IoT Edge 模組部署成功，然後從裝置消失

徵狀

設定 IoT Edge 裝置的模組後，模組會成功部署，但幾分鐘後，這些模組會從裝置上消失，並從 Azure 入口網站中的裝置詳細資料中消失。未定義的模組也可能出現在裝置上。

原因

如果自動部署是以裝置為目標，則其優先權會高於手動設定單一裝置的模組。 Azure 入口網站中的設定模組功能或為Visual Studio Code中的單一裝置功能建立部署會暫時生效。您會看到您定義的模組在裝置上啟動。然後，自動部署的優先順序會啟動並覆寫裝置所需的屬性。

解決方法

每個裝置僅使用一種類型的部署機制，可以是自動部署或個別裝置部署。如果您有多個以裝置為目標的自動部署，您可以變更優先順序或目標描述，以確保會將正確的部署套用至指定的裝置。您也可以更新裝置對應項，使其不再比對自動部署的目標描述。

如需詳細資訊，請參閱了解單一裝置或大規模的 IoT Edge 自動部署。

無法在 Windows 上取得IoT Edge執行時間記錄

徵狀

您在 Windows 上使用 Get-WinEvent 時，會收到 EventLogException。

原因

Get-WinEvent PowerShell 命令須依賴存在的登錄項目，才能根據特定 ProviderName 尋找記錄。

解決方法

設定 IoT Edge 精靈的登錄項目。建立具有下列內容的 iotedge.reg 檔案，然後按兩下此檔案或使用 reg import iotedge.reg 命令將檔案匯入至 Windows 登錄：

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\iotedged]
"CustomSource"=dword:00000001
"EventMessageFile"="C:\\ProgramData\\iotedge\\iotedged.exe"
"TypesSupported"=dword:00000007

DPS 用戶端錯誤

徵狀

IoT Edge 無法啟動，並出現錯誤訊息 failed to provision with IoT Hub, and no valid device backup was found dps client error.

原因

已使用群組註冊將 IoT Edge 裝置佈建到 IoT 中樞。 IoT Edge 裝置移至不同的中樞。註冊已在 DPS 中刪除。在 DPS 中為新中樞建立了新的註冊。裝置未重新布建。

解決方法

確認您的 DPS 認證正確無誤。
使用 sudo iotedge apply config 套用您的設定。
若裝置未重新佈建，請使用 sudo iotedge system restart 重新啟動裝置。
若裝置未重新佈建，請使用 sudo iotedge system reprovision 強制重新佈建。

若要自動重新佈建，請在裝置組態檔中設定 dynamic_reprovisioning: true。將此旗標設定為 true 會加入宣告動態重新布建功能。 IoT Edge 會監視本身的 IoT 中樞連線是否有特定錯誤，藉以偵測裝置可能已在雲端中重新佈建的情況。 IoT Edge關閉所有 Edge 模組和本身來回應。精靈在下次啟動時，將會嘗試使用 Azure 重新佈建此裝置，以接收新的 IoT 中樞佈建資訊。

使用外部布建時，精靈也會在關閉之前通知外部布建端點有關重新布建事件。如需詳細資訊，請參閱 IoT 中樞裝置重新佈建概念。

IoT Edge 執行階段

IoT Edge代理程式會在一分鐘後停止

徵狀

edgeAgent模組會啟動並成功執行約一分鐘，然後停止。記錄指出 IoT Edge 代理程式嘗試透過 AMQP 連線至 IoT 中樞，然後嘗試使用 AMQP over WebSocket 連線。這些作業失敗時，IoT Edge 代理程式即結束。

範例 edgeAgent 記錄：

2017-11-28 18:46:19 [INF] - Starting module management agent.
2017-11-28 18:46:19 [INF] - Version - 1.0.7516610 (03c94f85d0833a861a43c669842f0817924911d5)
2017-11-28 18:46:19 [INF] - Edge agent attempting to connect to IoT Hub via AMQP...
2017-11-28 18:46:49 [INF] - Edge agent attempting to connect to IoT Hub via AMQP over WebSocket...

原因

主機網路上的網路設定阻止了 IoT Edge 代理程式連線到該網路。代理程式首先嘗試透過 AMQP (連接埠 5671) 進行連線。如果連線失敗，代理程式會嘗試 Websocket (連接埠 443)。

IoT Edge 執行階段會為每個模組設定要在其中通訊的網路。在 Linux 上，此網路是橋接網路。在 Windows 上則是使用 NAT。此問題較常見於使用 Windows 容器 (使用 NAT 網路) 的 Windows 裝置。

解決方法

請確定指派給此橋接器/NAT 網路的 IP 位址有網際網路的路由。有時候主機上的 VPN 組態會覆寫 IoT Edge 網路。

Edge 代理程式模組報告「空白的組態檔」，且裝置上未啟動任何模組

徵狀

裝置無法啟動定義於部署中的模組。只有 edgeAgent 正在執行，但會持續報告「空的組態檔...」。

原因

根據預設，IoT Edge 會在其本身的隔離容器網路中啟動模組。此私人網路內的 DNS 名稱解析可能發生問題。

解決方法

選項 1：在容器引擎設定中設定 DNS 伺服器

在容器引擎設定中指定環境的 DNS 伺服器，這將會套用至引擎所啟動的所有容器模組。建立名為 daemon.json 的檔案，然後指定要使用的 DNS 伺服器。例如：

{
    "dns": ["1.1.1.1"]
}

此 DNS 伺服器會設定為可公開存取的 DNS 服務。但某些網路 (例如公司網路) 已安裝本身的 DNS 伺服器，且不允許存取公用 DNS 伺服器。因此，如果您的邊緣裝置無法存取公用 DNS 伺服器，請將其取代為可存取的 DNS 伺服器位址。

將 daemon.json 放在平台的適當位置：

平台	位置
Linux	`/etc/docker`
具有 Windows 容器的 Windows 主機	`C:\ProgramData\iotedge-moby\config`

如果該位置已包含 daemon.json 檔案，請在其中新增 dns 金鑰，並儲存檔案。

重新啟動容器引擎，讓更新生效。

平台	Command
Linux	`sudo systemctl restart docker`
Windows (Admin PowerShell)	`Restart-Service iotedge-moby -Force`

選項 2：在 IoT Edge 部署中設定每個模組的 DNS 伺服器

您可以在 IoT Edge 部署中，為每個模組的 createOptions 設定 DNS 伺服器。例如：

"createOptions": {
  "HostConfig": {
    "Dns": [
      "x.x.x.x"
    ]
  }
}

警告

如果您使用此方法，但指定了錯誤的 DNS 位址，edgeAgent 將會失去與 IoT 中樞的連線，且無法接收新的部署以修正問題。若要解決此問題，您可以重新安裝 IoT Edge 執行階段。在安裝新的 IoT Edge 執行個體之前，請務必從先前的安裝中移除任何 edgeAgent 容器。

請務必也為 edgeAgent 和 edgeHub 模組進行此設定。

Edge 代理程式無法存取模組的映像 (403)

徵狀

容器無法執行， edgeAgent 記錄會報告 403 錯誤。

原因

IoT Edge代理程式模組沒有存取模組映射的許可權。

解決方法

請確定您的容器登錄認證是正確的裝置部署資訊清單。

IoT Edge 中樞無法啟動

徵狀

edgeHub 模組無法啟動。您可能會在記錄中看到類似下列其中一個錯誤的訊息：

One or more errors occurred.
(Docker API responded with status code=InternalServerError, response=
{\"message\":\"driver failed programming external connectivity on endpoint edgeHub (6a82e5e994bab5187939049684fb64efe07606d2bb8a4cc5655b2a9bad5f8c80):
Error starting userland proxy: Bind for 0.0.0.0:443 failed: port is already allocated\"}\n)

info: edgelet_docker::runtime -- Starting module edgeHub...
warn: edgelet_utils::logging -- Could not start module edgeHub
warn: edgelet_utils::logging --     caused by: failed to create endpoint edgeHub on network nat: hnsCall failed in Win32:  
        The process cannot access the file because it is being used by another process. (0x20)

原因

主機電腦上的一些其他程序已繫結 edgeHub 模組嘗試繫結的連接埠。 IoT Edge 中樞會對應連接埠 443、5671 和 8883，以在閘道案例中使用。如果另一個程序已繫結其中一個連接埠，模組將無法啟動。

解決方法

您可以透過兩種方式來解決此問題：

如果 IoT Edge 裝置作為閘道裝置運作，則您必須找出使用連接埠 443、5671 或 8883 的程序，並加以停止。連接埠 443 的錯誤通常表示另一個程序是網頁伺服器。

如果您不需要使用 IoT Edge 裝置作為閘道，則可以從 edgeHub 的模組建立選項中移除連接埠繫結。您可以在 Azure 入口網站或直接在 deployment.json 檔案中變更建立選項。

在 Azure 入口網站中：

瀏覽至您的 IoT 中樞，然後選取 [裝置管理] 功能表底下的 [裝置]。
選取您要更新的 IoT Edge 裝置。
選取 [設定模組]。
選取 [執行階段設定]。
在 [Edge 中樞] 模組設定中，從 [建立選項] 文字方塊中刪除所有項目。
儲存變更並建立部署。

在 deployment.json 檔案中：

開啟已套用至 IoT Edge 裝置的 deployment.json 檔案。

在 edgeAgent 所需的屬性區段中尋找 edgeHub 設定：

"edgeHub": {
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.1",
        "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
    },
    "type": "docker",
    "status": "running",
    "restartPolicy": "always"
}

移除 createOptions 行，及其前面的 image 行結尾處的尾端逗號：

"edgeHub": {
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.1"
    },
    "type": "docker",
    "status": "running",
    "restartPolicy": "always"
}

儲存檔案，並再次將其套用至您的 IoT Edge 裝置。

IoT Edge 模組因發生 404 錯誤而無法將訊息傳送給 edgeHub

徵狀

自訂 IoT Edge 模組因發生 404 Module not found 錯誤而無法將訊息傳送至 IoT Edge 中樞。 IoT Edge執行時間會將下列訊息列印至記錄：

Error: Time:Thu Jun  4 19:44:58 2018 File:/usr/sdk/src/c/provisioning_client/adapters/hsm_client_http_edge.c Func:on_edge_hsm_http_recv Line:364 executing HTTP request fails, status=404, response_buffer={"message":"Module not found"}u, 04 )

原因

IoT Edge執行時間會針對連線到 edgeHub 的所有模組強制執行進程識別，因為安全性原因。它會確認模組傳送的所有訊息都來自該模組的主要處理序識別碼。如果傳送訊息之模組的來源處理序識別碼與最初確立的識別碼不同，它就會發出 404 錯誤訊息來拒絕該訊息。

解決方法

從 1.0.7 版開始，所有模組程序都已有權連線。如需詳細資訊，請參閱 1.0.7 版本變更記錄。

如果無法升級至 1.0.7，請完成下列步驟。請確定自訂 IoT Edge 模組一律使用相同的處理序識別碼將訊息傳送給 edgeHub。例如，請務必在 Docker 檔案中使用 ENTRYPOINT，而不使用 CMD 命令。 CMD 命令會導致模組有一個程序識別碼，執行主要程式的 Bash 命令有另一個程序識別碼，而 ENTRYPOINT 則會產生單一程序識別碼。

在較小的裝置上發生穩定性問題

徵狀

資源受限的裝置 (例如 Raspberry Pi) 可能會發生穩定性的問題，尤其是在當作閘道時。徵兆包括 IoT Edge 中樞模組發生記憶體不足例外狀況、下游裝置無法連線，或裝置在數小時後即無法傳送遙測訊息。

原因

根據預設，IoT Edge 中樞 (是 IoT Edge 執行階段的一部分) 已針對效能最佳化，且會嘗試配置大量的記憶體。此優化不適用於受限制的邊緣裝置，而且可能會導致穩定性問題。

解決方法

針對 IoT Edge 中樞，將環境變數 OptimizeForPerformance 設定為 false。有兩種方式可以設定環境變數：

在 Azure 入口網站中：

在 IoT 中樞選取您的 IoT Edge 裝置，然後從裝置詳細資料頁面中選取 [設定模組]>[執行階段設定]。為 IoT Edge 中樞模組建立名為 OptimizeForPerformance、設定為 false 的環境變數。

將 OptimizeForPerformance 設定為 false

在部署資訊清單中：

"edgeHub": {
  "type": "docker",
  "settings": {
    "image": "mcr.microsoft.com/azureiotedge-hub:1.1",
    "createOptions": <snipped>
  },
  "env": {
    "OptimizeForPerformance": {
      "value": "false"
    }
  },

安全性精靈無法成功啟動

徵狀

安全性精靈無法啟動，且模組容器未建立。 IoT Edge 服務未啟動 edgeAgent、edgeHub 和其他自訂模組。在 aziot-edged 記錄中，您看到下列錯誤：

精靈無法成功啟動：無法啟動管理服務

原因：路徑 /var/run/iotedge/mgmt.sock 發生錯誤

原因：權限遭拒 (OS 錯誤 13)

原因

對於 CentOS 7 以外的所有 Linux 發行版本，IoT Edge 的預設設定是使用 systemd 通訊端啟用。如果您將組態檔變更為不使用通訊端啟用，但將 URL 保留為 /var/run/iotedge/*.sock，由於 iotedge 使用者無法寫入 /var/run/iotedge (這意味著無法將通訊端本身解除鎖定並掛接)，因此會發生權限錯誤。

解決方法

您不需要在支援通訊端啟用的散發套件上停用通訊端啟用。不過，如果您完全不想使用通訊端啟用，請將通訊端放在 /var/lib/iotedge/ 中。

執行 systemctl disable iotedge.socket iotedge.mgmt.socket 以停用通訊端單元，讓 systemd 不會無謂地加以啟動
變更 iotedge 設定，以同時在 connect 和 listen 區段中使用 /var/lib/iotedge/*.sock
如果您已有模組，模組會有舊的 /var/run/iotedge/*.sock 掛接，因此請加以 docker rm -f。

因 OS 不符而無法啟動模組

徵狀

edgeHub 模組無法在 IoT Edge 1.1 版中啟動。

原因

Windows 模組使用的 Windows 版本與主機上的 Windows 版本不相容。需使用 IoT Edge Windows 版本 1809 組建 17763 作為模組映像的基礎層，但使用的是不同的版本。

解決方法

在對主機和容器映像不符進行疑難排解中，檢查各種 Windows 作業系統的版本。如果作業系統不同，請將其更新為 IoT Edge Windows 版本 1809 組建 17763，然後重建該模組所使用的 Docker 映像。

網路功能

IoT Edge 安全性精靈因主機名稱無效而失敗

徵狀

嘗試檢查 IoT Edge 安全性管理員記錄失敗，並列印了下列訊息：

Error parsing user input data: invalid hostname. Hostname cannot be empty or greater than 64 characters

原因

IoT Edge 執行階段只能支援少於 64 個字元的主機名稱。實體機器通常不需要很長的主機名稱，但問題在虛擬機器上更常發生。在 Azure 中代管的 Windows 虛擬機器自動產生的主機名稱通常很長。

解決方法

當發現這個錯誤時，可以設定虛擬機器的 DNS 名稱，然後將 DNS 名稱設定為安裝命令中的主機名稱來解決。

在 Azure 入口網站中，瀏覽至虛擬機器的概觀頁面。
選取 DNS 名稱下的 [設定]。如果虛擬機器已設定 DNS 名稱，則不需要設定新的名稱。
提供 DNS 名稱標籤的值，並選取 [儲存]。
複製新的 DNS 名稱，格式應該是 <DNSnamelabel>.<vmlocation>.cloudapp.azure.com。
在虛擬機器中，使用下列命令以您的 DNS 名稱設定 IoT Edge 執行階段：
- 在 Linux 上：
```
sudo nano /etc/iotedge/config.yaml
```
- 在 Windows 上：
```
notepad C:\ProgramData\iotedge\config.yaml
```

IoT Edge 模組報告連線錯誤

徵狀

直接連線至雲端服務的 IoT Edge 模組 (包括執行階段模組) 如預期停止運作，並傳回關於連線或網路失敗的錯誤。

原因

容器依賴 IP 封包轉送連線至網際網路，以便與雲端服務通訊。預設會在 Docker 中啟用 IP 封包轉送，但如果已停用，則連線到雲端服務的任何模組將無法如預期般運作。如需詳細資訊，請參閱 Docker 文件中的了解容器通訊。

解決方法

使用下列步驟來啟用 IP 封包轉送。

在 Windows 上：

開啟 [執行] 應用程式。
在文字方塊中輸入 regedit，然後選取 [確定]。
在 [登錄編輯程式] 視窗中，瀏覽至 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters。
尋找 IPEnableRouter 參數。
1. 如果該參數存在，請將參數的值設定為 1。
2. 如果參數不存在，請使用下列設定將其新增為新參數：
  
  設定值
  
  名稱 IPEnableRouter
  
  類型 REG_DWORD
  
  值 1
關閉 [登錄編輯程式] 視窗。
重新啟動系統以套用變更。

設定	值
名稱	IPEnableRouter
類型	REG_DWORD
值	1

在 Linux 上：

開啟 sysctl.conf 檔案。
```
sudo nano /etc/sysctl.conf
```
在檔案中新增以下一行。
```
net.ipv4.ip_forward=1
```
儲存並關閉檔案。
重新啟動網路服務和 Docker 服務，以套用變更。

下一步

您在 IoT Edge 平台中發現到錯誤嗎？提交問題，讓我們可以持續進行改善。

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

共用方式為

Azure IoT Edge常見問題的解決方案

布建和部署

IoT Edge 模組部署成功，然後從裝置消失

徵狀

原因

解決方法

無法在 Windows 上取得IoT Edge執行時間記錄

徵狀

原因

解決方法

DPS 用戶端錯誤

徵狀

原因

解決方法

IoT Edge 執行階段

IoT Edge代理程式會在一分鐘後停止

徵狀

原因

解決方法

Edge 代理程式模組報告「空白的組態檔」，且裝置上未啟動任何模組

徵狀

原因

解決方法

Edge 代理程式無法存取模組的映像 (403)

徵狀

原因

解決方法

IoT Edge 中樞無法啟動

徵狀

原因

解決方法

IoT Edge 模組因發生 404 錯誤而無法將訊息傳送給 edgeHub

徵狀

原因

解決方法

在較小的裝置上發生穩定性問題

徵狀

原因

解決方法

安全性精靈無法成功啟動

徵狀

原因

解決方法

因 OS 不符而無法啟動模組

徵狀

原因

解決方法

網路功能

IoT Edge 安全性精靈因主機名稱無效而失敗

徵狀

原因

解決方法

IoT Edge 模組報告連線錯誤

徵狀

原因

解決方法

下一步

其他資源