[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 您平台的正確位置：

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

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

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

平台	Command
Linux	`sudo systemctl restart docker`
Windows （系統管理員 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 代理程式模組沒有存取模組映像的權限。

解決方案

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

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 Hub 模組設定中，從 [建立選項] 文字框中刪除所有專案。
儲存變更並建立部署。

在 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 裝置，然後從裝置詳細資料頁面中選取 [設定模組]>[執行階段設定]。為名為 OptimizeForPerformance 的 IoT Edge 中樞模組建立環境變數，其設定為 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)

徵兆

原因

解決方案

Edge 中樞無法啟動

徵兆

原因

解決方案

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

徵兆

原因

解決方案

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

徵兆

原因

解決方案

安全性精靈無法成功啟動

徵兆

原因

解決方案

無法啟動模組，因為OS不相符

徵兆

原因

解決方案

網路

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

徵兆

原因

解決方案

IoT Edge模組報告連線錯誤

徵兆

原因

解決方案

下一步

其他資源