将 IoT Edge 设备配置为通过代理服务器进行通信

项目
04/12/2024

适用于： IoT Edge 1.4

IoT Edge 设备将发送 HTTPS 请求以与 IoT 中心进行通信。如果已将设备连接到使用代理服务器的网络，则需要将 IoT Edge 运行时配置为通过该服务器进行通信。如果代理服务器发出未通过 IoT Edge 中心路由的 HTTP 或 HTTPS 请求，则可能还会影响各个 IoT Edge 模块。

本文将引导你完成以下四个步骤，来配置并管理代理服务器后面的 IoT Edge 设备：

在设备上安装 IoT Edge 运行时

IoT Edge 安装脚本从 Internet 提取包和文件，因此，设备需要通过代理服务器通信，以发出这些请求。对于 Windows 设备，安装脚本还会提供脱机安装选项。

此步骤是首次设置 IoT Edge 设备时对其进行配置的一次性过程。更新 IoT Edge 运行时时，也需要建立这些连接。
在设备上配置 IoT Edge 和容器运行时

IoT Edge 负责与 IoT 中心通信。容器运行时负责容器管理，因此会与容器注册表通信。这两个组件都需要通过代理服务器发出 Web 请求。

此步骤是首次设置 IoT Edge 设备时对其进行配置的一次性过程。
在设备上的配置文件中配置 IoT Edge 代理属性

IoT Edge 守护程序最初会启动 edgeAgent 模块。然后，edgeAgent 模块从 IoT 中心检索部署清单，并启动其他所有模块。在设备本身上手动配置 edgeAgent 模块环境变量，使 IoT Edge 代理能够与 IoT 中心建立初始连接。建立初始连接后，可以远程配置 edgeAgent 模块。

此步骤是首次设置 IoT Edge 设备时对其进行配置的一次性过程。
针对将来的所有模块部署设置环境变量，使任何模块都可以通过代理进行通信

设置 IoT Edge 设备并通过代理服务器将其连接到 IoT 中心后，需要在将来的所有模块部署中保持该连接。

此步骤是远程执行的持续过程，目的是在每次更换新模块或更新部署后，设备仍可通过代理服务器通信。

知道你的代理 URL

在开始执行本文中的任何步骤之前，需要知道你的代理 URL。

代理 URL 采用以下格式：protocol://proxy_host:proxy_port。

protocol 是 HTTP 或 HTTPS。 Docker 守护程序可以根据容器注册表设置使用任一协议，但 IoT Edge 守护程序和运行时容器应始终使用 HTTP 连接到代理。
proxy_host 是代理服务器的地址。如果代理服务器要求进行身份验证，则可采用 user:password@proxy_host 格式将凭据作为 proxy_host 的一部分提供。
proxy_port 是代理用来响应网络流量的网络端口。

通过代理安装 IoT Edge

无论 IoT Edge 设备是在 Windows 还是 Linux 上运行，都需要通过代理服务器访问安装包。请据所用的操作系统，遵循相应的步骤通过代理服务器安装 IoT Edge 运行时。

Linux 设备

若要在 Linux 设备上安装 IoT Edge 运行时，请将包管理器配置为通过代理服务器访问安装包。例如，设置 apt-get 以使用 http-proxy。配置包管理器后，请按照安装 Azure IoT Edge 运行时中的说明照常进行操作。

在 Windows 使用 Linux IoT Edge 的 Windows 设备

如果要在 Windows 上使用 Linux IoT Edge 安装 IoT Edge 运行时，则默认会在 Linux 虚拟机上安装 IoT Edge。无需安装或更新任何其他组件。

使用 Windows 容器的 Windows 设备

若要在 Windows 设备上安装 IoT Edge 运行时，需要两次通过代理服务器执行操作。第一个连接用于下载安装程序脚本文件，第二个连接用于在安装过程中下载必需的组件。可以在 Windows 设置中配置代理信息，或直接在 PowerShell 命令中包含代理信息。

以下步骤演示使用 -proxy 参数安装 Windows 的示例：

Invoke-WebRequest 命令需要获得代理信息才能访问安装程序脚本。然后，Deploy-IoTEdge 命令需要获得代理信息才能下载安装文件。
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
```
Initialize-IoTEdge 命令不需经过代理服务器，因此第二步仅需 Invoke-WebRequest 的代理信息。
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
```

如果你拥有不能包含在 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 }

有关代理参数的详细信息，请参阅 Invoke-WebRequest。

配置 IoT Edge 和 Moby

IoT Edge 依赖于 IoT Edge 设备上运行的两个守护程序。 Moby 守护程序发出 Web 请求，以从容器注册表中拉取容器映像。 IoT Edge 守护程序发出 Web 请求，以与 IoT 中心进行通信。

必须将 Moby 和 IoT Edge 守护程序配置为使用代理服务器持续获得设备功能。需在最初设置设备期间，在 IoT Edge 设备上执行此步骤。

Moby 守护程序

由于 Moby 是基于 Docker 的，因此若要使用环境变量配置 Moby 守护程序，请参阅 Docker 文档。大多数容器注册表（包括 DockerHub 和 Azure 容器注册表）支持 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 Edge 守护程序。

sudo systemctl edit aziot-edged

输入以下文本，将 <代理 URL> 替换为代理服务器地址和端口。然后，保存并退出。

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

从版本 1.2 开始，IoT Edge 使用 IoT 标识服务通过 IoT 中心或 IoT 中心设备预配服务来处理设备预配。在终端中打开编辑器，以配置 IoT 标识服务守护程序。

sudo systemctl edit aziot-identityd

输入以下文本，将 <代理 URL> 替换为代理服务器地址和端口。然后，保存并退出。

[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

在 Windows 上使用 Linux IoT Edge 的 Windows

登录到 IoT Edge for Linux on Windows 虚拟机：

Connect-EflowVm

按照本文 Linux 部分中的相同步骤配置 IoT Edge 守护程序。

使用 Windows 容器的 windows

以管理员身份打开 PowerShell 窗口，运行以下命令来使用新的环境变量编辑注册表。将 <代理 URL> 替换为代理服务器地址和端口。

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 参数添加到环境变量部分，并将代理 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>"

默认情况下，IoT Edge 运行时使用 AMQP 与 IoT 中心通信。某些代理服务器会阻止 AMQP 端口。如果是这种情况，则还需要将 edgeAgent 配置为使用基于 WebSocket 的 AMQP。将 UpstreamProtocol 参数取消注释。
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.4"

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

将 https_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>"

默认情况下，IoT Edge 运行时使用 AMQP 与 IoT 中心通信。某些代理服务器会阻止 AMQP 端口。如果是这种情况，则还需要将 edgeAgent 配置为使用基于 WebSocket 的 AMQP。将 UpstreamProtocol 参数取消注释。
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.4"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
保存更改并关闭编辑器。应用最新更改。
```
sudo iotedge config apply
```
验证代理设置是否使用 Env 部分中的 docker inspect edgeAgent 传播。如果不是，则必须重新创建容器。
```
sudo docker rm -f edgeAgent
```
IoT Edge 运行时应在一分钟内重新创建 edgeAgent。 edgeAgent 容器再次运行后，使用 docker inspect edgeAgent 命令验证代理设置是否与配置文件匹配。

配置部署清单

将 IoT Edge 设备配置为与代理服务器配合工作后，在将来的部署清单中声明 HTTPS_PROXY 环境变量。可以使用 Azure 门户向导或者通过编辑部署清单 JSON 文件，来编辑部署清单。

始终配置两个运行时模块（edgeAgent 和 edgeHub），以通过代理服务器进行通信，从而维持与 IoT 中心的连接。如果从 edgeAgent 模块中删除代理信息，重新建立连接的唯一方法是编辑设备上的配置文件，如上一部分所述。

除了 edgeAgent 和 edgeHub 模块外，其他模块也可能需要代理配置。需要访问 IoT 中心以外的 Azure 资源（例如 blob 存储）的模块必须已在部署清单文件中指定 HTTPS_PROXY 变量。

以下过程在 IoT Edge 设备的整个生命周期中适用。

Azure 门户

使用“设置模块”向导为 IoT Edge 设备创建部署时，每个模块都有一个可在其中配置代理服务器连接的“环境变量”部分。

若要配置 IoT Edge 代理和 IoT Edge 中心模块，请在向导的第一步中选择“运行时设置”。

Screenshot of how to configure advanced Edge Runtime settings.

将 https_proxy 环境变量添加到 IoT Edge 代理和 IoT Edge 中心模块定义。如果在 IoT Edge 设备上的配置文件中包括 UpstreamProtocol 环境变量，也请将该变量添加到 IoT Edge 代理模块定义。

Screenshot of how to set the https_proxy environment variable.

添加到部署清单的所有其他模块都遵循相同的模式。选择“应用”以保存所做的更改。

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.4",
        "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"
    }
}

使用流量检查代理

某些代理（如 Zscaler）可以检查 TLS 加密的流量。在 TLS 流量检查期间，代理返回的证书不是来自目标服务器的证书，而是由代理自己的根证书签名的证书。默认情况下，IoT Edge 模块（包括 edgeAgent 和 edgeHub）不信任此代理的证书，因此 TLS 握手会失败。

若要解决握手失败问题，请使用以下步骤将操作系统和 IoT Edge 模块都配置为信任代理的根证书。

在主机操作系统的受信任的根证书存储中配置代理证书。若要详细了解如何安装根证书，请参阅将根 CA 安装到 OS 证书存储。
通过引用信任捆绑包中的证书，将 IoT Edge 设备配置为通过代理服务器进行通信。若要详细了解如何配置信任捆绑包，请参阅管理受信任的根 CA（信任捆绑包）。

若要为不由 IoT Edge 管理的容器配置流量检查代理支持，请联系代理提供商。

与 IoT Edge 通信的目标的完全限定域名 (FQDN)

如果代理的防火墙要求将用于 Internet 连接的所有 FQDN 添加到允许列表，请查看允许从 IoT Edge 设备进行连接中的列表，以确定要添加哪些 FQDN。

后续步骤

了解有关 IoT Edge 运行时的角色详细信息。

使用 Azure IoT Edge 的常见问题和解决方法解决安装和配置错误