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

适用于：IoT Edge 1.5

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

本文介绍在代理服务器后面配置和管理 IoT Edge 设备的四个步骤：

1. 在设备上安装 IoT Edge 运行时

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

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

2. 在设备上配置 IoT Edge 和容器运行时

   IoT Edge 处理与 IoT 中心的通信。 容器运行时管理容器并与容器注册表通信。 这两个组件都需要通过代理服务器发出 Web 请求。

   此步骤是首次设置 IoT Edge 设备时对其进行配置的一次性过程。

3. 在设备上的配置文件中配置 IoT Edge 代理属性

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

   此步骤是首次设置 IoT Edge 设备时对其进行配置的一次性过程。

4. 针对将来的所有模块部署设置环境变量，使任何模块都可以通过代理进行通信

   通过代理服务器设置 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_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 运行时，则默认情况下，IoT Edge 运行时安装在 Linux 虚拟机上。 无需安装或更新任何其他组件。

使用 Windows 容器的 Windows 设备

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

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

1. Invoke-WebRequest 命令需要获得代理信息才能访问安装程序脚本。 然后，Deploy-IoTEdge 命令需要获得代理信息才能下载安装文件。

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

2. Initialize-IoTEdge 命令不需经过代理服务器，因此第二步仅需 Invoke-WebRequest 的代理信息。

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

如果代理服务器凭据很复杂且不能包含在 URL 中，请使用 -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 }

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

配置 IoT Edge 和 Moby

IoT Edge 使用在 IoT Edge 设备上运行的两个守护程序。 Moby 守护程序从容器注册表中提取容器映像。 IoT Edge 守护程序与 IoT 中心通信。

配置 Moby 和 IoT Edge 守护程序以使用代理服务器，以保障设备功能的持续进行。 在初始设置期间在 IoT Edge 设备上执行此步骤。

Moby 守护程序

由于 Moby 是基于 Docker 构建的，因此请参阅 Docker 文档，以使用环境变量配置 Moby 守护程序。 大多数容器注册表（包括 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

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

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 设备上执行此步骤一次。

1. 打开 IoT Edge 设备上的配置文件 /etc/aziot/config.toml。 需要拥有管理特权才能访问配置文件。 在 Linux 系统上，请使用 sudo 命令，然后在偏好的文本编辑器中打开该文件。

2. 在该配置文件中，找到 [agent] 节，其中包含 edgeAgent 模块要在启动时使用的所有配置信息。 检查该 [agent] 部分是否没有注释。 如果缺少 [agent] 节，请将其添加到 config.toml。 IoT Edge 代理定义包括 [agent.env] 子节，可以在其中添加环境变量。

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

4. IoT Edge 运行时默认使用 AMQP 与 IoT 中心通信。 某些代理服务器会阻止 AMQP 端口。 如果是这种情况，则还需要将 edgeAgent 配置为使用基于 WebSocket 的 AMQP。 从 UpstreamProtocol 参数中删除注释。

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

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

6. 默认情况下，IoT Edge 运行时使用 AMQP 与 IoT 中心通信。 某些代理服务器会阻止 AMQP 端口。 如果是这种情况，则还需要将 edgeAgent 配置为使用基于 WebSocket 的 AMQP。 将 UpstreamProtocol 参数取消注释。

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

7. 保存更改并关闭编辑器。 应用更改。

   sudo iotedge config apply
   

8. 验证是否通过 Env 部分中的 docker inspect edgeAgent 应用了代理设置。 如果不是，则必须重新创建容器。

   sudo docker rm -f edgeAgent
   

9. 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 中心模块，请在向导的第一步中选择“运行时设置”。

将 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 设备的 config.yaml 文件中包括 UpstreamProtocol 环境变量，也请将其添加到 IoT Edge 代理模块定义。

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

使用流量检查代理

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

若要修复失败的握手，请设置操作系统和 IoT Edge 模块，以信任代理服务器的根证书，按照以下步骤进行操作。

1. 在主机操作系统的受信任根证书存储中设置代理证书。 若要详细了解如何安装根证书，请参阅将根 CA 安装到 OS 证书存储。

2. 通过引用信任捆绑包中的证书，将 IoT Edge 设备设置为通过代理服务器进行通信。 有关如何设置信任捆绑包的详细信息，请参阅管理受信任的根 CA（信任捆绑包）。

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

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

如果代理服务器的防火墙要求将所有 FQDN 添加到您的互联网连接的允许列表，请查看允许 IoT Edge 设备连接的列表，以确定要添加的 FQDN。

后续步骤

了解 IoT Edge 运行时的职能。

排查 Azure IoT Edge 的常见问题和解决方法中的安装和配置错误。