配置适用于网关层次结构方案的 API 代理模块

2025-08-16

适用于： IoT Edge 1.5

重要

IoT Edge 1.5 LTS 是受支持的版本。 IoT Edge 1.4 LTS 的生命周期结束日期为 2024 年 11 月 12 日。如果你使用的是较低的版本，请参阅更新 IoT Edge。

本文介绍 API 代理模块的配置选项，以便可以自定义模块以支持网关层次结构要求。

当多个服务使用 HTTPS 协议并绑定到端口 443 时，API 代理模块简化了 IoT Edge 设备的通信。此设置尤其适用于基于 ISA-95 的网络隔离体系结构中 IoT Edge 设备的分层部署，如网络隔离下游设备中所述的体系结构，因为下游设备上的客户端无法直接连接到云。

例如，让下游 IoT Edge 设备拉取 Docker 映像需要部署 Docker 注册表模块。让设备上传 Blob 需要在同一 IoT Edge 设备上部署 Azure Blob 存储模块。这两个服务都使用 HTTPS 进行通信。 API 代理模块在 IoT Edge 设备上启用这些部署。而不是每个服务都绑定到端口 443，API 代理模块绑定到主机设备上的端口 443，并根据用户可配置的规则将请求路由到运行在该设备上的正确服务模块。各个服务仍负责处理请求，包括对客户端进行身份验证和授权。

如果没有 API 代理，每个服务模块都必须绑定到主机设备上的单独端口，这需要在连接到父 IoT Edge 设备的每台子设备上进行繁琐且容易出错的配置更改。

注意

下游设备将数据直接发送到互联网或网关设备（启用或未启用 IoT Edge）。子设备可以是下游设备，也可以是嵌套拓扑中的网关设备。

部署代理模块

API 代理模块可从 Microsoft容器注册表（MCR）获取，映像 URI 为 mcr.microsoft.com/azureiotedge-api-proxy:latest。使用 Azure 门户或 Azure CLI 部署模块。

了解代理模块

API 代理模块使用 nginx 反向代理通过网络层路由数据。该模块具有嵌入式代理，因此模块映像需要支持代理配置。例如，如果代理侦听某个端口，模块需要打开该端口。

代理的开头为模块中嵌入的默认配置文件。将新的配置通过其模块孪生从云端传递到模块。还可以使用环境变量在部署时打开或关闭配置设置。

本文首先介绍了默认配置文件，以及如何使用环境变量启用其设置。然后说明如何自定义配置文件。

默认配置

API 代理模块附带了支持常见方案的默认配置，并允许对其进行自定义。通过模块的环境变量控制默认配置。

当前，默认环境变量包括：

环境变量	说明
`PROXY_CONFIG_ENV_VAR_LIST`	列出要在逗号分隔列表中更新的所有变量。此步骤有助于防止意外更改错误的配置设置。
`NGINX_DEFAULT_TLS`	设置要启用的 TLS 协议列表。参阅 NGINX 的 ssl_protocols。默认值为“TLSv1.2”。
`NGINX_DEFAULT_PORT`	更改 nginx 代理侦听的端口。如果更新此环境变量，请在模块 dockerfile 中公开端口并在部署清单中声明端口绑定。有关详细信息，请参阅公开代理端口。默认端口为 443。从 Azure 市场部署后，默认端口更改为 8000，以防止与 edgeHub 模块冲突。有关详细信息，请参阅最小化开放端口数。
`DOCKER_REQUEST_ROUTE_ADDRESS`	路由 docker 请求的地址。将顶层设备上的此变量修改为指向注册表模块。默认值为父主机名。
`BLOB_UPLOAD_ROUTE_ADDRESS`	路由 blob 注册表请求的地址。将顶层设备上的此变量修改为指向 blob 存储模块。默认值为父主机名。

最小化开放端口数

若要尽量减少打开的端口，请将 API 代理模块设置为中继所有 HTTPS 流量（端口 443），包括 edgeHub 模块的流量。默认情况下，API 代理模块在端口 443 上重新路由所有 edgeHub 流量。

按照以下步骤设置部署，以最大程度地减少打开的端口：

更新 edgeHub 模块设置，使其不会绑定到端口 443。否则，会导致端口绑定冲突。默认情况下，edgeHub 模块绑定到端口 443、5671 和 8883。删除端口 443 绑定，其余两个绑定不变：
```
{
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}
```
配置 API 代理模块，使其绑定在端口 443 上。
1. 将 NGINX_DEFAULT_PORT 环境变量的值设置为 443。
2. 更新容器创建选项以绑定到端口 443。
```
{
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}
```

如果不需要最小化打开的端口，请让 edgeHub 模块使用端口 443 并将 API 代理模块配置为侦听另一个端口。例如，将 NGINX_DEFAULT_PORT 环境变量 8000 配置为端口 8000 并创建端口绑定。

启用容器映像下载

API 代理模块的常见用例是让较低层中的 IoT Edge 设备提取容器映像。此方案使用 Docker 注册表模块从云中获取容器映像，并将其缓存在顶层。 API 代理将所有 HTTPS 请求中继，以将容器映像从较低层下载到顶层的注册表模块。

在此场景中，下游 IoT Edge 设备指向域名 $upstream ，然后是 API 代理模块的端口号，而不是映像的容器镜像存储库。例如，$upstream:8000/azureiotedge-api-proxy:1.1。

在教程使用网关创建 IoT Edge 设备的层次结构中演示了此用例。

在顶层配置以下模块：

Docker 注册表模块
- 为模块配置一个易记名称（如“注册表”），并公开该模块中的一个端口以接收请求。
- 配置要映射到容器注册表的模块。

API 代理模块

配置以下环境变量：

“属性”	“值”
`DOCKER_REQUEST_ROUTE_ADDRESS`	注册表模块名称和开放端口。例如，`registry:5000`。
`NGINX_DEFAULT_PORT`	Nginx 代理对其进行侦听以获取来自下游设备的请求的端口。例如，`8000`。

配置以下 createOptions：

{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

对于此方案，在任何较低层上配置以下模块：

API 代理模块。除底层设备外，所有下层设备都需要 API 代理模块。
- 配置以下环境变量：
  
  “属性” “值”
  
  NGINX_DEFAULT_PORT Nginx 代理对其进行侦听以获取来自下游设备的请求的端口。例如，8000。
- 配置以下 createOptions：
```
{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}
```

“属性”	“值”
`NGINX_DEFAULT_PORT`	Nginx 代理对其进行侦听以获取来自下游设备的请求的端口。例如，`8000`。

公开代理端口

默认情况下，端口 8000 从 Docker 映像公开。如果使用其他 nginx 代理端口，请添加 “公开端口 ”部分以声明部署清单中的端口。例如，如果将 nginx 代理端口更改为 8001，请将以下内容添加到部署清单：

{
   "ExposedPorts": {
      "8001/tcp": {}
   },
   "HostConfig": {
      "PortBindings": {
            "8001/tcp": [
               {
                  "HostPort": "8001"
               }
            ]
      }
   }
}

启用 blob 上传

API 代理模块的另一个用例是让较低层中的 IoT Edge 设备上传 Blob。此用例使你可以对较低层设备进行故障排除，例如上传模块日志或支持捆绑包。

此方案使用顶层的 IoT Edge 上的 Azure Blob 存储模块来处理 blob 创建和上载。在嵌套方案中，最多支持五个层。 IoT Edge 上的 Azure Blob 存储模块在顶层设备上是必需的，但对于较低层设备是可选的。有关多层部署的示例，请参阅用于工业 IoT 的 Azure IoT Edge 示例。

在顶层配置以下模块：

IoT Edge 上的 Azure Blob 存储模块。

API 代理模块

配置以下环境变量：

“属性”	“值”
`BLOB_UPLOAD_ROUTE_ADDRESS`	Blob 存储模块名称和开放端口。例如，`azureblobstorageoniotedge:11002`。
`NGINX_DEFAULT_PORT`	Nginx 代理对其进行侦听以获取来自下游设备的请求的端口。例如，`8000`。

配置以下 createOptions：

{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

对于此方案，在任何较低层上配置以下模块：

API 代理模块
- 配置以下环境变量：
  
  “属性” “值”
  
  NGINX_DEFAULT_PORT Nginx 代理对其进行侦听以获取来自下游设备的请求的端口。例如，8000。
- 配置以下 createOptions：
```
{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}
```

“属性”	“值”
`NGINX_DEFAULT_PORT`	Nginx 代理对其进行侦听以获取来自下游设备的请求的端口。例如，`8000`。

按照以下步骤将支持捆绑包或日志文件上传到顶层的 Blob 存储模块：

使用 Azure 存储资源管理器或 REST API 创建 Blob 容器。
按照从 IoT Edge 部署检索日志中的步骤请求日志或支持捆绑包上传，但使用域名 $upstream 和打开的代理端口，而不是 Blob 存储模块地址。例如：
```
{
   "schemaVersion": "1.0",
   "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
   "since": "2d",
   "until": "1d",
   "edgeRuntimeOnly": false
}
```

编辑代理配置

默认配置文件嵌入在 API 代理模块中，但可以通过模块双胞胎将新配置传递给模块。

编写自己的配置时，仍可以使用环境变量来调整每个部署的设置。使用以下语法：

用于 ${MY_ENVIRONMENT_VARIABLE} 获取环境变量的值。

使用条件语句根据环境变量的值启用或禁用设置：

#if_tag ${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 1
#endif_tag ${MY_ENVIRONMENT_VARIABLE}

#if_tag !${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 0
#endif_tag !${MY_ENVIRONMENT_VARIABLE}

当 API 代理模块解析代理配置时，它首先使用替换将 PROXY_CONFIG_ENV_VAR_LIST 中的所有环境变量替换为其值。然后，它将替换 #if_tag 和 #endif_tag 之间的范围。然后，该模块向 nginx 反向代理提供经过分析的配置。

若要动态更新代理配置，请执行以下步骤：

编写配置文件。将此默认模板用作参考： nginx_default_config.conf。
复制配置文件的文本，并将其转换为 base64。
将已编码的配置文件粘贴为模块孪生中 proxy_config 所需属性的值。