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

發行項
07/17/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。

IoT Edge 裝置會傳送 HTTPS 要求以和 IoT 中樞通訊。如果將裝置連線至使用 Proxy 伺服器的網路，您必須設定 IoT Edge 執行階段以透過伺服器進行通訊。如果 IoT Edge 模組提出未透過 IoT Edge 中樞路由傳送的 HTTP 或 HTTPS 要求，則 Proxy 伺服器也可能會影響這些個別的 IoT Edge 模組。

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

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

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

此步驟是一次性程序，可讓您在第一次安裝 IoT Edge 裝置時加以設定。當您更新 IoT Edge 執行階段時，也需要這些相同連線。
在裝置上設定 IoT Edge 和容器執行階段

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

此步驟是一次性程序，可讓您在第一次安裝 IoT Edge 裝置時加以設定。
在裝置的組態檔中設定 IoT Edge 代理程式屬性

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

此步驟是一次性程序，可讓您在第一次安裝 IoT Edge 裝置時加以設定。
對於所有未來的模組部署，為任何透過 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 安裝的範例：

Invoke-WebRequest 命令需要 Proxy 資訊才能存取安裝程式指令碼。然後，Deploy-IoTEdge 命令需要 Proxy 資訊才能下載安裝檔案。
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
```
Initialize-IoTEdge 命令不需要經由 Proxy 伺服器，因此第二個步驟只需要 Invoke-WebRequest 的 Proxy 資訊。
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
```

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

$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。

設定 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 aziot-edged

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

[Service]
Environment="https_proxy=<proxy URL>"

從 1.2 版開始，IoT Edge 會使用 IoT 識別服務透過 IoT 中樞或 IoT 中樞裝置佈建服務來處理裝置佈建。在終端機中開啟編輯器，以設定 IoT 識別服務精靈。

sudo systemctl edit aziot-identityd

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

[Service]
Environment="https_proxy=<proxy URL>"

重新整理服務管理員以取得新設定。

sudo systemctl daemon-reload

重新啟動 IoT Edge 系統服務，讓兩個精靈的變更生效。

sudo iotedge system restart

確認您的環境變數和新組態都存在。

systemctl show --property=Environment aziot-edged
systemctl show --property=Environment aziot-identityd

使用 IoT Edge for Linux on Windows 的 Windows

登入您的 IoT Edge for Linux on Windows 虛擬機器：

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 裝置上執行一次。

在您的 IoT Edge 裝置上開啟組態檔：/etc/aziot/config.toml。您需要系統管理權限來存取組態檔。在 Linux 系統上，請先使用 sudo 命令，再使用您偏好的文字編輯器開啟檔案。
在組態檔中尋找 [agent] 區段，其中包含 edgeAgent 模組在啟動時所使用的所有設定資訊。檢查以確定 [agent] 區段沒有註解。如果遺漏 [agent] 區段，請將它新增至 config.toml。 IoT Edge 代理程式定義包含 [agent.env] 子區段，可供您於該處新增環境變數。

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

[agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
# "UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"

IoT Edge 執行階段預設會使用 AMQP 來與 IoT 中樞通訊。某些 Proxy 伺服器會封鎖 AMQP 連接埠。針對那種情況，您也必須設定 edgeAgent 以使用 AMQP，而非 WebSocket。取消註解 UpstreamProtocol 參數。
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```

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

[agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
# "UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"

IoT Edge 執行階段預設會使用 AMQP 來與 IoT 中樞通訊。某些 Proxy 伺服器會封鎖 AMQP 連接埠。針對那種情況，您也必須設定 edgeAgent 以使用 AMQP，而非 WebSocket。取消註解 UpstreamProtocol 參數。
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
儲存變更並關閉編輯器。套用您的最新變更。
```
sudo iotedge config apply
```
在 Env 區段中使用 docker inspect edgeAgent 確認您的 Proxy 設定已傳播。如果沒有，您必須重新建立容器。
```
sudo docker rm -f edgeAgent
```
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 中樞模組，請在精靈的第一個步驟中選取 [執行階段設定]。

如何設定進階 Edge 執行階段設定的螢幕擷取畫面。

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

所有其他新增至部署資訊清單的模組都會遵循相同的模式。選取 [套用] 以儲存變更。

JSON 部署資訊清單檔案

如果您是使用 Visual Studio Code 中的範本，或是手動建立 JSON 檔案來針對 IoT Edge 裝置建立部署，您可以將環境變數直接新增至每個模組定義中。如果您未在 Azure 入口網站中新增它們，請在此將它們新增至您的 JSON 資訊清單檔案。以您自己的值取代 <proxy URL>。

使用下列 JSON 格式：

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

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

"edgeHub": {
    "type": "docker",
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
        "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 模組 (包括 edgeAgent 和 edgeHub) 不信任此 Proxy 的憑證，TLS 交握失敗。

若要解決失敗的交握，請設定作業系統和 IoT Edge 模組，以使用下列步驟來信任 Proxy 的根憑證。

在主機作業系統的信任根憑證存放區中設定 Proxy 憑證。如需如何安裝根憑證的詳細資訊，請參閱將根 CA 安裝至 OS 憑證存放區。
藉由參考信任套件組合中的憑證，將您的 IoT Edge 裝置設定為透過 Proxy 伺服器通訊。如需如何設定信任套件組合的詳細資訊，請參閱管理信任的根 CA (信任套件組合)。

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

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

如果 Proxy 的防火牆要求您將所有用於網際網路連線的 FQDN 加入允許清單，請檢閱允許來自 IoT Edge 裝置的連線中的清單，以決定要新增哪些 FQDN。

下一步

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

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

共用方式為