将 IoT Edge 设备配置为通过代理服务器进行通信Configure an IoT Edge device to communicate through a proxy server

IoT Edge 设备将发送 HTTPS 请求以与 IoT 中心进行通信。IoT Edge devices send HTTPS requests to communicate with IoT Hub. 如果设备已连接到使用代理服务器的网络,则需要将 IoT Edge 运行时配置为通过该服务器进行通信。If your device is connected to a network that uses a proxy server, you need to configure the IoT Edge runtime to communicate through the server. 如果代理服务器发出不通过 IoT Edge 中心路由的 HTTP 或 HTTPS 请求,则可能还会影响各个 IoT Edge 模块。Proxy servers can also affect individual IoT Edge modules if they make HTTP or HTTPS requests that aren't routed through the IoT Edge hub.

本文将引导你完成以下四个步骤,来配置并管理代理服务器后面的 IoT Edge 设备:This article walks through the following four steps to configure and then manage an IoT Edge device behind a proxy server:

  1. 在设备上安装 IoT Edge 运行时。Install the IoT Edge runtime on your device.

    IoT Edge 安装脚本从 Internet 提取包和文件,因此,设备需要通过代理服务器通信,以发出这些请求。The IoT Edge installation scripts pull packages and files from the internet, so your device needs to communicate through the proxy server to make those requests. 有关详细步骤,请参阅本文的通过代理安装运行时部分。For detailed steps, see the Install the runtime through a proxy section of this article. 对于 Windows 设备,安装脚本还会提供脱机安装选项。For Windows devices, the installation script also provides an Offline installation option.

    此步骤是首次设置 IoT Edge 设备时,在其上执行的一次性过程。This step is a one-time process performed on the IoT Edge device when you first set it up. 更新 IoT Edge 运行时时,也需要使用相同的连接。The same connections are also required when you update the IoT Edge runtime.

  2. 在设备上配置 Docker 守护程序和 IoT Edge 守护程序。Configure the Docker daemon and the IoT Edge daemon on your device.

    IoT Edge 使用设备上的两个守护程序,这些守护程序需要通过代理服务器发出 Web 请求。IoT Edge uses two daemons on the device, both of which need to make web requests through the proxy server. IoT Edge 守护程序负责与 IoT 中心通信。The IoT Edge daemon is responsible for communications with IoT Hub. Moby 守护程序负责容器管理,因此将与容器注册表通信。The Moby daemon is responsible for container management, so communicates with container registries. 有关详细步骤,请参阅本文的配置守护程序部分。For detailed steps, see the Configure the daemons section of this article.

    此步骤是首次设置 IoT Edge 设备时,在其上执行的一次性过程。This step is a one-time process performed on the IoT Edge device when you first set it up.

  3. 在设备上的 config.yaml 文件中配置 IoT Edge 代理属性。Configure the IoT Edge agent properties in the config.yaml file on your device.

    IoT Edge 守护程序最初会启动 edgeAgent 模块,然后,edgeAgent 模块将负责从 IoT 中心检索部署清单,并启动所有其他模块。The IoT Edge daemon starts the edgeAgent module initially, but then the edgeAgent module is responsible for retrieving the deployment manifest from IoT Hub and starting all the other modules. 要使 IoT Edge 代理能够与 IoT 中心建立初始连接,请在设备本身上手动配置 edgeAgent 模块环境变量。For the IoT Edge agent to make the initial connection to IoT Hub, configure the edgeAgent module environment variables manually on the device itself. 建立初始连接后,可以远程配置 edgeAgent 模块。After the initial connection, you can configure the edgeAgent module remotely. 有关详细步骤,请参阅本文的配置 IoT Edge 代理部分。For detailed steps, see the Configure the IoT Edge agent section of this article.

    此步骤是首次设置 IoT Edge 设备时,在其上执行的一次性过程。This step is a one-time process performed on the IoT Edge device when you first set it up.

  4. 针对将来的所有模块部署设置环境变量,使任何模块可以通过代理进行通信。For all future module deployments, set environment variables for any module communicating through the proxy.

    设置 IoT Edge 设备并通过代理服务器将其连接到 IoT 中心后,需要在将来的所有模块部署中保持该连接。Once your IoT Edge device is set up and connected to IoT Hub through the proxy server, you need to maintain the connection in all future module deployments. 有关详细步骤,请参阅本文的配置部署清单部分。For detailed steps, see the Configure deployment manifests section of this article.

    此步骤是远程执行的持续过程,目的是在每次更换新模块或更新部署后,设备仍可通过代理服务器通信。This step is an ongoing process performed remotely so that every new module or deployment update maintains the device's ability to communicate through the proxy server.

知道你的代理 URLKnow your proxy URL

在开始执行本文中的任何步骤之前,需要知道你的代理 URL。Before you begin any of the steps in this article, you need to know your proxy URL.

代理 URL 采用以下格式:protocol://proxy_host:proxy_portProxy URLs take the following format: protocol://proxy_host:proxy_port.

  • protocol 是 HTTP 或 HTTPS。The protocol is either HTTP or HTTPS. Docker 守护程序可以根据容器注册表设置使用任一协议,但 IoT Edge 守护程序和运行时容器应始终使用 HTTP 连接到代理。The Docker daemon can use either protocol, depending on your container registry settings, but the IoT Edge daemon and runtime containers should always use HTTP to connect to the proxy.

  • proxy_host 是代理服务器的地址。The proxy_host is an address for the proxy server. 如果代理服务器要求进行身份验证,则可采用 user:password@proxy_host 格式将凭据作为 proxy_host 的一部分提供。If your proxy server requires authentication, you can provide your credentials as part of the proxy host with the following format: user:password@proxy_host.

  • proxy_port 是代理用来响应网络流量的网络端口。The proxy_port is the network port at which the proxy responds to network traffic.

通过代理安装运行时Install the runtime through a proxy

无论 IoT Edge 设备是在 Windows 还是 Linux 上运行,都需要通过代理服务器访问安装包。Whether your IoT Edge device runs on Windows or Linux, you need to access the installation packages through the proxy server. 请据所用的操作系统,遵循相应的步骤通过代理服务器安装 IoT Edge 运行时。Depending on your operating system, follow the steps to install the IoT Edge runtime through a proxy server.

Linux 设备Linux devices

若要在 Linux 设备上安装 IoT Edge 运行时,请将包管理器配置为通过代理服务器访问安装包。If you're installing the IoT Edge runtime on a Linux device, configure the package manager to go through your proxy server to access the installation package. 例如,设置 apt-get 以使用 http-proxyFor example, Set up apt-get to use a http-proxy. 配置包管理器后,请按照在 Linux 上安装 Azure IoT Edge 运行时中的说明照常进行操作。Once your package manager is configured, follow the instructions in Install Azure IoT Edge runtime on Linux as usual.

Windows 设备Windows devices

若要在 Windows 设备上安装 IoT Edge 运行时,需要两次通过代理服务器执行操作。If you're installing the IoT Edge runtime on a Windows device, you need to go through the proxy server twice. 第一个连接用于下载安装程序脚本文件,第二个连接用于在安装过程中下载必需的组件。The first connection downloads the installer script file, and the second connection is during the installation to download the necessary components. 可以在 Windows 设置中配置代理信息,或直接在 PowerShell 命令中包含代理信息。You can configure proxy information in Windows settings, or include your proxy information directly in the PowerShell commands.

以下步骤演示使用 -proxy 参数安装 Windows 的示例:The following steps demonstrate an example of a windows installation using the -proxy argument:

  1. Invoke-WebRequest 命令需要获得代理信息才能访问安装程序脚本。The Invoke-WebRequest command needs proxy information to access the installer script. 然后,Deploy-IoTEdge 命令需要获得代理信息才能下载安装文件。Then the Deploy-IoTEdge command needs the proxy information to download the installation files.

    . {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
    
  2. Initialize-IoTEdge 命令不需经过代理服务器,因此第二步仅需 Invoke-WebRequest 的代理信息。The Initialize-IoTEdge command doesn't need to go through the proxy server, so the second step only requires proxy information for Invoke-WebRequest.

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

如果拥有不能包含在 URL 中的复杂代理服务器凭据,请使用 -InvokeWebRequestParameters 中的 -ProxyCredential 参数。If you have complicated credentials for the proxy server that can't be included in the URL, use the -ProxyCredential parameter within -InvokeWebRequestParameters. 例如,For example,

$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-WebRequestFor more information about proxy parameters, see Invoke-WebRequest. 有关 Windows 安装选项(包括脱机安装)的详细信息,请参阅在 Windows 上安装 Azure IoT Edge 运行时For more information about Windows installation options, including offline installation, see Install Azure IoT Edge runtime on Windows.

配置守护程序Configure the daemons

IoT Edge 依赖于 IoT Edge 设备上运行的两个守护程序。IoT Edge relies on two daemons running on the IoT Edge device. Moby 守护程序发出 Web 请求,以从容器注册表中拉取容器映像。The Moby daemon makes web requests to pull container images from container registries. IoT Edge 守护程序发出 Web 请求,以与 IoT 中心进行通信。The IoT Edge daemon makes web requests to communicate with IoT Hub.

Moby 和 IoT Edge 守护程序都需要配置为使用代理服务器持续获得设备功能。Both the Moby and the IoT Edge daemons need to be configured to use the proxy server for ongoing device functionality. 需在最初设置设备期间,在 IoT Edge 设备上执行此步骤。This step takes place on the IoT Edge device during initial device setup.

Moby 守护程序Moby daemon

由于 Moby 是基于 Docker 的,因此若要使用环境变量配置 Moby 守护程序,请参阅 Docker 文档。Since Moby is built on Docker, refer to the Docker documentation to configure the Moby daemon with environment variables. 大多数容器注册表(包括 DockerHub 和 Azure 容器注册表)支持 HTTPS 请求,因此,你应当设置的变量为 HTTPS_PROXYMost container registries (including DockerHub and Azure Container Registries) support HTTPS requests, so the parameter that you should set is HTTPS_PROXY. 如果要从不支持传输层安全性 (TLS) 的注册表中拉取映像,则应当设置 HTTP_PROXYIf you're pulling images from a registry that doesn't support transport layer security (TLS), then you should set the HTTP_PROXY parameter.

选择适用于 IoT Edge 设备操作系统的文章:Choose the article that applies to your IoT Edge device operating system:

IoT Edge 守护程序IoT Edge daemon

IoT Edge 守护程序以类似的方式配置为 Moby 守护程序。The IoT Edge daemon is configured in a similar manner to the Moby daemon. 使用以下步骤根据所使用的操作系统为服务设置环境变量。Use the following steps to set an environment variable for the service, based on your operating system.

IoT Edge 守护程序始终使用 HTTPS 将请求发送到 IoT 中心。The IoT Edge daemon always uses HTTPS to send requests to IoT Hub.

LinuxLinux

在终端中打开编辑器以配置 IoT Edge 守护程序。Open an editor in the terminal to configure the IoT Edge daemon.

sudo systemctl edit iotedge

输入以下文本,将 <proxy URL> 替换为代理服务器地址和端口。Enter the following text, replacing <proxy URL> with your proxy server address and port. 然后,保存并退出。Then, save and exit.

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

刷新服务管理器以选取 IoT Edge 的新配置。Refresh the service manager to pick up the new configuration for IoT Edge.

sudo systemctl daemon-reload

重新启动 IoT Edge 以使更改生效。Restart IoT Edge for the changes to take effect.

sudo systemctl restart iotedge

确认已创建环境变量并加载了新配置。Verify that your environment variable was created, and the new configuration was loaded.

systemctl show --property=Environment iotedge

WindowsWindows

以管理员身份打开 PowerShell 窗口,运行以下命令来使用新的环境变量编辑注册表。Open a PowerShell window as an administrator and run the following command to edit the registry with the new environment variable. 将 <proxy url> 替换为代理服务器地址和端口。Replace <proxy url> with your proxy server address and port.

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

重新启动 IoT Edge 以使更改生效。Restart IoT Edge for the changes to take effect.

Restart-Service iotedge

配置 IoT Edge 代理Configure the IoT Edge agent

IoT Edge 代理是在任意 IoT Edge 设备上启动的第一个模块。The IoT Edge agent is the first module to start on any IoT Edge device. 该代理基于 IoT Edge config.yaml 文件中的信息首次启动,It's started for the first time based on the information in the IoT Edge config.yaml file. IoT Edge 代理随后连接到 IoT 中心以检索部署清单,其中声明了应在设备上部署的其他模块。The IoT Edge agent then connects to IoT Hub to retrieve deployment manifests, which declare what other modules should be deployed on the device.

需在最初设置设备期间,在 IoT Edge 设备上执行此步骤一次。This step takes place once on the IoT Edge device during initial device setup.

  1. 打开 IoT Edge 设备上的 config.yaml 文件。Open the config.yaml file on your IoT Edge device. 在 Linux 系统上,此文件位于 /etc/iotedge/config.yaml。On Linux systems, this file is located at /etc/iotedge/config.yaml. 在 Windows 系统上,此文件位于 C:\ProgramData\iotedge\config.yaml。On Windows systems, this file is located at C:\ProgramData\iotedge\config.yaml. 配置文件是受保护的,因此,你需要管理权限才能对其进行访问。The configuration file is protected, so you need administrative privileges to access it. 在 Linux 系统上,请使用 sudo 命令,然后在偏好的文本编辑器中打开该文件。On Linux systems, use the sudo command before opening the file in your preferred text editor. 在 Windows 上,请以管理员身份打开记事本之类的文本编辑器,然后打开该文件。On Windows, open a text editor like Notepad as administrator and then open the file.

  2. 在 config.yaml 文件中,找到“Edge 代理模块规范”部分。In the config.yaml file, find the Edge Agent module spec section. IoT Edge 代理定义包括可以在其中添加环境变量的 env 参数。The IoT Edge agent definition includes an env parameter where you can add environment variables.

  3. 删除作为 env 参数占位符的大括号,并在新行上添加新变量。Remove the curly brackets that are placeholders for the env parameter, and add the new variable on a new line. 请记住,YAML 中的缩进为两个空格。Remember that indents in YAML are two spaces.

    https_proxy: "<proxy URL>"
    
  4. 默认情况下,IoT Edge 运行时使用 AMQP 与 IoT 中心通信。The IoT Edge runtime uses AMQP by default to talk to IoT Hub. 某些代理服务器会阻止 AMQP 端口。Some proxy servers block AMQP ports. 如果是这种情况,则还需要将 edgeAgent 配置为使用基于 WebSocket 的 AMQP。If that's the case, then you also need to configure edgeAgent to use AMQP over WebSocket. 添加第二个环境变量。Add a second environment variable.

    UpstreamProtocol: "AmqpWs"
    

    具有环境变量的 edgeAgent 定义

  5. 将更改保存到 config.yaml 并关闭编辑器。Save the changes to config.yaml and close the editor. 重新启动 IoT Edge 以使更改生效。Restart IoT Edge for the changes to take effect.

    • Linux:Linux:

      sudo systemctl restart iotedge
      
    • Windows:Windows:

      Restart-Service iotedge
      

配置部署清单Configure deployment manifests

将 IoT Edge 设备配置为与代理服务器配合使用后,还需要在将来的部署清单中声明 HTTPS_PROXY 环境变量。Once your IoT Edge device is configured to work with your proxy server, you need to continue to declare the HTTPS_PROXY environment variable in future deployment manifests. 可以使用 Azure 门户向导或者通过编辑部署清单 JSON 文件,来编辑部署清单。You can edit deployment manifests either using the Azure portal wizard or by editing a deployment manifest JSON file.

始终配置两个运行时模块(edgeAgent 和 edgeHub),以通过代理服务器进行通信,从而维持与 IoT 中心的连接。Always configure the two runtime modules, edgeAgent and edgeHub, to communicate through the proxy server so they can maintain a connection with IoT Hub. 如果从 edgeAgent 模块中删除了代理信息,则重新建立连接的唯一方法是根据前一部分中所述,编辑设备上的 config.yaml 文件。If you remove the proxy information from the edgeAgent module, the only way to reestablish connection is by editing the config.yaml file on the device, as described in the previous section.

除了 edgeAgent 和 edgeHub 模块外,其他模块也可能需要代理配置。In addition to the edgeAgent and edgeHub modules, other modules may need the proxy configuration. 这些模块需要访问 IoT 中心以外的 Azure 资源(例如 blob 存储),并且必须在部署清单文件中为该模块指定 HTTPS_PROXY 变量。These are modules that need to access Azure resources besides the IoT Hub, such as blob storage, and must have the HTTPS_PROXY variable specified for that module in the deployment manifest file.

以下过程在 IoT Edge 设备的整个生命周期中适用。The following procedure is applicable throughout the life of the IoT Edge device.

Azure 门户Azure portal

使用“设置模块”向导为 IoT Edge 设备创建部署时,每个模块都有可用于配置代理服务器连接的“环境变量”部分。When you use the Set modules wizard to create deployments for IoT Edge devices, every module has an Environment Variables section that you can use to configure proxy server connections.

若要配置 IoT Edge 代理和 IoT Edge 中心模块,请在向导的第一步中选择“运行时设置”。To configure the IoT Edge agent and IoT Edge hub modules, select Runtime Settings on the first step of the wizard.

配置 Edge 运行时高级设置

https_proxy 环境变量添加到 IoT Edge 代理和 IoT Edge 中心模块定义。Add the https_proxy environment variable to both the IoT Edge agent and IoT Edge hub module definitions. 如果在 IoT Edge 设备的 config.yaml 文件中包括 UpstreamProtocol 环境变量,也请将其添加到 IoT Edge 代理模块定义。If you included the UpstreamProtocol environment variable in the config.yaml file on your IoT Edge device, add that to the IoT Edge agent module definition too.

设置 https_proxy 环境变量

添加到部署清单的所有其他模块都遵循相同的模式。All other modules that you add to a deployment manifest follow the same pattern. 在设置模块名称和映像的页面中,具有环境变量部分。In the page where you set the module name and image, there is an environment variables section.

JSON 部署清单文件JSON deployment manifest files

如果使用 Visual Studio Code 中的模板或通过手动创建 JSON 文件来为 IoT Edge 设备创建部署,则可以将环境变量直接添加到每个模块定义。If you create deployments for IoT Edge devices using the templates in Visual Studio Code or by manually creating JSON files, you can add the environment variables directly to each module definition.

使用以下 JSON 格式:Use the following JSON format:

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

如果包括环境变量,模块定义应类似以下 edgeHub 示例:With the environment variables included, your module definition should look like the following edgeHub example:

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

如果在 IoT Edge 设备的 confige.yaml 文件中包括 UpstreamProtocol 环境变量,也请将其添加到 IoT Edge 代理模块定义。If you included the UpstreamProtocol environment variable in the confige.yaml file on your IoT Edge device, add that to the IoT Edge agent module definition too.

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

后续步骤Next steps

了解有关 IoT Edge 运行时的角色详细信息。Learn more about the roles of the IoT Edge runtime.

使用 Azure IoT Edge 的常见问题和解决方法解决安装和配置错误Troubleshoot installation and configuration errors with Common issues and resolutions for Azure IoT Edge