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

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

重要

IoT Edge 1.5 LTS 是受支持的版本。 IoT Edge 1.4 LTS 于 2024 年 11 月 12 日终止。如果使用的是早期版本，请参阅 Update IoT Edge。

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

以下是主要任务：

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

提示

为简化体验，请尝试使用 Azure IoT Edge 配置工具。此命令行工具目前以公共预览版提供，在设备上安装IoT Edge，并使用 DPS 和对称密钥证明对其进行预配。

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

先决条件

云资源

一个活跃的物联网集线器
在Azure中与您的IoT Hub关联的IoT Hub设备预配服务实例
- 如果您没有设备预配服务实例，可以按照 IoT Hub 设备预配服务快速入门中创建新的 IoT Hub 设备预配服务和链接 IoT hub 和设备预配服务部分的说明进行操作。
- 运行设备预配服务后，从概述页复制“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 portal，但也可以使用Azure CLI创建单个注册。有关详细信息，请参阅 az iot dps enrollment。在 CLI 命令中，使用 edge-enabled 标志以指定注册对象为 IoT Edge 设备。

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

由于此设备已注册，IoT Edge运行时环境可以在安装期间自动配置该设备。

创建 DPS 组注册

提示

本文中的步骤适用于Azure portal，但也可以使用Azure CLI创建组注册。有关详细信息，请参阅 az iot dps enrollment-group。在 CLI 命令中，使用 edge-enabled 标志来指定注册是为 IoT Edge 设备准备的。对于组注册，所有设备必须都是 IoT Edge 设备，否则就不能有任何设备。

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

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

派生一个设备密钥

在组注册过程中预配的每个设备都需要一个派生的设备密钥，以在预配期间与注册进行对称密钥验证。

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

重要

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

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

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

请将 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。

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

重要

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

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

可以使用几个命令安装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开始运行上一个命令。

可以使用几个命令安装IoT Edge。打开终端并运行以下命令：

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 和 Docker EE 容器映像适用于 Moby 运行时。如果使用的是 Ubuntu Core 快照，Canonical 负责管理 Docker 快照，并支持在生产环境中使用。

安装 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 核心软件包

创建或编辑现有 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 Hub通信的设备组件的标识预配和管理。

本部分中的步骤表示在具有 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商店安装IoT Edge：

sudo snap install azure-iot-edge

连接快照

默认情况下，Snap 无依赖项、不受信任且严格限制。因此，安装之后，必须将 snap 连接到其他 snap 和系统资源。使用以下命令将 IoT 标识服务和 IoT Edge 插件相互连接，并连接到系统资源。要开始，请手动连接 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

为设备预配其云标识

在您的设备上安装运行时后，配置设备以使用其用于连接到设备预配服务和物联网中心的信息。

准备好以下信息：

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

根据作为IoT Edge安装的一部分提供的模板文件为设备创建配置文件。

Ubuntu / Debian / RHEL
Ubuntu 核心软件包

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

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

Ubuntu / Debian / RHEL
Ubuntu 核心软件包

sudo iotedge config apply

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

检查安装是否成功

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

单独注册
群组注册

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

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

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

后续步骤

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

Last updated on 2026-03-16

通过

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

先决条件

云资源

设备要求

创建 DPS 注册

创建 DPS 个人注册

安装IoT Edge

安装容器引擎

安装IoT Edge环境

为设备预配其云标识

检查安装是否成功

后续步骤

其他资源