設定 IoT Edge 裝置以透過 Proxy 伺服器進行通訊

適用於： IoT Edge 1.1

重要

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

IoT Edge 裝置會傳送 HTTPS 要求以和 IoT 中樞通訊。 如果您的裝置連線到使用 Proxy 伺服器的網路，您必須設定 IoT Edge 運行時間以透過伺服器進行通訊。 如果 Proxy 伺服器發出 HTTP 或 HTTPS 要求，但不會透過 IoT Edge 中樞路由傳送，Proxy 伺服器也會影響個別的 IoT Edge 模組。

本文將逐步解說如何使用下列四個步驟，設定及管理位於 Proxy 伺服器後方的 IoT Edge 裝置：

1. 在裝置上安裝 IoT Edge 執行階段

   IoT Edge 安裝指令碼會從網際網路提取套件和檔案，因此您的裝置必須透過 Proxy 伺服器進行通訊，才能提出這些要求。 對於 Windows 裝置，安裝指令碼也會提供離線安裝選項。

   此步驟是一次性程序，可讓您在第一次安裝 IoT Edge 裝置時加以設定。 當您更新IoT Edge運行時間時，也需要相同的連線。

2. 在裝置上設定 IoT Edge 和容器執行階段

   IoT Edge 負責與 IoT 中樞通訊。 容器執行階段負責進行容器管理，因此會與容器登錄通訊。 這兩個元件都需要透過 Proxy 伺服器提出 Web 要求。

   此步驟是一次性程序，可讓您在第一次安裝 IoT Edge 裝置時加以設定。

3. 在裝置的組態檔中設定 IoT Edge 代理程式屬性

   IoT Edge 精靈最初會啟動 edgeAgent 模組。 然後，edgeAgent 模組會從 IoT 中樞擷取部署資訊清單，並啟動所有其他模組。 若要讓IoT Edge代理程式對 IoT 中樞 進行初始連線，請在裝置本身手動設定edgeAgent模組環境變數。 初始連線之後，您可以從遠端設定 edgeAgent 模組。

   此步驟是一次性程序，可讓您在第一次安裝 IoT Edge 裝置時加以設定。

4. 對於所有未來的模組部署，為任何透過 Proxy 進行通訊的模組設定環境變數

   設定 IoT Edge 裝置並透過 Proxy 伺服器連線到 IoT 中樞 之後，您必須在所有未來的模組部署中維護連線。

   此步驟是從遠端執行的一項持續性程序，目的是要在每次新的模組或部署更新之後，保有裝置透過 Proxy 伺服器進行通訊的能力。

知道您的 Proxy URL

開始進行本文中的任何步驟之前，您必須知道自己的 Proxy URL。

Proxy URL 採用下列格式：protocol://proxy_host:proxy_port。

• protocol是 HTTP 或 HTTPS。 Docker 精靈可以使用任一種通訊協定，端視您的容器登錄設定而定，但 IoT Edge 精靈和執行階段容器應一律使用 HTTPS 連線至 Proxy。

• proxy_host是 Proxy 伺服器的位址。 如果您的 Proxy 伺服器需要驗證，您可以使用下列格式將認證提供作為 Proxy 主機的一部分：user:password@proxy_host。

• proxy_port是 Proxy 回應網路流量的網路連接埠。

透過 Proxy 安裝 IoT Edge

無論您的 IoT Edge 裝置是在 Windows 或 Linux 上執行，您都需要透過 Proxy 伺服器來存取安裝套件。 根據您的作業系統，依照相關步驟透過 Proxy 伺服器安裝 IoT Edge 執行階段。

Linux 裝置

若您正於 Linux 裝置上安裝 IoT Edge 執行階段，請設定套件管理員以 Proxy 伺服器存取安裝套件。 例如，設定 apt-get 以使用 http-proxy \(英文\)。 設定套件管理員之後，請依照一般方式安裝 Azure IoT Edge 運行時間中的指示操作。

使用 IoT Edge for Linux on Windows 的 Windows 裝置

如果您要安裝使用 IoT Edge for Linux on Windows 的 IoT Edge 執行階段，依預設會在 Linux 虛擬機器上安裝 IoT Edge。 不需要額外的安裝或更新步驟。

使用 Windows 容器的 Windows 裝置

若您在 Windows 裝置上安裝 IoT Edge 執行階段，則必須經由 Proxy 伺服器操作兩次。 第一次連線下載安裝程式指令碼檔案，第二次連線則是在安裝期間下載必要的元件。 您可以在 Windows 設定中設定 Proxy 資訊，或直接在 PowerShell 命令中包含您的 Proxy 資訊。

下列步驟示範使用 -proxy 引數進行 Wndows 安裝的範例：

1. Invoke-WebRequest 命令需要 Proxy 資訊才能存取安裝程式指令碼。 然後，Deploy-IoTEdge 命令需要 Proxy 資訊才能下載安裝檔案。

   . {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
   

2. Initialize-IoTEdge 命令不需要經由 Proxy 伺服器，因此第二個步驟只需要 Invoke-WebRequest 的 Proxy 資訊。

   . {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
   

如果您有無法包含在 URL 中的 Proxy 伺服器的複雜認證，請使用 -ProxyCredential 中的 -InvokeWebRequestParameters參數。 例如，

$proxyCredential = (Get-Credential).GetNetworkCredential()
. {Invoke-WebRequest -proxy <proxy URL> -ProxyCredential $proxyCredential -useb aka.ms/iotedge-win} | Invoke-Expression; `
Deploy-IoTEdge -InvokeWebRequestParameters @{ '-Proxy' = '<proxy URL>'; '-ProxyCredential' = $proxyCredential }

如需 Proxy 參數的詳細資訊，請參閱 Invoke-WebRequest。 如需 Windows 安裝參數的詳細資訊，請參閱 Windows 上 IoT Edge 的 PowerShell 腳本。

設定 IoT Edge 和 Moby

IoT Edge 須依賴在 IoT Edge 裝置上執行的兩個精靈。 Moby 精靈會發出從容器登錄中提取容器映像的 Web 要求。 IoT Edge 精靈會發出 Web 要求，以和 IoT 中樞通訊。

Moby 和 IoT Edge 精靈都必須設定為使用 Proxy 伺服器進行進行中的裝置功能。 此步驟會在初始裝置設定期間於 IoT Edge 裝置上執行。

Moby 精靈

由於 Moby 是基於 Docker 而建置的，若要使用環境變數設定 Moby 精靈，請參閱 Docker 文件。 大部分的容器登錄 (包括 Docker Hub 和 Azure Container Registry) 皆支援 HTTPS 要求，因此您應該設定的參數為 HTTPS_PROXY。 如果您是從不支援傳輸層安全性 (TLS) 的登錄提取映像，則應該設定 HTTP_PROXY 參數。

選擇您的 IoT Edge 裝置作業系統適用的文章：

• 在 Linux 上設定 Docker 精靈 Linux 裝置上的 Moby 精靈保留了 Docker 名稱。
• 在 Windows 上設定 Docker 精靈 Windows 裝置上的 Moby 精靈名為 iotedge-moby。 其名稱不同，因為可以在 Windows 裝置上平行執行 Docker Desktop 和 Moby。

IoT Edge 精靈

IoT Edge 精靈是以與Moby精靈類似的方式設定。 請根據您的作業系統，使用下列相對應的步驟來針對服務設定環境變數。

IoT Edge 精靈一律會使用 HTTPS 將要求傳送至 IoT 中樞。

Linux

在終端機中開啟編輯器以設定 IoT 精靈。

sudo systemctl edit iotedge

輸入下列文字，並將 <proxy URL> 取代為您的 Proxy 伺服器位址和連接埠。 然後儲存並結束。

[Service]
Environment=https_proxy=<proxy URL>

重新整理服務管理員以挑選IoT Edge的新組態。

sudo systemctl daemon-reload

重新啟動 IoT Edge 來讓變更生效。

sudo systemctl restart iotedge

確認您的環境變數已建立，並已載入新的組態。

systemctl show --property=Environment iotedge

使用 IoT Edge for Linux on Windows 的 Windows

在 Windows 虛擬機上登入適用於 Linux 的 IoT Edge：

Connect-EflowVm

請遵循與上述 Linux 一節相同的步驟來設定 IoT Edge 精靈。

使用 Windows 容器的 Windows

以系統管理員身分開啟 PowerShell 視窗，並執行下列命令以搭配新的環境變數編輯登錄。 將 <proxy url> 取代為您 Proxy 伺服器的位址和連接埠。

reg add HKLM\SYSTEM\CurrentControlSet\Services\iotedge /v Environment /t REG_MULTI_SZ /d https_proxy=<proxy URL>

重新啟動 IoT Edge 來讓變更生效。

Restart-Service iotedge

設定 IoT Edge 代理程式

IoT Edge 代理程式是在任何 IoT Edge 裝置上皆應第一個啟動的模組。 這是第一次根據IoT Edge組態檔中的資訊啟動。 IoT Edge 代理程式接著會連線到 IoT 中樞 以擷取部署指令清單，以宣告裝置上應該部署的其他模組。

此步驟會在初始裝置設定期間於 IoT Edge 裝置上執行一次。

1. 在您的IoT Edge裝置上開啟 config.yaml 檔案。 在 Linux 系統上，此檔案位於 /etc/iotedge/config.yaml。 在 Windows 系統上，此檔案位於 C：\ProgramData\iotedge\config.yaml。 組態檔受到保護，因此您需要系統管理許可權才能存取它。 在 Linux 系統上，請先使用 sudo 命令，再使用您偏好的文字編輯器開啟檔案。 在 Windows 上，以系統管理員身分開啟 [記事本] 之類的文本編輯器，然後開啟檔案。

2. 在 config.yaml 檔案中，尋找 Edge Agent 模組規格 區段。 IoT Edge 代理程式定義包含 env 參數，您可以在其中新增環境變數。

3. 拿掉 env 參數佔位符的大括弧，然後在新行上新增變數。 請記住，YAML 中的縮排是兩個空格。

   https_proxy: "<proxy URL>"
   

4. IoT Edge 執行階段預設會使用 AMQP 來與 IoT 中樞通訊。 某些 Proxy 伺服器會封鎖 AMQP 連接埠。 針對那種情況，您也必須設定 edgeAgent 以使用 AMQP，而非 WebSocket。 新增第二個環境變數。

   UpstreamProtocol: "AmqpWs"
   

   

5. 將變更儲存至 config.yaml，然後關閉編輯器。 重新啟動 IoT Edge 來讓變更生效。

   • Windows 上的 Linux 和適用於 Linux 的 IoT Edge：

     sudo systemctl restart iotedge
     

   • 使用 Windows 容器的 Windows：

     Restart-Service iotedge
     

3. 將 https_proxy 參數新增至環境變數區段，並將 Proxy URL 設定為其值。

   [agent]
   name = "edgeAgent"
   type = "docker"
   
   [agent.config]
   image = "mcr.microsoft.com/azureiotedge-agent:1.4"
   
   [agent.env]
   # "RuntimeLogLevel" = "debug"
   # "UpstreamProtocol" = "AmqpWs"
   "https_proxy" = "<proxy URL>"
   

4. IoT Edge 執行階段預設會使用 AMQP 來與 IoT 中樞通訊。 某些 Proxy 伺服器會封鎖 AMQP 連接埠。 針對那種情況，您也必須設定 edgeAgent 以使用 AMQP，而非 WebSocket。 取消註解 UpstreamProtocol 參數。

   [agent.config]
   image = "mcr.microsoft.com/azureiotedge-agent:1.4"
   
   [agent.env]
   # "RuntimeLogLevel" = "debug"
   "UpstreamProtocol" = "AmqpWs"
   "https_proxy" = "<proxy URL>"
   

5. 儲存變更並關閉編輯器。 套用您的最新變更。

   sudo iotedge config apply
   

6. 在 Env 區段中使用 docker inspect edgeAgent 確認您的 Proxy 設定已傳播。 如果沒有，則必須重新建立容器。

   sudo docker rm -f edgeAgent
   

7. IoT Edge 執行階段應該會在一分鐘內重新建立 edgeAgent。 一旦 edgeAgent 容器再次執行， docker inspect edgeAgent 並確認 Proxy 設定符合組態檔。

設定部署資訊清單

將 IoT Edge 裝置設定為使用 Proxy 伺服器之後，您必須在未來的部署指令清單中繼續宣告HTTPS_PROXY環境變數。 您可以使用 Azure 入口網站精靈，或藉由編輯部署資訊清單 JSON 檔案，來編輯部署資訊清單。

請一律設定兩個執行階段模組 (edgeAgent 和 edgeHub) 透過 Proxy 伺服器進行通訊，以維持與 IoT 中樞的連線。 如果您從 edgeAgent 模組移除了 Proxy 資訊，則重新建立連線的唯一方式將是編輯裝置上的組態檔，如上一節所述。

除了 edgeAgent 和 edgeHub 模組以外，其他模組可能也需要 Proxy 設定。 需要存取 IoT 中樞以外的 Azure 資源 (例如 Blob 儲存體) 的模組，必須已在部署資訊清單檔中指定 HTTPS_PROXY 變數。

下列程序在 IoT Edge 裝置的整個生命週期內均適用。

Azure 入口網站

當您使用 [設定模組] 精靈來針對 IoT Edge 裝置建立部署時，每個模組都會有 [環境變數] 區段可供您設定 Proxy 伺服器連線。

若要設定 IoT Edge 代理程式和 IoT Edge 中樞模組，請在精靈的第一個步驟中選取 [執行階段設定]。

將 https_proxy 環境變數同時新增至 IoT Edge 代理程式和 IoT Edge 中樞模組定義。 如果您已在 IoT Edge 裝置上的組態檔中包含 UpstreamProtocol 環境變數，請同時將該環境變數新增至 IoT Edge 代理程式模組定義。

所有其他新增至部署資訊清單的模組都會遵循相同的模式。

JSON 部署資訊清單檔案

如果您是使用 Visual Studio Code 中的範本，或是手動建立 JSON 檔案來針對 IoT Edge 裝置建立部署，您可以將環境變數直接新增至每個模組定義中。

使用下列 JSON 格式：

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    }
}

在包含環境變數的情況下，您的模組定義看起來應該會和下列 edgeHub 範例類似：

"edgeHub": {
    "type": "docker",
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.1",
        "createOptions": "{}"
    },
    "env": {
        "https_proxy": {
            "value": "http://proxy.example.com:3128"
        }
    },
    "status": "running",
    "restartPolicy": "always"
}

如果您已在 IoT Edge 裝置上的 confige.yaml 檔案中包含 UpstreamProtocol 環境變數，請同時將該環境變數新增至 IoT Edge 代理程式模組定義。

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    },
    "UpstreamProtocol": {
        "value": "AmqpWs"
    }
}

使用流量檢查 Proxy

某些 Proxy (例如 Zscaler) 可以檢查 TLS 加密的流量。 在 TLS 流量檢查期間，Proxy 傳回的憑證不是來自目標伺服器的憑證，而是 Proxy 自己的根憑證所簽署的憑證。 根據預設，IoT Edge 模組不會信任此 Proxy 的憑證（包括 edgeAgent 和 edgeHub），TLS 交握會失敗。

若要解決此問題，操作系統和IoT Edge模組都必須信任 Proxy 的跟證書。

1. 在主機作業系統的信任根憑證存放區中設定 Proxy 憑證。 如需如何安裝根憑證的詳細資訊，請參閱將根 CA 安裝至 OS 憑證存放區。

2. 藉由參考信任套件組合中的憑證，將您的 IoT Edge 裝置設定為透過 Proxy 伺服器通訊。 如需如何設定信任套件組合的詳細資訊，請參閱管理信任的根 CA (信任套件組合)。

若要為 IoT Edge 未管理的容器設定流量檢查 Proxy 支援，請連絡您的 Proxy 提供者。

IoT Edge 通訊目的地的完整網域名稱 (FQDN)

如果您的 Proxy 具有需要您允許列出所有 FQDN 以進行因特網連線的防火牆，請檢閱 [允許來自 IoT Edge 裝置的連線] 清單，以判斷要新增的 FQDN。

下一步

深入了解 IoT Edge 執行階段的角色。

使用 Azure IoT Edge 的常見問題和解決方案來對安裝和設定錯誤進行疑難排解