使用对称密钥在 Linux 上大规模创建和预配 IoT Edge 设备

项目
2025/05/30

适用于： IoT Edge 1.5

重要

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

本文提供了使用对称密钥设置一个或多个 Linux IoT Edge 设备的分步说明。使用 Azure IoT 中心设备预配服务（DPS）自动设置 Azure IoT Edge 设备。如果不熟悉自动预配过程，请在继续之前查看预配概述。

以下是主要任务：

为单个设备创建 单个注册 ，或为一组设备创建 组注册 。
安装 IoT Edge 运行时并连接到 IoT 中心。

提示

为了简单起见，请尝试使用 Azure IoT Edge 配置工具。此命令行工具目前以公共预览版提供，可在设备上安装 IoT Edge，并使用 DPS 和对称密钥证明来预配它。

对称密钥证明是使用设备预配服务实例对设备进行身份验证的简单方法。此方法是面向不熟悉设备预配或没有严格安全要求的开发人员的“Hello world”体验。使用 TPM 或 X.509 证书进行设备证明更安全，应将其用于更严格的安全需求。

先决条件

云资源

一个活动的 IoT 中心
Azure 中的一个 IoT 中心设备预配服务实例，该实例已链接到 IoT 中心
- 如果没有设备预配服务实例，则可按照 IoT 中心设备预配服务快速入门的创建新的 IoT 中心设备预配服务和将 IoT 中心和设备预配服务相链接部分的说明进行操作。
- 运行设备预配服务后，从概述页复制“ID 范围”的值。配置 IoT Edge 运行时时，需要使用此值。

设备要求

使用物理或虚拟 Linux 设备作为 IoT Edge 设备。

定义一个唯一的注册 ID 来标识每个设备。使用设备的 MAC 地址、序列号或任何唯一信息。例如，组合 MAC 地址和序列号以形成注册 ID，例如 sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6。有效字符为小写字母数字和短划线 (-)。

创建 DPS 注册

创建注册以通过 DPS 预配一个或多个设备。

如果要预配单个 IoT Edge 设备，请创建单个注册。如果需要预配多个设备，请按照创建 DPS 组注册的步骤进行操作。

在 DPS 中创建注册时，可以声明“初始设备孪生状态”。在设备孪生中可以设置标记，以便按解决方案中所需的任何指标（例如区域、环境、位置或设备类型）将设备分组。这些标记用于创建自动部署。

有关设备预配服务中的注册的详细信息，请参阅如何管理设备注册。

单独注册
组注册

创建 DPS 单独注册

提示

本文中的步骤适用于 Azure 门户，但你也可使用 Azure CLI 创建单个注册。有关详细信息，请参阅 az iot dps enrollment。作为 CLI 命令的一部分，使用 edge-enabled 标志指定注册适用于单个 IoT Edge设备。

在 Azure 门户中，导航到 IoT 中心设备预配服务实例。
在“设置”下，选择“管理注册”。
选择“添加个人注册”，然后完成以下步骤以配置注册：
1. 对于“机制”，请选择“对称密钥”。
2. 为设备提供一个唯一的注册 ID。
3. （可选）为设备提供一个 IoT 中心设备 ID。可以使用设备 ID 将单个设备指定为模块部署的目标。如果未提供设备 ID，则会使用注册 ID。
4. 选择“True”，声明该注册适用于 IoT Edge 设备。
5. （可选）向“初始设备孪生状态”添加一个标记值。可以使用标记将设备组指定为模块部署的目标。例如：
```
{
   "tags": {
      "environment": "test"
   },
   "properties": {
      "desired": {}
   }
}
```
6. 选择“保存” 。
复制个人注册的“主密钥”值，以便在安装 IoT Edge 运行时的情况下使用。

既然此设备已存在注册，IoT Edge 运行时在安装期间可以自动预配设备。

创建 DPS 组注册

提示

本文中的步骤适用于 Azure 门户，但你也可使用 Azure CLI 创建组注册。有关详细信息，请参阅 az iot dps enrollment-group。作为 CLI 命令的一部分，使用 edge-enabled 标志指定注册适用于一组 IoT Edge设备。对于组注册，所有设备必须是 IoT Edge 设备，或者都不是 IoT Edge 设备。

在 Azure 门户中，导航到 IoT 中心设备预配服务实例。
在“设置”下，选择“管理注册”。
选择“添加个人注册”，然后完成以下步骤以配置注册：
1. 提供组名称。
2. 选择“对称密钥”作为证明类型。
3. 选择“True”，声明该注册适用于 IoT Edge 设备。对于组注册，所有设备必须是 IoT Edge 设备，或者都不是 IoT Edge 设备。
4. （可选）向“初始设备孪生状态”添加一个标记值。可以使用标记将设备组指定为模块部署的目标。例如：
```
{
   "tags": {
      "environment": "test"
   },
   "properties": {
      "desired": {}
   }
}
```
5. 选择“保存” 。
复制注册组的“主密钥”值，以便在创建用于组注册的设备密钥时使用。

现在注册组已经存在，IoT Edge 运行时在安装期间可以自动预配设备。

派生一个设备密钥

在组注册过程中预配的每个设备都需要一个派生的设备密钥，用于在预配期间向注册执行对称密钥证明。

若要生成设备密钥，请使用从 DPS 注册组复制的密钥来计算设备的唯一注册 ID 的 HMAC-SHA256，并将结果转换为 Base64 格式。

重要

不要在设备代码中包含注册的主密钥或辅助密钥。

在 Windows 上，可以使用 PowerShell 生成派生的设备密钥，如以下示例中所示。

将“键” 值替换为前面记录的“主键” 。

请将 REG_ID 值替换为设备的注册 ID。

$KEY='PASTE_YOUR_ENROLLMENT_KEY_HERE'
$REG_ID='PASTE_YOUR_REGISTRATION_ID_HERE'

$hmacsha256 = New-Object System.Security.Cryptography.HMACSHA256
$hmacsha256.key = [Convert]::FromBase64String($KEY)
$sig = $hmacsha256.ComputeHash([Text.Encoding]::ASCII.GetBytes($REG_ID))
$derivedkey = [Convert]::ToBase64String($sig)
echo "`n$derivedkey`n"

下面是派生设备密钥的输出示例：

Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc=

安装 IoT Edge

在本部分，你将准备 IoT Edge 的 Linux 虚拟机或物理设备。然后安装 IoT Edge。

运行以下命令以添加包存储库，然后将 Azure 包签名密钥添加到你的受信任密钥列表中。

重要

2022 年 6 月 30 日，Raspberry Pi OS Stretch 已从第 1 层 OS 支持列表中停用。若要避免潜在的安全漏洞，请将主机 OS 更新为 Bullseye。

对于支持第 2 层的平台操作系统，Azure IoT Edge 版本中提供了安装包。请参阅脱机安装或特定版本安装中的安装步骤（可选）。

安装可通过几个命令来完成。打开终端并运行以下命令：

24.04：

wget https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

22.04：

wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

20.04：

wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

使用 APT 进行安装可通过几个命令来完成。打开终端并运行以下命令：

12 - Bookworm (arm32v7)：

curl https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
sudo apt install ./packages-microsoft-prod.deb

11 - Bullseye (arm32v7)：

curl https://packages.microsoft.com/config/debian/11/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
sudo apt install ./packages-microsoft-prod.deb

提示

如果在 OS 安装过程中为“root”帐户提供了密码，则不需要“sudo”，并且可以通过从“apt”开始运行上一个命令。

安装可通过几个命令来完成。打开终端并运行以下命令：

9.x (amd64)：

  wget https://packages.microsoft.com/config/rhel/9.0/packages-microsoft-prod.rpm -O packages-microsoft-prod.rpm
  sudo yum localinstall packages-microsoft-prod.rpm
  rm packages-microsoft-prod.rpm

8.x (amd64)：

  wget https://packages.microsoft.com/config/rhel/8/packages-microsoft-prod.rpm -O packages-microsoft-prod.rpm
  sudo yum localinstall packages-microsoft-prod.rpm
  rm packages-microsoft-prod.rpm

有关操作系统版本的详细信息，请参阅 Azure IoT Edge 支持的平台。

备注

Azure IoT Edge 软件包受制于每个包（usr/share/doc/{package-name} 或 LICENSE 目录）中的许可条款。使用包之前，请先阅读许可条款。安装和使用包即表示你接受这些条款。如果你不同意许可条款，请不要使用该包。

安装容器引擎

Azure IoT Edge 依赖于 OCI 兼容的容器运行时。对于生产方案，建议使用 Moby 引擎。 Moby 引擎是官方支持用于 IoT Edge 的容器引擎。 Docker CE/EE 容器映像与 Moby 运行时兼容。如果使用的是 Ubuntu Core Snap 应用，则 Docker Snap 应用由 Canonical 提供支持，并适用于生产环境。

安装 Moby 引擎。

sudo apt-get update; \
  sudo apt-get install moby-engine

安装 Moby 引擎。

sudo apt-get update; \
  sudo apt-get install moby-engine

安装 Moby 引擎和 CLI。

sudo yum install moby-engine moby-cli

提示

如果在安装 Moby 容器引擎时出现错误，请验证 Linux 内核的 Moby 兼容性。有些嵌入式设备制造商寄送的设备映像包含的自定义 Linux 内核没有确保容器引擎兼容所需的功能。运行以下命令，该命令使用 Moby 提供的 check-config 脚本来检查内核配置：

curl -ssl https://raw.githubusercontent.com/moby/moby/master/contrib/check-config.sh -o check-config.sh
chmod +x check-config.sh
./check-config.sh

在该脚本的输出中，检查 Generally Necessary 和 Network Drivers 下的所有项是否都已启用。如果缺少某些功能，请启用它们，方法是通过源重新构建内核，然后选择关联的模块，将其包括在相应的内核 .config 中。同样，如果使用内核配置生成器（例如 defconfig 或 menuconfig），请找到并启用相应的功能，然后以相应方式重新构建内核。部署新修改的内核后，再次运行 check-config 脚本，验证是否已成功启用所有必需的功能。

IoT Edge 依赖于 Docker 和 IoT 标识服务。使用以下命令安装依赖项：

sudo snap install docker
sudo snap install azure-iot-identity

Docker snap 由 Canonical 提供服务，并支持将其用于生产场景中。

默认情况下，容器引擎不会设置容器日志大小限制。随着时间的推移，这种情况可能会导致设备填满日志并耗尽磁盘空间。但是，你可以将日志配置为在本地显示，不过这是可选操作。若要了解有关日志记录配置的详细信息，请参阅准备在生产环境中部署 IoT Edge 解决方案。

以下步骤说明如何将容器配置为使用 local 日志记录驱动程序作为日志记录机制。

Ubuntu / Debian / RHEL
Ubuntu 核心 snap

创建或编辑现有 Docker 守护程序的配置文件
```
sudo nano /etc/docker/daemon.json
```
将默认日志记录驱动程序设置为 local 日志记录驱动程序，如示例中所示。
```
   {
      "log-driver": "local"
   }
```
重启容器引擎以使更改生效。
```
sudo systemctl restart docker
```

安装 IoT Edge 运行时

IoT Edge 服务在 IoT Edge 设备上提供并维护安全标准。该服务在每次开机时启动，并通过启动 IoT Edge 运行时的其余部分来启动设备。

备注

从版本 1.2 开始， Azure IoT 标识服务将处理 IoT Edge 的标识预配和管理，以及需要与 IoT 中心通信的其他设备组件。

本部分中的步骤表示在可连接 Internet 的设备上安装最新 IoT Edge 版本的典型过程。如果需要安装特定版本（如预发行版版本）或在脱机时需要安装，请按照本文后面的 脱机或特定版本安装 步骤作。

提示

如果已有运行较旧版本的 IoT Edge 设备，并且想要升级到最新版本，请使用 Update IoT Edge 中的步骤。最新版本与先前的 IoT Edge 版本有很大不同，因此需要采取特定的步骤进行升级。

安装最新版本的 IoT Edge 和 IoT 标识服务包（如果不是最新版本）：

22.04：

sudo apt-get update; \
   sudo apt-get install aziot-edge

20.04：

sudo apt-get update; \
   sudo apt-get install aziot-edge

安装最新版本的 IoT Edge 和 IoT 标识服务包（如果不是最新版本）：

sudo apt-get update; \
  sudo apt-get install aziot-edge

安装最新版本的 IoT Edge 和 IoT 标识服务包（如果不是最新版本）：

sudo yum install aziot-edge

从 snap store 安装 IoT Edge：

sudo snap install azure-iot-edge

连接 snap

默认情况下，snap 无依赖项、不受信任且严格受限。因此，安装之后，snap 必须连接到其他 snap 和系统资源。使用以下命令将 IoT 标识服务和 IoT Edge snap 彼此相连并连接到系统资源。若要开始操作，需要手动连接 snap。对于生产部署，可以将其配置为自动连接以减少预配工作负载。

#------------------------
# IoT Identity Service
#------------------------

# Connect the Identity Service snap to the logging system
# and grant permission to query system info

sudo snap connect azure-iot-identity:log-observe
sudo snap connect azure-iot-identity:mount-observe
sudo snap connect azure-iot-identity:system-observe
sudo snap connect azure-iot-identity:hostname-control

# If using a TPM, enable TPM access

sudo snap connect azure-iot-identity:tpm

#------------
# IoT Edge
#------------

# Connect to your /home directory to enable writing support bundles

sudo snap connect azure-iot-edge:home

# Connect to logging and grant permission to query system info

sudo snap connect azure-iot-edge:log-observe
sudo snap connect azure-iot-edge:mount-observe
sudo snap connect azure-iot-edge:system-observe
sudo snap connect azure-iot-edge:hostname-control
# Allow IoT Edge to connect to the /var/run/iotedge folder and use sockets

sudo snap connect azure-iot-edge:run-iotedge

# Connect IoT Edge to Docker

sudo snap connect azure-iot-edge:docker docker:docker-daemon

为设备预配其云标识

在设备上安装运行时后，请使用供设备用来连接到设备预配服务和 IoT 中心的信息来配置该设备。

准备好以下信息：

DPS 的“ID 范围”值
为设备创建的“注册 ID”
个人注册的主密钥，或者使用组注册时设备的派生密钥。

基于在安装 IoT Edge 的过程中提供的模板文件为你的设备创建配置文件。

Ubuntu / Debian / RHEL
Ubuntu 核心 snap

sudo cp /etc/aziot/config.toml.edge.template /etc/aziot/config.toml

在 IoT Edge 设备上打开配置文件。

sudo nano /etc/aziot/config.toml

如果使用 IoT Edge 的快照安装，则模板文件位于此位置 /snap/azure-iot-edge/current/etc/aziot/config.toml.edge.template。将模板文件复制到主目录并将其命名为 config.toml。例如：

cp /snap/azure-iot-edge/current/etc/aziot/config.toml.edge.template ~/config.toml

在 IoT Edge 设备上打开主目录中的配置文件。

nano ~/config.toml

找到文件的 Provisioning 节。取消注释使用对称密钥进行 DPS 预配的行，并确保注释掉所有其他预配行。

# DPS provisioning with symmetric key
[provisioning]
source = "dps"
global_endpoint = "https://global.azure-devices-provisioning.net"
id_scope = "PASTE_YOUR_SCOPE_ID_HERE"

# Uncomment to send a custom payload during DPS registration
# payload = { uri = "PATH_TO_JSON_FILE" }

[provisioning.attestation]
method = "symmetric_key"
registration_id = "PASTE_YOUR_REGISTRATION_ID_HERE"

symmetric_key = { value = "PASTE_YOUR_PRIMARY_KEY_OR_DERIVED_KEY_HERE" }

# auto_reprovisioning_mode = Dynamic

将 id_scope、registration_id 和 symmetric_key 的值更新为你的 DPS 和设备信息。

对称密钥参数可以接受内联密钥、文件 URI 或 PKCS#11 URI。根据所使用的格式，仅取消注释一个对称密钥行。如果使用内联密钥，请使用 base64 编码的密钥，例如示例。如果使用文件 URI，则文件必须包含密钥的原始字节。

如果使用任何 PKCS#11 URI，请在配置文件中找到 PKCS#11 部分并输入 PKCS#11 配置信息。

有关预配配置设置的详细信息，请参阅配置 IoT Edge 设备设置。
（可选）找到文件的自动重新预配模式部分。使用 auto_reprovisioning_mode 参数设置设备的重新预配行为。动态 - 当设备检测到它可以从一个 IoT 中心移动到另一个 IoT 中心时重新预配。这是默认情况。 AlwaysOnStartup - 设备在重新启动时或在故障导致守护程序重启时进行重新预配。 OnErrorOnly - 从不自动触发设备重新预配。如果设备在标识预配期间因连接错误而无法连接到 IoT Hub，则每种模式都有隐含的设备重新预配回退方案。有关详细信息，请参阅 IoT 中心设备重新预配概念。
（可选）取消注释 payload 参数以指定本地 JSON 文件的路径。设备注册时，文件的内容将作为附加数据发送到 DPS 。这对于自定义分配很有用。例如，如果要根据 IoT 即插即用模型 ID 分配设备而无需人工干预。
保存并关闭该文件。

应用设备上所做的配置更改。

Ubuntu / Debian / RHEL
Ubuntu 核心 snap

sudo iotedge config apply

sudo snap set azure-iot-edge raw-config="$(cat ~/config.toml)"

检查安装是否成功

如果运行时成功启动，请转到 IoT 中心，并开始将 IoT Edge 模块部署到设备。

单独注册
组注册

检查您创建的设备预配服务中的个人注册是否已被使用。在 Azure 门户中，访问你的设备预配服务实例。打开创建的个人注册的注册详细信息。注册状态为“已分配”并且设备 ID 已列出。

在设备上运行这些命令，检查 IoT Edge 是否已安装并成功启动。

检查 IoT Edge 服务的状态。
```
sudo iotedge system status
```
查看服务日志。
```
sudo iotedge system logs
```
列出正在运行的模块。
```
sudo iotedge list
```

后续步骤

通过设备预配服务注册过程，可以在设置新设备时设置设备 ID 和设备孪生标记。使用这些值以具有自动设备管理的单个设备或设备组为目标。了解如何使用 Azure 门户或使用 Azure CLI 大规模部署和监视 IoT Edge 模块。

通过

使用对称密钥在 Linux 上大规模创建和预配 IoT Edge 设备

先决条件

云资源

设备要求

创建 DPS 注册

创建 DPS 单独注册

安装 IoT Edge

安装容器引擎

安装 IoT Edge 运行时

为设备预配其云标识

检查安装是否成功

后续步骤

其他资源