通过

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

在 Linux 上使用 X.509 证书创建和预配 IoT Edge 设备

  • 项目

适用于： IoT Edge 1.5 复选标记 IoT Edge 1.5 IoT Edge 1.4 复选标记 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 上使用对称密钥创建和预配 IoT Edge 设备。

注意

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

先决条件

本文介绍如何注册 IoT Edge 设备并在设备上安装 IoT Edge。 这些任务具有不同的先决条件和用于完成这些任务的实用程序。 在继续操作之前，请确保已满足所有先决条件。

设备管理工具

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

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

设备要求

X64、ARM32 或 ARM64 Linux 设备。

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

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

生成设备标识证书

使用 X.509 证书进行手动预配需要 IoT Edge 1.0.10 或更高版本。

在使用 X.509 证书预配 IoT Edge 设备时，你将使用所谓的设备标识证书。 此证书仅用于预配 IoT Edge 设备，以及通过 Azure IoT 中心对设备进行身份验证。 它是不能对其他证书进行签名的叶证书。 设备标识证书不同于 IoT Edge 设备提供给模块或下游设备进行验证的证书颁发机构 (CA) 证书。

对于 X.509 证书身份验证，每个设备的身份验证信息采用从设备标识证书获取的指纹的形式提供。 在注册设备时，会向 IoT 中心提供这些指纹，以便服务在连接时能够识别设备。

若要详细了解如何在 IoT Edge 设备中使用 CA 证书，请参阅了解 Azure IoT Edge 如何使用证书。

若要使用 X.509 进行手动预配，需要以下文件：

  • 两个设备标识证书及其 .cer 或 .pem 格式的匹配私钥证书。 需要两个设备标识证书才能轮换证书。 最佳做法是准备两个不同的设备标识证书，它们的过期日期不同。 如果其中一个证书过期，另一个证书仍然有效，让你有时间轮换已过期的证书。

    其中一组证书和密钥文件提供给 IoT Edge 运行时。 创建设备标识证书时，请将证书公用名 (CN) 设置为你希望该设备在 IoT 中心具有的设备 ID。

  • 从两个设备标识证书获取的指纹。 IoT 中心在注册 IoT Edge 设备时需要两个指纹。 只能使用一个证书进行注册。 若要使用单个证书，请在注册设备时为主要和次要指纹设置相同的证书指纹。

    SHA-1 哈希的指纹值为 40 个十六进制字符，SHA-256 哈希的指纹值为 64 个十六进制字符。 在注册设备时，两个指纹都将提供给 IoT 中心。

    从证书中检索指纹的一种方法是使用以下 openssl 命令：

    openssl x509 -in <certificate filename>.pem -text -fingerprint

    指纹包含在此命令的输出中。 例如：

    SHA1 Fingerprint=D2:68:D9:04:9F:1A:4D:6A:FD:84:77:68:7B:C6:33:C0:32:37:51:12

如果没有可用的证书，可以创建演示证书以测试 IoT Edge 设备功能。 按照该文章中的说明设置证书创建脚本、创建根 CA 证书，然后创建一个 IoT Edge 设备标识证书。 若要进行测试，可以创建单个设备标识证书，并在 IoT 中心注册设备时对主要和辅助指纹值使用相同的指纹。

注册设备

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

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

  1. 登录 Azure 门户，导航到 IoT 中心。

  2. 在左侧窗格中，从菜单中选择“设备”，然后选择“添加设备”。

  3. 在“创建设备”页面上，提供以下信息：

    • 创建描述性设备 ID。 记下此设备 ID，因为稍后会用到它。
    • 选中“IoT Edge 设备”复选框。
    • 选择“X.509 自签名”作为身份验证类型。
    • 提供主要和辅助标识证书指纹。 SHA-1 哈希的指纹值为 40 个十六进制字符，SHA-256 哈希的指纹值为 64 个十六进制字符。 Azure 门户仅支持十六进制值。 在门户中输入指纹值之前，请从指纹值中删除列分隔符和空格。 例如，将 D2:68:D9:04:9F:1A:4D:6A:FD:84:77:68:7B:C6:33:C0:32:37:51:12 输入为 D268D9049F1A4D6AFD8477687BC633C032375112。

    提示

    如果正在测试并且想要使用一个证书，则可以对主要和辅助指纹使用相同的证书。

  4. 选择“保存”。

在 IoT 中心完成设备注册后，需检索用于安装和预配 IoT Edge 运行时的信息。

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

使用 X.509 证书进行身份验证的设备需要其 IoT 中心名称、设备名称及证书文件才能完成 IoT Edge 运行时的安装和预配。

连接到 IoT 中心并已启用 Edge 的设备将在“设备”页上列出。 可以按设备类型 IoT Edge 设备筛选列表。

安装 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

有关操作系统版本的详细信息，请参阅 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

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

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

  1. 创建或编辑现有 Docker 守护程序的配置文件

    sudo nano /etc/docker/daemon.json

  2. 将默认日志记录驱动程序设置为 local 日志记录驱动程序，如示例中所示。

       {
      "log-driver": "local"
   }

  3. 重启容器引擎以使更改生效。

    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 defender-iot-micro-agent-edge

可选的 defender-iot-micro-agent-edge 包中包含 Microsoft Defender for IoT 安全性微代理，用于为安全态势管理、漏洞、威胁检测、群队管理等提供终结点可见性，以帮助保护 IoT Edge 设备。 建议使用 Edge 代理安装微代理，以便启用 Edge 设备的安全监视和强化。 若要详细了解 Microsoft Defender for IoT，请参阅什么是适用于设备生成器的 Microsoft Defender for IoT。

为设备预配其云标识

在设备上安装容器引擎和 IoT Edge 运行时后，可以使用设备的云标识和身份验证信息来设置设备。

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

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

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

    sudo nano /etc/aziot/config.toml

  3. 找到文件的预配部分，并取消注释“使用 X.509 标识证书进行手动预配”行。 确保所有其他预配部分都已被注释掉。

    # Manual provisioning with x.509 certificates
[provisioning]
source = "manual"
iothub_hostname = "REQUIRED_IOTHUB_HOSTNAME"
device_id = "REQUIRED_DEVICE_ID_PROVISIONED_IN_IOTHUB"

[provisioning.authentication]
method = "x509"

identity_cert = "REQUIRED_URI_OR_POINTER_TO_DEVICE_IDENTITY_CERTIFICATE"

identity_pk = "REQUIRED_URI_TO_DEVICE_IDENTITY_PRIVATE_KEY"

更新以下字段：

  • iothub_hostname：设备连接到的 IoT 中心的主机名。 例如 {IoT hub name}.azure-devices.net。
  • device_id：注册设备时提供的 ID。
  • identity_cert：设备上标识证书的 URI，例如 file:///path/identity_certificate.pem。 或者，使用 EST 或本地证书颁发机构动态颁发证书。
  • identity_pk：所提供标识证书的私钥文件 URI，例如 file:///path/identity_key.pem。 或者，提供 PKCS#11 URI，然后在

配置文件的后续 PKCS#11 部分提供你的配置信息。

有关证书的详细信息，请参阅管理 IoT Edge 证书。

保存并关闭该文件。

CTRL + X、Y、Enter

在配置文件中输入预配信息后，应用所做的更改：

sudo iotedge config apply

部署模块

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

  1. 在 IoT 中心菜单中选择“设备”。

  2. 选择你的设备以打开其页面。

  3. 选择“设置模块”选项卡。

  4. 由于我们要部署 IoT Edge 默认模块（edgeAgent 和 edgeHub），且不需要将任何模块添加到此窗格，因此请选择底部的“查看 + 创建”。

  5. 你将看到模块的 JSON 确认。 选择“创建”以部署模块。<

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

验证成功的配置

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

提示

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

检查以确保 IoT Edge 系统服务正在运行。

sudo iotedge system status

成功的状态响应是 Ok。

若需排查服务问题，请检索服务日志。

sudo iotedge system logs

使用 check 工具验证设备的配置和连接状态。

sudo iotedge check

预期会收到一系列响应，其中可能包括“正常”（绿色）、“警告”（黄色）或“错误”（红色）。 有关排查常见错误的信息，请参阅 Azure IoT Edge 常见问题的解决方案。

check 命令的示例响应的屏幕截图。

提示

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

注意

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

× 生产就绪性：Edge 中心的存储目录持久保存在主机文件系统上- 错误

无法检查 edgeHub 容器的当前状态

由于 IoT Edge 中心模块未运行，在新预配的设备上预期会出现此错误。 若要解决此错误，请在 IoT 中心为设备设置模块并创建部署。 为设备创建部署会启动设备上的模块，包括 IoT Edge 中心模块。

查看在 IoT Edge 设备上运行的所有模块。 当服务首次启动时，你应当只会看到 edgeAgent 模块正在运行。 edgeAgent 模块会默认运行，用于安装并启动部署到设备的任何其他模块。

sudo iotedge list

创建新的 IoT Edge 设备时，它将在 Azure 门户中显示状态代码 417 -- The device's deployment configuration is not set。 此状态正常，表示设备已准备好接收模块部署。

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

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

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

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

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

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

  1. 导航到 Azure IoT Edge 版本，找到需要将其作为目标的发行版。

  2. 展开该版本的“资产”部分。

  3. 每个版本都应有用于 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

    1. 找到与你的 IoT Edge 设备体系结构匹配的 az iot-edge 文件。 右键单击文件链接并复制链接地址。

    2. 在以下命令中使用复制的链接来安装该版本的 IoT Edge。

      curl -L <iotedge link> -o aziot-edge.deb && sudo apt-get install ./aziot-edge.deb

卸载 IoT Edge

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

删除 IoT Edge 运行时。

sudo apt-get autoremove --purge aziot-edge

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

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

sudo docker ps -a

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

sudo docker rm -f <container name>

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

sudo apt-get autoremove --purge moby-engine