你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

项目
12/18/2024

适用于： IoT Edge 1.5 IoT Edge 1.4

重要

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

本文提供有关注册和预配 Linux IoT Edge 设备的端到端说明，包括安装 IoT Edge。

连接到 IoT 中心的每个设备都有一个设备 ID，用于跟踪云到设备或设备到云的通信。你将使用设备的连接信息配置设备，这些信息包括：

IoT 中心主机名
设备 ID
用于连接到 IoT 中心的身份验证详细信息

本文中的步骤演示了一个名为“手动预配”的过程。在手动预配过程中，你可以将单个设备连接到其 IoT 中心。对于手动预配，可以通过两种方式来验证 IoT Edge 设备：

对称密钥：你在 IoT 中心创建新设备标识时，服务将创建两个密钥。将其中一个密钥置于设备上，并在进行身份验证时将该密钥提供给 IoT 中心。

此身份验证方法更容易上手，但不够安全。
X.509 自签名：创建两个 X.509 标识证书并将其置于设备上。在 IoT 中心创建新的设备标识时，需要提供两个证书的指纹。设备在向 IoT 中心进行身份验证时会提供一个证书，IoT 中心会验证该证书是否与其指纹匹配。

此身份验证方法更加安全，建议用于生产方案。

本文介绍如何使用对称密钥作为身份验证方法。如果要使用 X.509 证书，请参阅在 Linux 上使用 X.509 证书创建和预配 IoT Edge 设备。

注意

如果要设置多个设备，并且不想手动预配每个设备，请参阅以下文章之一来了解 IoT Edge 如何与 IoT 中心设备预配服务配合工作：

先决条件

本文介绍如何注册 IoT Edge 设备并在设备上安装 IoT Edge（也称为 IoT Edge 运行时）。在注册和安装设备之前，请确保已准备好所选的设备管理工具（例如 Azure CLI）并满足设备要求。

设备管理工具

你可以使用 Azure 门户、Visual Studio Code 或 Azure CLI 来完成注册设备的步骤。每个实用工具都有自身的先决条件，或者可能需要完成安装：

Azure 订阅中的免费或标准 IoT 中心。

设备要求

X64、ARM32 或 ARM64 Linux 设备。

Microsoft 发布了适用于各种操作系统的安装包。

如需生产方案目前支持哪些操作系统的最新信息，请参阅 Azure IoT Edge 支持的系统。

Visual Studio Code 扩展

如果你使用 Visual Studio Code，可以通过一些有用的 Azure IoT 扩展来简化设备创建和管理过程。

同时安装 Azure IoT Edge 和 Azure IoT 中心扩展：

Azure IoT Edge。 适用于 Visual Studio Code 的 Azure IoT Edge 工具扩展处于维护模式。
Azure IoT 中心

注册设备

根据你的偏好，你可以使用 Azure 门户、Visual Studio Code 或 Azure CLI 来注册设备。

在 Azure 门户你的 IoT 中心内，IoT Edge 设备的创建和管理独立于不支持 Edge 的 IoT 设备。

登录 Azure 门户，导航到 IoT 中心。
在左侧窗格中，从菜单中选择“设备”，然后选择“添加设备”。
在“创建设备”页面上，提供以下信息：
- 创建描述性的设备 ID，例如 my-edge-device-1（全小写）。复制此设备 ID，因为稍后需要用到。
- 选中“IoT Edge 设备”复选框。
- 选择“对称密钥”作为身份验证类型。
- 使用默认设置自动生成身份验证密钥，用于将新设备连接到中心。
选择“保存”。

IoT 中心应会显示你的新设备。

可使用适用于 Visual Studio Code 的 Azure IoT 扩展来执行与 IoT 中心相关的操作。确保已安装 Azure IoT 扩展必备组件。

安装 Azure IoT Edge 和 Azure IoT 中心扩展后，你会注意到，左侧图标菜单中添加了一个“Azure”图标。可以通过 Visual Studio Code 登录到你的 Azure 帐户，方法是选择“Azure”图标，然后选择“登录到 Azure”。

将新设备注册到 Visual Studio Code

注册新设备的过程类似于在 Azure 门户中创建 IoT Edge 设备。此虚拟设备是一个孪生，而真实设备是另一个孪生。 Visual Studio Code 可通过以下步骤为你完成此项设置。

在 Visual Studio Code 资源管理器菜单中，展开“Azure IoT 中心”部分。
选择“Azure IoT 中心”部分标题中的“...”。如果没有看到省略号图标，请选择标题或将鼠标指针悬停在标题上。
选择“创建 IoT Edge 设备” 。
在打开的文本框中，为设备提供一个 ID，例如 my-edge-device-1（全小写），然后按 Enter。

在 Visual Studio Code 的输出控制台中，你会看到命令的结果：JSON 输出。设备信息包括你提供的 deviceId，其中生成了可用于将物理设备连接到 IoT 中心的 connectionString。输出控制台还会显示你的密钥和其他设备标识信息。

现在可以看到，你的设备已列在资源管理器菜单的“Azure IoT 中心”>“设备”部分下。

注意

如果你的设备未列出，可能需要通过“Azure IoT 中心”下提供的“选择 IoT 中心”链接选择你的 IoT 中心，然后按提示操作。提示要求你先选择订阅，然后再选择 IoT 中心。此过程让 Visual Studio Code 知道你的 IoT 中心（及其中的所有设备）。刷新 Visual Studio Code，然后你的设备即会显示。

使用 az iot hub device-identity create 命令在 IoT 中心创建新设备标识。将 device_id_here 替换为你自己的新唯一设备 ID，例如 my-edge-device-1（全小写）。将 hub_name_here 替换为你的现有 IoT 中心。

此命令包括三个参数：

--device-id 或 -d：提供在 IoT 中心独一无二的描述性名称。
--hub-name 或 -n：提供 IoT 中心的名称。

--edge-enabled 或 --ee：声明该设备是 IoT Edge 设备。

az iot hub device-identity create --device-id device_id_here --hub-name hub_name_here --edge-enabled

如果 CLI 显示“该命令需要扩展 azure-iot。是否现在安装该扩展?”，请键入 Y 并按 Enter 开始下载该扩展以创建设备。

在 IoT 中心注册设备后，接下来可以检索预配信息，用于在下一步骤中完成 IoT Edge 运行时的安装和预配。

查看已注册设备并检索预配信息

使用对称密钥身份验证的设备需要使用其连接字符串来完成 IoT Edge 运行时的安装和预配。当你创建设备时，系统将为 IoT Edge 设备生成连接字符串。对于 Visual Studio Code 和 Azure CLI，该连接字符串位于 JSON 输出中。如果你使用 Azure 门户创建设备，可以在设备本身中找到该连接字符串。在 IoT 中心选择你的设备时，该连接字符串将在设备页上列出为 Primary connection string。

连接到 IoT 中心并已启用边缘的设备将在 IoT 中心的“设备”页上列出。如果你有多个设备，可以通过选择“IoT Edge 设备”类型来筛选列表，然后选择“应用”。

如果已准备好设置设备，则需要连接字符串，该字符串使用物理设备在 IoT 中心内的标识链接该设备。使用对称密钥进行身份验证的设备有自己的连接字符串，可以在门户中复制这些连接字符串。若要在门户中查找连接字符串，请执行以下操作：

在“设备”页中，从列表中选择 IoT Edge 设备 ID。
复制“主连接字符串”或“辅助连接字符串”的值。任何一键都是有效的。

若要查看 IoT 中心内的所有设备，请使用 az iot hub device-identity list 命令。将 hub_name_here 替换为你自己的 IoT 中心名称。

az iot hub device-identity list --hub-name hub_name_here

注册为 IoT Edge 设备的任何设备的 capabilities.iotEdge 属性会设置为 true。还会看到其他许多元数据作为 JSON 输出列出，其中包括你的设备 ID。

准备好设置设备时，需要提供其连接字符串，用于通过物理设备在 IoT 中心内的标识链接该设备。使用以下 az iot hub device-identity connection-string show 命令返回单个设备的连接字符串。将 [device_id] 和 [hub_name] 替换为自己的值。 device-identity 参数的值区分大小写。

az iot hub device-identity connection-string show --device-id [device_id] --hub-name [hub_name]

应会在控制台中看到 JSON 输出，如下所示：

{
  "connectionString": "HostName=[hub_name].azure-devices.net;DeviceId=[device_id];SharedAccessKey=[device_key]"
}

提示

connection-string show 命令是在 Azure IoT 扩展的 0.9.8 版本中引入的，替换弃用的 show-connection-string 命令。如果在运行此命令时遇到错误，请确保将扩展版本更新为 0.9.8 或更高版本。有关详细信息以及最新的更新，请参阅适用于 Azure CLI 的 Microsoft Azure IoT 扩展。

复制要在设备上使用的连接字符串时，请不要包括围绕连接字符串的引号。

安装 IoT Edge

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

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

重要

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 提供服务，并支持将其用于生产场景中。

默认情况下，容器引擎不会设置容器日志大小限制。一段时间后，这可能会导致设备中填满了日志，因此出现磁盘空间不足的情况。但是，你可以将日志配置为在本地显示，不过这是可选操作。若要了解有关日志记录配置的详细信息，请参阅生产部署清单。

以下步骤说明如何将容器配置为使用 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 开始，IoT 标识服务会处理 IoT Edge 以及需要与 IoT 中心通信的其他设备组件的标识预配和管理。

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

提示

如果你已经有运行旧版本的 IoT Edge 设备并想要升级到最新版本，请按照更新 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 Edge 运行时后，可以使用设备的云标识和身份验证信息来设置设备。

Ubuntu / Debian / RHEL
Ubuntu 核心 snap

可以使用以下命令通过对称密钥身份验证配置 IoT Edge 设备：

sudo iotedge config mp --connection-string 'PASTE_DEVICE_CONNECTION_STRING_HERE'

此 iotedge config mp 命令在设备上创建一个配置文件，并在配置文件中输入你的连接字符串。

应用配置更改。
```
sudo iotedge config apply
```
若要查看配置文件，可将其打开：
```
sudo nano /etc/aziot/config.toml
```

在主目录中创建 config.toml 文件，并通过 snap 的对称密钥身份验证配置 IoT Edge 设备。
```
sudo nano ~/config.toml
```
可以使用以下预配设置通过连接字符串手动进行预配：
```
[provisioning]
source = "manual"
connection_string = "REPLACE_WITH_DEVICE_CONNECTION_STRING"
```
有关预配配置设置的详细信息，请参阅配置 IoT Edge 设备设置。

使用以下命令设置 IoT Edge 和标识服务的配置：

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

部署模块

若要部署 IoT Edge 模块，请转到 Azure 门户中你的 IoT 中心，然后：

在 IoT 中心菜单中选择“设备”。
选择你的设备以打开其页面。
选择“设置模块”选项卡。
由于我们要部署 IoT Edge 默认模块（edgeAgent 和 edgeHub），且不需要将任何模块添加到此窗格，因此请选择底部的“查看 + 创建”。
你将看到模块的 JSON 确认。选择“创建”以部署模块。

有关详细信息，请参阅部署模块。

验证成功的配置

验证是否已在 IoT Edge 设备上成功安装并配置运行时。

提示

需要提升权限才能运行 iotedge 命令。安装 IoT Edge 运行时后从计算机中注销并第一次重新登录后，你的权限将自动更新。在此之前，请在命令前使用 sudo。

检查以确保 IoT Edge 系统服务正在运行。
```
sudo iotedge system status
```
成功状态响应会将 aziot 服务显示为正在运行或准备就绪。
若需排查服务问题，请检索服务日志。
```
sudo iotedge system logs
```
使用 check 工具验证设备的配置和连接状态。
```
sudo iotedge check
```
预期会收到一系列响应，其中可能包括“正常”（绿色）、“警告”（黄色）或“错误”（红色）。有关排查常见错误的信息，请参阅 Azure IoT Edge 常见问题的解决方案。

提示

请始终使用 sudo 来运行检查工具，即使权限已更新。该工具需要提升的权限才能访问配置文件以验证配置状态。

注意

在新预配的设备上，可能会看到与 IoT Edge 中心相关的错误：

× 生产就绪性：Edge 中心的存储目录保存在主机文件系统上 - 错误。无法检查 edgeHub 容器的当前状态

由于 IoT Edge 中心模块仍未运行，在新预配的设备上预期会出现此错误。请确保在前面的步骤中部署了 IoT Edge 模块。部署会解决此错误。

或者，你可能会看到状态代码为 417 -- The device's deployment configuration is not set。部署模块后，此状态会发生变化。
当服务首次启动时，你应当只会看到 edgeAgent 模块正在运行。 edgeAgent 模块会默认运行，用于安装并启动部署到设备的任何其他模块。

通过在 Azure 门户查看设备页，检查设备和模块是否已部署并正在运行。

部署并运行模块后，使用以下命令在设备或虚拟机中将其列出：
```
sudo iotedge list
```

脱机或特定版本安装（可选）

本部分中的步骤适用于标准安装步骤未涵盖的方案。这可能包括：

脱机安装 IoT Edge
安装候选发布版本

如果你想要安装特定版本的无法通过包管理器获取的 Azure IoT Edge 运行时，请使用本部分中的步骤。 Microsoft 包列表仅包含有限的一组最新版本及其子版本，因此，这些步骤适用于想要安装较旧版本或候选发布版本的任何用户。

如果使用 Ubuntu snap，可以下载 snap 并脱机安装它。有关详细信息，请参阅下载 snap 并脱机安装。

使用 curl 命令，可以直接从 IoT Edge GitHub 存储库将组件文件作为目标。

导航到 Azure IoT Edge 版本，找到需要将其作为目标的发行版。
展开该版本的“资产”部分。
每个版本都应有用于 IoT Edge 和标识服务的新文件。如果要在脱机设备上安装 IoT Edge，请提前下载这些文件。否则，请使用以下命令来更新这些组件。
1. 找到与你的 IoT Edge 设备体系结构匹配的 aziot-identity-service 文件。右键单击文件链接并复制链接地址。
2. 在以下命令中使用复制的链接来安装该版本的标识服务：
```
curl -L <identity service link> -o aziot-identity-service.deb && sudo apt-get install ./aziot-identity-service.deb
```
```
curl -L <identity service link> -o aziot-identity-service.rpm && sudo yum localinstall ./aziot-identity-service.rpm
```
  如果使用 Ubuntu snap，可以下载 snap 包并脱机安装它。有关详细信息，请参阅下载 snap 并脱机安装。
1. 找到与你的 IoT Edge 设备体系结构匹配的 az iot-edge 文件。右键单击文件链接并复制链接地址。
2. 在以下命令中使用复制的链接来安装该版本的 IoT Edge。
```
curl -L <iotedge link> -o aziot-edge.deb && sudo apt-get install ./aziot-edge.deb
```
```
curl -L <iotedge link> -o aziot-edge.rpm && sudo yum localinstall ./aziot-edge.rpm
```
  如果使用 Ubuntu snap，可以下载 snap 包并脱机安装它。有关详细信息，请参阅下载 snap 并脱机安装。

卸载 IoT Edge

若要从设备中删除 IoT Edge 安装，请使用以下命令。

删除 IoT Edge 运行时。

sudo apt-get autoremove --purge aziot-edge

如果计划重新安装 IoT Edge 并在以后使用相同的配置信息，请忽略 --purge 标记。 --purge 标记会删除与 IoT Edge 关联的所有文件，包括配置文件。

sudo yum remove aziot-edge

删除 IoT Edge 运行时：

sudo snap remove azure-iot-edge

删除 Azure 标识服务：

sudo snap remove azure-iot-identity

删除 IoT Edge 运行时后，已创建的所有容器都会停止，但仍存在于设备上。查看所有容器以了解哪些容器仍然存在。

sudo docker ps -a

从设备中删除容器，包括两个运行时容器。

sudo docker rm -f <container ID>

最后，从设备中删除容器运行时。

sudo apt-get autoremove --purge moby-engine

sudo yum remove moby-cli
sudo yum remove moby-engine

sudo snap remove docker

通过

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

先决条件

设备管理工具

设备要求

Visual Studio Code 扩展

注册设备

将新设备注册到 Visual Studio Code

查看已注册设备并检索预配信息

安装 IoT Edge

安装容器引擎

安装 IoT Edge 运行时

连接 snap

为设备预配其云标识

部署模块

验证成功的配置

脱机或特定版本安装（可选）

卸载 IoT Edge

后续步骤

反馈

其他资源