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

适用范围：IoT Edge 1.5 checkmark IoT Edge 1.5

IoT Edge设备发送 HTTPS 请求以与IoT Hub通信。 如果设备连接到使用代理服务器的网络，请将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 Hub的通信。 容器运行时管理容器并与容器注册表通信。 这两个组件都需要通过代理服务器发出 Web 请求。

   此步骤是在首次设置该设备时配置 IoT Edge 设备的一个一次性过程。

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

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

   此步骤是在首次设置该设备时配置 IoT Edge 设备的一个一次性过程。

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

   在设置 IoT Edge 设备并通过代理服务器连接到 IoT Hub 之后，在今后的所有模块部署中保持连接。

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

知道你的代理 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。 设置包管理器后，请按照 Install Azure IoT Edge runtime 中的说明进行操作。

在 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 Hub通信。

配置 Moby 和 IoT Edge 守护程序，使它们在设备持续运行中使用代理服务器。 在初始设置期间对IoT Edge设备执行此步骤。

Moby 守护程序

由于 Moby 是基于 Docker 构建的，因此请参阅 Docker 文档，以使用环境变量配置 Moby 守护程序。 大多数容器注册表（包括 DockerHub 和 Azure 容器注册表）都支持 HTTPS 请求，因此请设置 HTTPS_PROXY 参数。 如果要从不支持传输层安全性 (TLS) 的注册表中拉取映像，则应当设置 HTTP_PROXY。

选择适用于 IoT 边缘设备操作系统的文章：

• 在 Linux 上配置 Docker 守护程序 在 Linux 设备上，Moby 守护程序仍称为 Docker。
• 在 Windows 上配置 Docker 守护程序 Windows 设备上的 Moby 守护程序名为 iotedge-moby。 之所以让这些名称保持不同，是因为可能会在 Windows 设备上并行运行 Docker Desktop 和 Moby。

IoT Edge守护程序

IoT Edge守护程序类似于 Moby 守护程序。 使用以下步骤根据所使用的操作系统为服务设置环境变量。

IoT Edge守护程序始终使用 HTTPS 将请求发送到IoT Hub。

Linux

在终端中，打开编辑器以配置IoT Edge守护程序。

sudo systemctl edit aziot-edged

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

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

从版本 1.2 开始，IoT Edge使用 IoT 标识服务通过IoT Hub或IoT Hub设备预配服务来处理设备预配。 在终端中打开编辑器，以配置 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

利用适用于 Linux 的 IoT Edge 在 Windows 中运行

在 Windows 虚拟机上登录到适用于 Linux 的 IoT Edge：

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 Hub以检索部署清单。 清单将声明设备应部署其他哪些模块。

在初始设备设置期间，此步骤在IoT Edge设备上执行一次。

1. 打开IoT Edge设备上的配置文件：/etc/aziot/config.toml。 需要管理权限才能access配置文件。 在 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 Hub通信。 某些代理服务器会阻止 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. 保存更改并关闭编辑器。 应用更改。

   sudo iotedge config apply
   

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

   sudo docker rm -f edgeAgent
   

7. IoT Edge运行时在一分钟内重新创建 edgeAgent。 edgeAgent 容器再次运行后，使用 docker inspect edgeAgent 命令验证代理设置是否与配置文件匹配。

配置部署清单

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

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

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

此过程适用于IoT Edge设备的整个生命周期。

Azure 门户

使用 Set modules 向导为IoT Edge设备创建部署时，每个模块都有一个 Environment Variables 部分，可在其中配置代理服务器连接。

若要配置IoT Edge代理和IoT Edge中心模块，请在向导的第一步中选择 Runtime Settings。

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

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

JSON 部署清单文件

如果使用 Visual Studio Code 中的模板或手动创建 JSON 文件为IoT Edge设备创建部署，则可以将环境变量直接添加到每个模块定义。 如果未在Azure portal中添加它们，请在此处将其添加到 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.toml 文件中包括了 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 添加到 Internet 连接的允许列表，请查看来自 IoT Edge 设备的 Allow 连接的列表以确定要添加的 FQDN。

后续步骤

了解 IoT Edge 运行时的功能与角色。

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