为 Azure Sphere 设置 Azure IoT Edge

重要

这是 Azure Sphere（旧版）文档。 Azure Sphere（旧版）将于 2027 年 9 月 27 日停用，用户此时必须迁移到 Azure Sphere（集成）。 使用位于 TOC 上方的版本选择器查看 Azure Sphere（集成）文档。

Azure IoT Edge 在下游设备（如 Azure Sphere 和 Azure IoT 中心）之间提供筛选和数据处理层。 如果 Azure Sphere 设备生成大量需要后期处理的数据或数据，请考虑使用 Azure IoT Edge。

本主题介绍使用 Azure Sphere 设置 Azure IoT Edge 设备的步骤。 Azure Sphere 支持 Azure IoT Edge 版本 1.1 和 1.2;说明中指出了重大差异。 主要差异在于：

• 包名称已从 iotedge 此更改为 aziot-edge。
• 默认配置文件具有新的名称和位置。 在 Azure IoT Edge 1.1 中，配置文件为 /etc/iotedge/config.yaml。 在 Azure IoT Edge 1.2 中，配置文件为 /etc/aziot/config.toml。
• Azure IoT Edge 1.2 需要通过网络上的 DNS 服务器访问的完全限定域名（FQDN）。

完成本主题中的任务后，Azure Sphere 设备将配置为通过充当透明网关的 Azure IoT Edge 设备将数据发送到Azure IoT 中心。 可以按照 Azure IoT Edge 模块指南在 Azure IoT Edge 设备上添加其他数据筛选和处理。

开始之前

本主题中的步骤假定：

• Azure Sphere 设备通过 USB 连接到电脑。
• 你有一个 Azure 订阅。
• 已创建Azure IoT 中心实例并手动预配设备。 请注意，在过程（步骤 6）的后面部分，需要为IoT 中心使用租户 CA 证书。
• 已创建资源组，与 Azure IoT 中心 和 IoT Edge 服务相关的所有资源都必须属于此资源组。

重要

虽然可以免费创建 Azure 订阅，但注册过程要求输入信用卡号。 Azure 提供多个级别的订阅服务。 默认情况下，在创建Azure IoT 中心实例时，会选择需要每月服务费的标准层。 若要避免每月收取费用，请选择免费层。 免费层包括将设备用于Azure IoT 中心实例（包括设备孪生）所需的服务。 如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

概述

设置 Azure IoT Edge 设备并将其配置为使用 Azure Sphere 设备需要一个多步骤过程，应该计划大约 8 小时才能完成这些步骤，尤其是不熟悉 Azure IoT Edge 时。 如果这是你第一次使用 Azure IoT Edge，请按照每个部分中的快速入门说明设置和配置在 Linux 虚拟机上运行的 IoT Edge 设备。

每个 Azure Sphere 租户和 Azure IoT Edge 设备必须仅完成一次这些步骤;但是，必须在Azure IoT 中心中手动配置每个 Azure Sphere 设备，并且必须将 Azure IoT Edge 设备设置为 Azure Sphere 设备的父设备。

设置步骤可以分为三个逻辑分组：

• 创建 IoT Edge 设备并将其配置为透明网关

  • 步骤 1. 创建 Azure IoT Edge 设备。
  • 步骤 2. 将 Azure IoT Edge 网关设备配置为服务器。
  • 步骤 3. 打开 Azure IoT Edge 网关设备端口进行通信。
  • 步骤 4. 更新 config.toml（Azure IoT Edge 版本 1.2）或 config.yaml（Azure IoT Edge 版本 1.1）中的网关主机名。

• 在 Azure IoT 中心 中配置 Azure Sphere 设备

  • 步骤 5。 将 Azure IoT Edge 设备设置为 Azure Sphere 设备的父级。

• 在 Azure Sphere 设备和 IoT Edge 设备之间建立受信任的连接

  • 步骤 6。 将 Azure Sphere 设备的租户 CA 证书提供给 Azure IoT Edge 设备。
  • 步骤 7. 将 Azure IoT Edge 设备的根 CA 证书提供给 Azure Sphere 设备。

步骤 1. 创建 Azure IoT Edge 设备

必须设置 Azure IoT Edge 设备并将其注册到Azure IoT 中心（如果尚未这样做）。

可以使用设备预配服务（DPS）来预配 Azure IoT Edge 设备。 但是，不能使用 DPS 预配 Azure Sphere 设备。 不支持使用 Azure IoT 中心 DPS 自动预配 Azure IoT Edge 设备下游的设备。

可以按照 IoT Edge 快速入门中的步骤设置在 Linux VM 或 Windows 设备上运行的 Azure IoT Edge 设备，并将其注册到Azure IoT 中心。

使用快速入门中的步骤可以：

• 将 Azure IoT Edge 设备注册到Azure IoT 中心实例。 不要在此步骤中创建新的 IoT 中心，只需将 Azure IoT Edge 设备注册到已创建的 IoT 中心。
• 在 Azure IoT Edge 设备上安装和启动 Azure IoT Edge 运行时。

注意

在 IoT Edge 快速入门中，在部署模块之前停止。

步骤 2. 将 IoT Edge 网关设备配置为服务器

按照说明配置 Azure IoT Edge 设备以充当透明网关（Azure IoT Edge 1.2） 或 Azure IoT Edge 1.1，但在到达“打开网关设备上的端口”部分时停止。尽管这些说明告诉你将证书文件复制到 IoT Edge 设备，但在此过程的第 8 步之前，不要将文件复制到 VM。

在完成将设备网关配置为服务器的步骤中，你已具备：

• 配置了 Azure IoT Edge 设备证书。
• 部署了 Azure IoT Edge 中心模块。
• 通过 Azure IoT Edge 配置了消息路由。

此外，在这些步骤中，还将创建以下证书：

• 根 CA 证书： certs/azure-iot-test-only.root.ca.cert.pem
• 设备 CA 证书和私钥（用于将 IoT Edge 设备注册到IoT 中心）：
  • certs/iot-edge-device-identity-<cert-name>-full-chain.cert.pem
  • private/iot-edge-device-identity-<cert-name>.key.pem
• IoT Edge CA 证书和私钥（要复制到 IoT Edge 设备并在配置文件中引用）：
  • certs/iot-edge-device-ca-<cert-name>-full-chain.cert.pem
  • private/iot-edge-device-ca-<cert-name>.key.pem

如果遵循快速入门，请使用 Linux 说明配置演示证书（如果生成证书的计算机是基于 Linux 的计算机）。 如果生成证书的计算机是基于 Windows 的计算机，请使用 Windows 说明生成演示证书。 请参阅此部分，将 根证书复制到 Linux VM 或本地 Windows 计算机。

Azure IoT Edge 根 CA 证书将在步骤 7 中修改，但步骤 8 中需要原始证书。 保留原始证书的副本，以便重复使用它。

注意

更新 config.toml（Azure IoT Edge 1.2）或 config.yaml（Azure IoT Edge 1.1） 文件的证书部分时，请确保 certificates: config.toml（Azure IoT Edge 1.2）或 config.yaml（Azure IoT Edge 1.1）中的行没有前面的空格，并且每个嵌套证书都缩进两个空格。

更新文件后，验证 Edgehub 模块是否在 Azure IoT Edge 设备上运行：

sudo iotedge list

有关详细信息，请参阅 如何将 IoT Edge 设备用作网关（Azure IoT Edge 1.2） 或 Azure IoT Edge 1.1。

如果使用测试证书，请在生成下游设备证书之前停止，如“创建下游设备证书”（Azure IoT Edge 1.2）或 Azure IoT Edge 1.1 中所述。

步骤 3. 打开 Azure IoT Edge 网关设备端口进行通信

网关设备必须能够从其下游设备接收消息。 若要使网关方案正常工作，必须为来自下游设备的入站流量打开至少一个 IoT 中心支持的协议。

Azure Sphere 使用协议 MQTT。 此协议使用端口 8883。

有关详细信息，请参阅 网关设备上的开放端口（Azure IoT Edge 1.2） 或 Azure IoT Edge 1.1。

在快速入门中设置 Edge 设备后，请按照以下步骤在 Windows VM 上打开端口 8883：

1. 如有必要，请使用 Azure 帐户登录到Azure 门户。
2. 导航到在步骤 1：创建 Azure IoT Edge 设备部分中创建的虚拟机。
3. 在左侧的“设置”部分中，选择“网络”，然后选择“添加入站端口规则”。
4. 在“添加入站端口规则”边栏选项卡中，在“目标端口范围”下，将值更改为 8883。
5. 在“协议”下，选择“TCP”。
6. 在“名称”下，将值更改为 MQTT。
7. 将所有其他设置保留为默认值，然后选择“ 添加”。

按照以下步骤在快速入门中设置 Azure IoT Edge 设备后，在 Linux VM 上打开端口 8883：

1. 运行以下命令，检查 MQTT 的端口是否已打开：

   sudo netstat -lptu

2. 如有必要，请使用以下命令打开端口：

   sudo ufw allow 8883

这将定义入站安全规则，以允许 MQTT 协议与 Azure IoT Edge 网关通信。

步骤 4. 更新网关主机名

此步骤根据所使用的 Azure IoT Edge 版本使用不同的过程： Azure IoT Edge 1.2 或 Azure IoT Edge 1.1。

Azure IoT Edge 1.2：在 config.toml 中更新网关主机名

Azure IoT Edge 运行时支持少于 64 个字符的主机名。 物理计算机通常没有较长的主机名，但如果使用虚拟机作为 Azure IoT Edge 设备，如快速入门中的示例，则必须手动配置主机名。

若要排查无效主机名问题，请参阅 常见的错误解决方法。

在快速入门中配置 MQTT 端口后，请按照以下步骤配置 Azure IoT Edge 设备主机名：

1. 通过在 Azure 门户中导航到 IoT Edge 设备（Linux VM），并从概述页复制 DNS 名称的值，查找 IoT Edge 网关的完全限定域名（FQDN）。

2. 如有必要，请登录到 Azure IoT Edge 设备。

3. 在文本编辑器中打开 config.toml 文件。

   /etc/aziot/config.toml

4. 将 FQDN 粘贴到 config.toml 的主机名部分。 确保该名称全部小写。

   hostname: "<iotedge_machinename>.<mydomain>"
   

   注意

   根据 Azure IoT Edge v1.2 及更高版本的设计， 主机名 必须是 FQDN 名称（不再允许 IP 地址，如 v1.1 中）;因此，必须在同一网络上具有相应 A 记录的 DNS 服务器。

5. 重新启动 iotedge 守护程序。

   sudo systemctl restart iotedge

6. 如果在状态中看到了错误（带“[ERROR]”前缀的彩色文本），请检查守护程序日志以了解详细错误信息。

   sudo journalctl -u iotedge --no-pager --no-full

7. 若要避免警告，请在 Azure IoT Edge 设备上设置模块的 DNS 配置，以在 /etc/docker/daemon.json 中包含配置文件，例如：

   {
        "dns": ["<IP address of your DNS server>"]
   }
   

Azure IoT Edge 1.1：在 config.yaml 中更新网关主机名

Azure IoT Edge 运行时支持少于 64 个字符的主机名。 物理计算机通常没有较长的主机名，但如果使用虚拟机作为 Azure IoT Edge 设备，如快速入门中的示例，则必须手动配置主机名。

若要排查无效主机名问题，请参阅 常见的错误解决方法。

在快速入门中配置 MQTT 端口后，请按照以下步骤配置 Azure IoT Edge 设备主机名：

1. 在 Azure 门户中，导航到你的虚拟机。 从“概述”部分复制 DNS 名称（计算机 FQDN）的值。

2. 如有必要，请登录到 Azure IoT Edge 设备。

3. 在文本编辑器中打开 config.yaml 文件。

   /etc/iotedge/config.yaml

4. 将 FQDN 粘贴到 config.yaml 的主机名部分。 确保该名称全部小写。

   `hostname: "<machinename>.<region>.cloudapp.azure.com"`
   

   注意

   如果 DNS 解析程序位于网络上，则可能必须使用主机名（IP 地址或实际主机名）的裸机名称，因为 Azure Sphere 不支持 netbios。

5. 重新启动 iotedge 守护程序。

   sudo systemctl restart iotedge

6. 如果在状态中看到了错误（带“[ERROR]”前缀的彩色文本），请检查守护程序日志以了解详细错误信息。

   sudo journalctl -u iotedge --no-pager --no-full

7. 若要避免警告，请在 Azure IoT Edge 设备上设置模块的 DNS 配置，以在 /etc/docker/daemon.json 中包含配置文件，例如：

   {
       "dns": ["<IP address of your DNS server>"]
   }
   

步骤 5。 将 Azure IoT Edge 设备设置为 Azure Sphere 设备的父设备

按照以下步骤将 Azure IoT Edge 设备设置为 Azure Sphere 设备的父级：

1. 导航到上面手动预配的 Azure Sphere 设备。
2. 选择设备 ID。
3. 选择“无父设备”下的齿轮图标。
4. 选择要设置为父级的 Azure IoT Edge 设备。
5. 选择“确定”，然后选择“保存”。

Azure IoT Edge 设备现在成为 Azure Sphere 设备的父级。

步骤 6。 将 Azure Sphere 设备的租户 CA 证书提供给 IoT Edge 设备

若要验证 Azure Sphere 设备证书，Azure IoT Edge 设备必须有自己的租户 CA 副本。

1. 下载租户 CA 证书（如果尚未这样做）。 注意：在配置Azure IoT 中心过程中，应已完成此操作。

   • 在命令提示符处，使用 Azure Sphere 登录名登录：

     azsphere login
     

   • 下载 Azure Sphere 租户的 CA 证书。 此命令将证书下载到当前工作目录中名为 CAcertificate.cer 的文件。 确保将文件下载到具有写入权限的目录，否则下载操作将失败。 输出文件必须具有.cer扩展名。

     Azure Sphere CLI

     azsphere ca-certificate download --destination CAcertificate.cer
     

     Azure Sphere 经典 CLI

     azsphere ca-certificate download --output CAcertificate.cer
     

     注意

     Azure Sphere 经典 CLI 即将停用。 建议使用 Azure Sphere（集成）。

2. 将租户 CA 证书转换为 PEM 格式。 有关在 Windows 计算机上转换格式的示例说明如下：

   • 在计算机上找到证书的路径，然后双击证书将其打开。
   • 打开“ 详细信息 ”选项卡，然后选择“ 复制到文件”。
   • 在“证书导出”向导中，选择“下一步”。
   • 选择 Base-64 编码的 X.509 （CER） 格式，然后选择“ 下一步”。
   • 输入要导出的证书的文件名，然后选择“ 下一步”。
   • 选择完成以完成向导。
   • 将下载的证书文件重命名为扩展名为 .pem。

3. 将租户证书追加到 Azure IoT Edge 根证书。 请记住，在步骤 2 中创建 Azure IoT Edge 证书。

   • 如有必要，请登录到 Azure IoT Edge 设备。
   • 找到 IoT Edge 设备的根 CA 证书的路径，并在文本编辑器中打开它。 如果遵循快速入门，则使用 Azure IoT Edge git 存储库中提供的脚本创建演示证书，则根 CA 证书名为 azure-iot-test-only.root.ca.cert.pem。
   • 在文本编辑器中打开 Azure Sphere 租户 CA 证书（采用 PEM 格式）。 复制内容并将其粘贴到 IoT Edge 根 CA 证书的末尾。
   • 保存对 Azure IoT Edge 根 CA 证书所做的更改，然后关闭该文件。
   • 重启 Azure IoT Edge 设备。 对于 Linux Azure IoT Edge 设备，请运行： sudo systemctl restart iotedge
   • 验证模块是否在 Azure IoT Edge 设备上运行。 对于 Linux Azure IoT Edge 设备，请运行： sudo iotedge list

步骤 7. 将 Azure IoT Edge 设备的根 CA 证书提供给 Azure Sphere 设备

若要验证 Azure IoT Edge 设备证书，Azure Sphere 设备（下游设备）必须拥有在步骤 2 中配置的 Azure IoT Edge 设备根 CA 证书的副本。

有关详细信息，请参阅 将下游设备连接到 Azure IoT Edge 网关。

1. 找到原始 Azure IoT Edge 设备根证书。

   • 请记住，原始 Azure IoT Edge 设备根证书是在步骤 2 中创建的证书。
   • 如果遵循快速入门，然后使用 IoT Edge git 存储库中提供的脚本创建演示证书，则根 CA 证书称为 azure-iot-test-only.root.ca.cert.pem。

2. 通过将 Azure IoT Edge 根证书添加到应用程序包，将 Azure IoT Edge 根证书复制到 Azure Sphere 设备。

   • 有关详细步骤，请参阅 映像包创建。
   • 请参阅此部分，将 根证书复制到 Linux VM 或本地 Windows 计算机。

步骤 8。 将 IoT 根证书复制到远程计算机

按照以下步骤将 Azure IoT Edge 根证书复制到远程 Linux VM 或本地 Windows 计算机：

• 可以安装 WinSCP 工具 来传输文件。 该工具提供 GUI，因此比命令行方法更易于使用。

• 若要使用命令行，请使用 SCP（安全复制）命令行工具。

• 若要将文件从本地 Windows 计算机传输到远程 Linux VM，请在 Windows PowerShell 中运行以下命令：

  powershell -Command scp -r <path-to-file-name> <userName@remote-ip>:<path-to-destination-directory>
  

  示例语法：

  scp C:\Documents\cert.pem AzureUser@edgevmname-west.westus22.cloudapp.azure.com:/home/azureUser/test/

• 若要将文件从远程 Linux VM 传输到本地 Windows 计算机，请在 Windows PowerShell 中运行以下命令：

  powershell -Command scp -r <userName@remote-ip>:<path-to-file-name> <path-to-destination-dir>
  

  示例语法：

  scp azureUser@edgevmname-west.westus22.cloudapp.azure.com:/home/azureUser/test/cert.pem C:\Documents\

故障排除

如果在环境中运行 Azure IoT Edge 时遇到问题，请使用以下文章进行故障排除和诊断：

• 对 IoT Edge 设备（Azure IoT Edge 1.2） 或 Azure IoT Edge 1.1 进行故障排除

• Azure IoT Edge（Azure IoT Edge 1.2） 或 Azure IoT Edge 1.1 的常见问题和解决方法

后续步骤

• 完成本主题中的步骤后，可以按照有关使用 Azure IoT Edge 进行连接的说明运行 Azure IoT 示例。