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

项目
12/02/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。

如果在环境中运行 Azure IoT Edge for Linux on Windows (EFLOW) 时遇到问题，请使用本文作为故障排除和诊断的指南。

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

隔离问题

对 IoT Edge for Linux on Windows 进行故障排除的第一步应该是了解导致问题的组件。 EFLOW 解决方案包含三个主要组件：

Windows 组件：PowerShell 模块、WSSDAgent 和 EFLOWProxy
CBL Mariner 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 的常见问题和解决方法。

收集调试信息

需要从 IoT Edge for Linux on Windows 设备收集日志时，最方便的方法是使用 Get-EflowLogs PowerShell cmdlet。默认情况下，此命令收集以下日志：

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

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

检查 IoT Edge 版本

如果运行的是较旧版本的 IoT Edge for Linux on Windows，则升级可能会解决你的问题。若要检查设备上安装的 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 处于“Running”状态，但你无法访问 VM 或与之交互，则 VM 和 Windows 主机 OS 之间可能存在网络问题。此外，请确保 EFLOW VM 有足够的内存和存储空间来继续正常执行。运行 Get-EflowVm cmdlet 以查看内存（TotalMemMb、UsedMemMb、AvailableMemMb）和存储（TotalStorageMb、UsedStorageMb、AvailableStorageMb）信息。

最后，如果 VM 处于“Off”状态，并且无法使用 Start-EflowVm cmdlet 启动它，则可能有多种原因导致 VM 无法启动。

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

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

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

使用“以管理员身份运行”启动提升的 PowerShell 会话。
检查可用内存。确保 FreePhysicalMemory 大于 EflowVmAssignedMemory。
```
Get-CIMInstance Win32_OperatingSystem | Select FreePhysicalMemory
```
检查可用 CPU 核心。确保 NumberOfLogicalProcessors 大于 EflowVmAssignedCPUcores。
```
 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”并检查日志。
如果服务处于“Running”状态，请检查 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 Endorsement Key 作为以下命令的输出：
```
sudo /usr/bin/tpm_device_provision
```

检查 GPU 分配

如果使用 GPU 直通，请确保遵循用于 Azure IoT Edge for Linux on Windows 的 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 性能和调试信息的详细信息，请参阅使用 Azure IoT Edge for Linux on Windows (EFLOW) 和 OpenVINO™ 工具包见证 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，则表示 VM 未在运行或 WSSDAgent 无法创建它。使用以下步骤检查 WSSDAgent 日志：

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

重新安装 EFLOW

有时，系统可能需要进行重大特殊修改才能使用现有网络或操作系统约束。例如，系统可能需要复杂的网络配置（防火墙、Windows 策略、代理设置）和自定义 Windows 操作系统配置。如果你尝试了之前的所有故障排除步骤，但仍然存在 EFLOW 问题，则可能是某些配置错误导致了该问题。在这种情况下，最后的选择是卸载并重新安装 EFLOW。

后续步骤

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

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

通过