对 IoT Edge for Linux on Windows 设备进行故障排除

2025-09-15

适用于： IoT Edge 1.5

重要

IoT Edge 1.5 LTS 是受支持的版本。截至 2024 年 11 月 12 日，IoT Edge 1.4 LTS 已终止。如果你使用的是较低的版本，请参阅更新 IoT Edge。

如果你在 Windows 上使用 Azure IoT Edge for Linux 时遇到问题（EFLOW），请用本文来排查和诊断问题。

还可以查看 IoT Edge for Linux on Windows GitHub 问题，了解报告的类似问题。

隔离问题

通过确定哪个组件导致问题，开始对适用于 Windows 的 IoT Edge for Linux 进行故障排除。 EFLOW 解决方案有三个主要组件：

Windows 组件：PowerShell 模块、WSSDAgent 和 EFLOWProxy
Azure Linux 虚拟机
Azure IoT Edge

有关 EFLOW 体系结构的详细信息，请参阅什么是 Azure IoT Edge for Linux on Windows。

如果在安装或部署 EFLOW 虚拟机时遇到问题，请检查是否满足所有先决条件，并验证网络和 VM 配置。如果安装和部署成功，但遇到 VM 后管理问题，则问题通常与 VM 生命周期、网络或 Azure IoT Edge 相关。如果问题涉及模块或 IoT Edge 功能，请参阅 IoT Edge 设备疑难解答。

若要详细了解与安装和部署、预配、与 VM 交互以及网络相关的常见错误，请参阅 Azure IoT Edge for Linux on Windows 的常见问题和解决方法。

收集调试信息

若要从 Windows 设备上的适用于 Linux 的 IoT Edge 收集日志，请使用 Get-EflowLogs PowerShell cmdlet。默认情况下，此命令收集以下日志：

eflowlogs-summary.txt：显示所有日志收集步骤的状态。
EFLOW VM 配置：具有 VM、网络、直通配置和其他信息。
EFLOW 事件：与 VM 生命周期和 EFLOWProxy 服务相关的 Windows 事件。
IoT Edge 日志：包含 iotedge check IoT Edge 运行时支持包的输出。
WSSDAgent 日志：包括与 WSSDAgent 服务相关的所有日志。

cmdlet 收集所有必需的日志后，它将文件压缩为 EFLOW 安装路径中 名为eflowlogs.zip 的单个文件（例如 C：\Program Files\Azure IoT Edge）。

检查 IoT Edge 版本

如果在 Windows 上运行旧版 IoT Edge for Linux，升级可以解决问题。若要检查设备上安装的 EFLOW 版本，请执行以下步骤：

在 Windows 上打开“设置”。
选择“添加或删除程序”。
根据使用的 EFLOW 发布训练（持续发布或 LTS），选择 Azure IoT Edge LTS 或 Azure IoT Edge。
检查 EFLOW 应用名称下的版本。

有关特定版本发行说明的详细信息，请查看 Azure IoT Edge for Linux on Windows 发行说明。

有关如何更新设备的说明，请参阅更新 IoT Edge for Linux on Windows。

检查 EFLOW VM 状态

可以使用 Get-EflowVm PowerShell cmdlet 验证 EFLOW VM 状态和信息。如果 EFLOW VM 正在运行，则 VmPowerState 输出应为 Running。而如果 VM 停止，则 VmPowerState 输出为 Off。若要启动或停止 EFLOW VM，请使用 Start-EflowVm 和 Stop-EflowVm cmdlet。

如果 VM 正在运行， 但无法与 VM 交互或使用 VM，则 VM 与 Windows 主机 OS 之间可能存在网络问题。此外，请检查 EFLOW VM 是否有足够的内存和存储可用于继续正常执行。 Get-EflowVm运行 cmdlet 以查看内存（总内存Mb、已用内存Mb、可用内存Mb）和存储（总存储Mb、已用存储Mb、可用存储Mb）信息。

如果 VM 已关闭 ，并且无法使用 cmdlet 启动它 Start-EflowVm ，则 VM 无法启动的原因可能有多种。

首先，该问题可能与 VM 生命周期管理服务 (WSSDAgent) 未运行有关。使用以下步骤确保 WSSDAgent 服务正在运行：

使用“以管理员身份运行”启动提升的 PowerShell 会话。
检查服务状态
```
Get-Service -Name WSSDAgent
```
如果服务处于“Stopped”状态，请使用以下命令启动服务：
```
Start-Service -Name WSSDAgent
```
如果服务处于“Running”状态，则问题可能与网络配置错误或缺少创建 VM 的资源有关。

其次，此问题可能与缺少资源有关。可以在部署期间使用 PowerShell cmdlet 或在部署后使用 -memoryInMb cmdlet 设置分配给 VM 的 EflowVmAssignedMemory () 和 EflowVmAssignedCPUcores (-cpuCount)。如果在尝试启动 VM 时这些资源不可用，则 VM 将无法启动。若要检查已分配资源和可用资源，请执行以下步骤：

使用“以管理员身份运行”启动提升的 PowerShell 会话。
检查可用内存。确保 FreePhysicalMemory 大于 EflowVmAssignedMemory。
```
Get-CIMInstance Win32_OperatingSystem | Select FreePhysicalMemory
```

检查可用 CPU 核心。确保 NumberOfLogicalProcessors 大于 EflowVmAssignedCPUcores。

 wmic cpu get NumberOfLogicalProcessors
 ```ssignedCPUcores*.
```powershell
 wmic cpu get NumberOfLogicalProcessors

最后，此问题可能与网络相关。有关 EFLOW VM 网络问题的详细信息，请参阅如何对 Azure IoT Edge for Linux on Windows 网络进行故障排除。

检查 IoT Edge 运行时的状态

IoT Edge 运行时负责接收要在边缘运行的代码并传达结果。如果 IoT Edge 运行时和模块未运行，则不会在边缘运行任何代码。可以使用以下步骤检查运行时和模块状态：

使用“以管理员身份运行”启动提升的 PowerShell 会话。
检查 IoT Edge 运行时状态。尤其要检查服务是否处于“Loaded”和“Active”状态。
```
(Get-EflowVm).EdgeRuntimeStatus.SystemCtlStatus | Format-List
```
检查 IoT Edge 模块状态。检查所有模块是否正在运行。
```
(Get-EflowVm).EdgeRuntimeStatus.ModuleList | Format-List
```

有关 IoT Edge 运行时故障排除的详细信息，请参阅排除 IoT Edge 设备故障。

检查 TPM 直通

如果根据指南使用 TPM 大规模创建和预配 IoT Edge for Linux on Windows 设备使用 TPM 预配，则必须启用 TPM 直通。为了访问连接到 Windows 主机操作系统的物理 TPM，所有 EFLOW VM TPM 命令都使用称为 EFLOWProxy 的 Windows 服务转发到主机操作系统。如果在使用 DpsTpm 配置或从 EFLOW VM 访问 TPM 索引时遇到问题，请使用以下步骤检查服务状态：

使用“以管理员身份运行”启动提升的 PowerShell 会话。
检查 EFLOWProxy 服务的状态。
```
Get-Service -Name EFLOWProxy
```
如果服务处于“Stopped”状态，请使用以下命令启动服务：
```
Start-Service -Name EFLOWProxy
```
如果服务未启动，请检查 EFLOWProxy 日志。转到应用>事件查看器>应用程序和服务日志>Microsoft>EFLOW EFLOWProxy> 并查看日志。
如果 服务正在运行，请检查 EFLOW VM 代理服务。首先连接到 EFLOW VM。
```
Connect-EflowVm
```
在 EFLOW VM 内部，检查 TPM 服务是否正在运行。
```
sudo systemctl status tpm*
```
可以看到四个不同的服务的状态和日志。所有四个服务都需要运行。
1. tpm2-netns.service - TPM2 网络命名空间
2. tpm2-socat@2322.service - 端口 2322 上的 TPM2 沙盒服务
3. tpm2-socat@2321.service - 端口 2321 上的 TPM2 沙盒服务
4. tpm2-abrmd.service - TPM2 访问代理和资源管理守护程序
如果其中任一服务 已停止 或失败，请使用以下命令重启所有服务：
```
sudo systemctl restart tpm*
```
检查 EFLOW VM 和 EFLOWProxy 服务之间的通信。如果通信有效，会看到 RegistrationId 和 TPM 认可密钥 作为以下命令的输出：
```
sudo /usr/bin/tpm_device_provision
```

检查 GPU 分配

如果使用 GPU 直通，请确保遵循适用于 Windows 上的 Azure IoT Edge for Linux 的 GPU 加速中的所有先决条件和配置。如果 GPU 直通功能出现问题，请执行以下步骤：

首先，检查你的设备是否在 Windows 主机 OS 上可用。

打开“应用程序”“设备管理器”。
转到“显示适配器”并检查 GPU 是否在列表中。
右键单击 GPU 名称并选择“属性”。
检查驱动程序是否正确安装。

其次，如果 GPU 已正确分配，但仍无法在 EFLOW VM 内使用，请使用以下步骤：

使用“以管理员身份运行”启动提升的 PowerShell 会话。
连接到 EFLOW 虚拟机
```
Connect-EflowVm
```
如果使用 NVIDIA GPU，请使用以下命令检查传递状态：
```
sudo nvidia-smi
```
你将看到 GPU 卡信息、驱动程序版本、CUDA 版本以及 GPU 系统和进程信息。
如果使用 Intel iGPU 直通，请使用以下命令检查传递状态：
```
sudo ls -al /dev/dxg
```
预期的输出如下所示：
```
crw-rw-rw- 1 root 10, 60  Sep  8 06:20 /dev/dxg
```
有关 Intel iGPU 性能和调试的详细信息，请参阅见证 Windows（EFLOW）和 OpenVINO™ Toolkit 上的 Azure IoT Edge for Linux 的 Intel® iGPU 的强大功能。

检查 WSSDAgent 日志是否存在问题

在检查 WSSDAgent 日志之前，请确保 VM 已创建并运行。

使用“以管理员身份运行”启动提升的 PowerShell 会话。

在 Windows 客户端 SKU 上，检查 HCS 虚拟机。

hcsdiag list

如果 EFLOW VM 正在运行，你应该会看到包含 GUID 且后跟 wssdagent 的行。例如：

2bd841e4-126a-11ed-9a91-f01dbca16d1e
    VM,                         Running, 2BD841E4-126A-11ED-9A91-F01DBCA16D1E, wssdagent

88d7aa8c-0d1f-4786-b4cb-62eff1decd92
    VM,                         SavedAsTemplate, 88D7AA8C-0D1F-4786-B4CB-62EFF1DECD92, CmService

在 Windows Server SKU 上，检查 VMMS 虚拟机

hcsdiag list

如果 EFLOW VM 正在运行，应该会看到包含 <WindowsHostname-EFLOW> 作为名称的行。例如：

Name               State   CPUUsage(%) MemoryAssigned(M) Uptime           Status             Version
---- -----   ----------- ----------------- ------ ------             -------
NUC-EFLOW          Running 0           1024              00:01:34.1280000 Operating normally 9.0

如果未列出 VM，则它未运行，或者 WSSDAgent 无法创建它。按照以下步骤检查 WSSDAgent 日志：

打开“文件资源管理器”。
转到 C:\ProgramData\wssdagent\log
打开 wssdagent.log 文件。
查找 Error 或 Fail 字样。

重新安装 EFLOW

有时，系统需要特殊更改才能对现有的网络或操作系统约束进行工作。例如，系统可能需要复杂的网络设置，例如防火墙、Windows 策略、代理设置或自定义 Windows OS 设置。如果尝试了所有以前的故障排除步骤，但仍存在 EFLOW 问题，则配置错误可能会导致问题。在这种情况下，最后一个选项是卸载并重新安装 EFLOW。

后续步骤

你认为在 IoT Edge for Linux on Windows 中发现了 bug？提交问题，以便我们可以持续改进。

如果你还有其他问题，请创建支持请求以获取帮助。

通过