通过

Azure IoT Edge for Linux on Windows 的常见问题和解决方法

  • 项目

适用于：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。

使用本文来帮助解决在部署 IoT Edge for Linux on Windows 解决方案时可能出现的常见问题。

安装和部署

以下部分用于解决在安装 EFLOW MSI 和部署 EFLOW 虚拟机时的常见错误。 确保了解以下 EFLOW 概念：

错误 错误说明 解决方案
HNS API 版本 X 不满足最低版本要求 EFLOW 使用 HCS/HNS 在客户端 SKU 上创建虚拟机。 最低 HNS 版本为 9.2。 如果使用 Windows 版本 20H1 或更高版本，HCS/HNS API 应满足要求。 如果使用的是 Windows 客户端 RS5 (17763)，请验证你是否有最新的 Windows 更新。
找不到 WSSDAGENT 服务!
WssdAgent 无法访问，更新失败。		 WSSDAgent 是创建和管理 VM 生命周期的 EFLOW 组件。 WSSDAgent 在 Windows 主机 OS 上运行服务。 如果服务未运行，VM 通信和生命周期将失败。 打开提升的 PowerShell 会话并运行命令 Get-Service -Name wssdagent，验证 WSSDAgent 是否正在 Windows 主机 OS 上运行。 如果 WSSDAgent 未运行，请尝试使用 cmdlet Start-Service -name WSSDAgent 手动启动服务。 如果未启动，请共享 C:\ProgramData\wssdagent 下的内容。
缺少预期的映像“$vhdPathBackup” 安装 EFLOW 当前发布 (CR) 时，用户可以使用 vmDataSize 提供数据分区大小。 如果指定了，EFLOW 将调整 VHDX 的大小。 如果在调整大小期间找不到 VHDX 文件，则会发生此错误。 验证 VHDX 文件未从原始位置被删除或移动。
Hyper-V、Hyper-V 管理 PowerShell 或 OpenSSH 的安装失败。 请手动安装并重启部署。 正在中止... EFLOW 安装要求满足所需的先决条件才能部署虚拟机。 如果有一个先决条件不满足，Deploy-Eflow cmdlet 将失败。 确保满足所有所需的先决条件。 PowerShell：关闭 PowerShell 会话并打开一个新会话。 如果有多个安装，请确保导入了正确的模块。 尝试使用其他版本的 PowerShell。
Hyper-V：有关 EFLOW Hyper-V 支持的详细信息，请参阅 Azure IoT Edge for Linux on Windows 嵌套虚拟化。
OpenSSH：如果使用自己的自定义安装，请在部署期间检查 customSsh 参数。
$feature 在此 Windows 版本中不可用。
无法启用 $featureversion。 请在设置中添加“$featureversion”可选功能，然后重启部署。		 部署 EFLOW 时，如果有一个先决条件不满足，安装程序将尝试安装它。 如果此功能不可用或功能安装失败，EFLOW 部署将失败。 确保满足所有所需的先决条件。 PowerShell：关闭 PowerShell 会话并打开一个新会话。 如果有多个安装，请确保导入了正确的模块。 尝试使用其他版本的 PowerShell。
Hyper-V：有关 EFLOW Hyper-V 支持的详细信息，请参阅 Azure IoT Edge for Linux on Windows 嵌套虚拟化。
OpenSSH：如果使用自己的自定义安装，请在部署期间检查 customSsh 参数。
Hyper-V 属性指示 Hyper-V 组件不起作用(属性 HyperVRequirementVirtualizationFirmwareEnabled 为 false)
Hyper-V 属性指示 Hyper-V 组件不起作用(属性 HyperVisorPresent 为 false)。
Hyper-V 核心服务未运行(vmms、vmcompute、hvhost)。 确保 Hyper-V 配置正确并且能够启动虚拟机。		 这些错误与 Hyper-V 虚拟化技术堆栈和服务相关。 EFLOW 虚拟机需要多个 Hyper-V 服务才能创建并运行虚拟机。 如果其中一个服务不可用，则安装将失败。 有关 EFLOW Hyper-V 支持的详细信息，请参阅 Azure IoT Edge for Linux on Windows 嵌套虚拟化。
wssdagent 无法访问，请重试... WSSDAgent 是创建和管理 VM 生命周期的 EFLOW 组件。 WSSDAgent 在 Windows 主机 OS 上运行服务。 打开提升的 PowerShell 会话并运行命令 Get-Service -Name wssdagent，验证 WSSDAgent 是否正在 Windows 主机 OS 上运行。 如果 WSSDAgent 未运行，请尝试使用 cmdlet Start-Service -name WSSDAgent 手动启动服务。 如果未启动，请共享 C:\ProgramData\wssdagent 下的内容。
无法从 wssdagent 检索虚拟机配置 在 EFLOW 根安装文件夹下查找 EFLOW 配置 yaml 文件。 例如，如果使用了默认安装目录，配置文件应位于 C:\Program Files\Azure IoT Edge\yaml 目录中。 检查目录是否已删除或移动。 如果目录不可用，则无法创建 VM。 需要重新安装 EFLOW。
检测到现有的虚拟机。 若要重新部署虚拟机，请卸载并重新安装 $eflowProductName。
虚拟机“$name”已存在。 需要首先删除“$name”虚拟机。		 在 EFLOW 部署期间，安装程序将检查是否有从之前的安装创建的 EFLOW VM。 在某些情况下，如果安装在最后的步骤中失败，将创建 VM，并且它仍然在 Windows 主机 OS 中运行。 在开始新安装之前，请确保完全卸载 EFLOW。 若要从设备中删除 Azure IoT Edge for Linux on Windows 安装，请使用以下命令。
1. 在 Windows 中，打开“设置”
2. 选择“添加或删除程序”
3.选择“Azure IoT Edge LTS”应用
4. 选择“卸载”
创建存储 vhd (文件: $($config["imageNameEflowVm"]))失败 创建或调整 EFLOW 虚拟机 VHDX 大小时出错。 有关详细信息，请查看 EFLOW 安装日志 C:\Program Files\Azure IoT Edge 和 WSSDAgent 日志。
错误: 虚拟机创建失败!
未能检索虚拟机名称。		 与 WSSDAgent 创建虚拟机相关的错误。 安装程序将尝试删除 VM，并将安装标记为失败。 打开提升的 PowerShell 会话并运行命令 Get-Service -Name wssdagent，验证 WSSDAgent 是否正在 Windows 主机 OS 上运行。 如果 WSSDAgent 未运行，请尝试使用 cmdlet Start-Service -name WSSDAgent 手动启动服务。 如果未启动，请共享 C:\ProgramData\wssdagent 下的内容。
此 Windows 设备不满足 Azure EFLOW 的最低要求。 请参阅 https://aka.ms/AzEFLOW-Requirements 以了解系统要求 在 EFLOW 部署期间，Deploy-EFlow PowerShell cmdlet 会检查是否满足所有的先决条件。 具体而言，将检查 Windows SKU（Windows Server 2019 和 2022、Windows 客户端专业版或客户端企业版），并且 Windows 版本至少为 17763。 验证你使用的是否是受支持的 Windows SKU 和版本。 如果使用的是 Windows 版本 17763，请确保应用所有的更新。
可用内存不足。 没有足够的 RAM 内存来创建具有已分配 VM 内存的 EFLOW VM。 默认情况下，虚拟机分配有 1024 MB。 Windows 主机 OS 至少需要有 X MB 可用才能将该内存分配给 VM。 检查可用的 Windows 主机 OS 内存，并在 Deploy-Eflow 期间使用 memoryInMb 参数来自定义内存分配。 有关 Deploy-EFlow PowerShell cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
可用的 CPU 核心数不足。 没有足够的 CPU 核心可用于创建具有已分配核心的 EFLOW VM。 默认情况下，虚拟机将分配有一个核心。 Windows 主机 OS 至少需要有一个核心才能将该核心分配给 EFLOW VM。 检查可用的 Windows 主机 OS CPU 核心，并在 Deploy-Eflow 期间使用 cpuCore 参数来自定义内存分配。 有关 Deploy-EFlow PowerShell cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
驱动器“$drive”上没有足够的磁盘空间。 没有足够的存储空间可用于创建具有已分配存储大小的 EFLOW VM。 默认情况下，VM 将使用大约 18 GB 的存储。 Windows 主机 OS 至少需要 18 GB 的可用存储空间才能将该存储分配给 EFLOW VM VHDX。 检查可用的 Windows 主机存储，并在 Deploy-Eflow 期间使用 vmDiskSize 参数来自定义存储大小。 有关 Deploy-EFlow PowerShell cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
签名无效(文件: $filePath，签名状态: ${signature.Status})
缺少签名(文件: $filePath)!
无法跟踪到 Microsoft 根证书的签名		 找不到文件的签名或签名无效。 EFLOW PSM 和 EFLOW 更新都是使用 Microsoft 证书进行签名的。 如果 Azure 代码或 Azure CA 证书在 Windows 主机 OS 中不可用，则验证将失败。 验证是否从官方 Azure 站点下载了所有内容。 此外，如果所需的证书不属于 Windows 主机，请查看安装 EFLOW 必要证书。

预配和 IoT Edge 运行时

以下部分用于解决在预配 EFLOW 虚拟机和与 IoT Edge 运行时进行交互时的常见错误。 确保了解以下 EFLOW 概念：

错误 错误说明 解决方案
用户已中止操作 对于某些 EFLOW PowerShell cmdlet，需要用户交互和确认。 -
错误，未提供设备连接字符串。
只能指定 ManualConnectionString 预配的设备连接字符串。		 使用 ManualConnectionString 设备预配时使用的参数不正确。 有关 Provision-EflowVm PowerShell cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
未指定 ManualX509 预配的 IoT 中心主机名、设备 ID 和/或标识证书/私钥参数
可能未为 DpsX509 预配指定设备连接字符串、范围 ID、注册 ID 和对称密钥
未找到 ManualX509 预配的证书和私钥文件(应在 $identityCertPath and $identityPrivKeyPath 处)		 使用 ManualX509 设备预配时使用的参数不正确。 有关 Provision-EflowVm PowerShell cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
未指定 DpsTpm 预配的范围 ID
只能指定 DpsTpm 预配的范围 ID 和注册 ID（可选）		 使用 DpsTpm 设备预配时使用的参数不正确。 有关 Provision-EflowVm PowerShell cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
DpsSymmetricKey 预配缺少范围 ID、注册 ID 或对称密钥
未指定 globalEndpoint
只能指定 DpsSymmetricKey 预配的范围 ID、注册 ID 或对称密钥		 使用 DpsSymmetricKey 设备预配时使用的参数不正确。 有关 Provision-EflowVm PowerShell cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
虚拟机不存在，首先部署它 EFLOW MSI 已安装，但从未部署 EFLOW 虚拟机。 使用 Deploy-Eflow PowerShell cmdlet 部署 EFLOW VM。
正在中止，iotedge 是之前预配的(无外设模式)! EFLOW VM 是之前预配的，重新预配时不支持无外设模式。 此问题已修复，现在重新预配时支持无外设模式
预配已由用户中止 EFLOW VM 是之前预配的，用户需要确认他们想要进行重新预配。 用户必须接受重新预配才能继续预配过程。
未能预配
未能预配 config.toml。 请手动进行预配。
预配后未运行 iotedge 服务，请手动调查		 在 EFLOW VM 中正确配置了 EFLOW 预配信息，但 IoT Edge 守护程序无法使用云预配服务预配设备。 检查 Azure IoT Edge 运行时日志。 首先，使用 Connect-EflowVm PowerShell cmdlet 连接到 EFLOW 虚拟机，然后按照对 IoT Edge 设备进行故障排除以检索 IoT Edge 日志。
从“sudo iotedge list”意外返回
正在从“$vmName”检索 iotedge 检查输出		 在 EFLOW VM 中执行 sudo iotedge list 命令返回了意外的有效负载。 通常，这与 EFLOW VM 中未正确运行的 IoT Edge 服务相关。 检查 Azure IoT Edge 运行时日志。 首先，使用 Connect-EflowVm PowerShell cmdlet 连接到 EFLOW 虚拟机，然后按照对 IoT Edge 设备进行故障排除以获取 IoT Edge 日志。
启用 DpsTpm 需要 TPM 2.0 TPM 传递仅适用于与 TPM 2.0 兼容的硬件。 这可能是由物理 TPM 造成的，或者如果 EFLOW VM 正在 Windows 主机 OS 上使用通过使用 vTPM 的嵌套虚拟化运行，也可能会造成此错误。 请确保 Windows 主机 OS 具有有效的 TPM 2.0，请查看在电脑上启用 TPM 2.0。
TPM 预配信息不可用! EFLOW VM 中的 TPM 传递二进制文件无法从 Windows 主机 OS 获取 TPM 信息。 此错误可能与 EFLOWProxy 的通信错误有关。 使用 PowerShell cmdlet Get-Service -name "EFLOW Proxy Service" 确保 EFLOW 代理服务正在运行。 如果未运行，请查看事件日志。 打开“事件查看器”>“应用程序和服务日志”->“Azure IoT Edge for Linux on Windows”。

与 VM 交互

以下部分用于解决与 EFLOW 虚拟机交互并配置 EFLOW 设备传递选项时的常见问题。 确保了解以下 EFLOW 概念：

错误 错误说明 解决方案
无法处理请求，EFLOW VM 已关闭! 尝试将配置应用到 EFLOW 虚拟机时，必须打开 VM。 如果 EFLOW VM 处于关闭状态，SSH 通道将失败，无法与 VM 通信。 使用 Start-EflowVm PowerShell cmdlet 启动 EFLOW VM。 有关 Start-EflowVm cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
无法从 wssdagent 检索虚拟机名称
错误: 找到多个虚拟机		 WSSDAgent 服务找不到 EFLOW 虚拟机。 验证 EFLOW VM 是否已启动并运行，请使用 PowerShell cmdlet Start-EflowVm。 如果使用的是客户端 SKU，请使用 hcsdiag list cmdlet，并在 VM 的 GUID 后面找到具有 wssdagent 的行，然后检查状态。 如果使用的是服务器 SKU，请转到 Hyper-V 管理器，并验证是否存在名称为 Windows-hostname 的 VM，然后检查状态。
无法使用 SSH 连接虚拟机。 正在中止.. Windows 主机 OS 无法与 EFLOW VM 建立 SSH 连接以执行必要的命令或复制文件。 通常，此问题与 Windows 和虚拟机之间的网络问题有关。 尝试使用 PowerShell cmdlet Get-EflowVmAddr，并检查分配给 VM 的 IP4Address 是否正确。 有关网络配置的详细信息，请参阅 Azure IoT Edge for Linux on Windows 网络。
来自虚拟机的意外返回统计信息 执行 Get-EflowVm PowerShell cmdlet 将检查虚拟机的状态。 如果与虚拟机的通信失败，或者 VM 中的某些 Linux bash 命令失败，则 cmdlet 将失败。 使用 Connect-EflowVm PowerShell cmdlet 检查 EFLOW VM 连接，然后尝试在 VM 中手动运行 VM 统计信息 bash 命令。
未启用 TPM 预配! 若要获取 TPM 的 TPM 预配信息，必须启用 EFLOW TPM 传递。 如果未启用 TPM 传递，cmdlet 将失败。 在获取 TPM 信息之前启用 TPM 传递。 使用 Set-EflowVmFeature PowerShell cmdlet 启用 TPM 传递。 有关 Set-EflowVmFeature PowerShell cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
提供了未知功能“$feature”。 Set-EflowVmFeature cmdlet 支持将 DpsTpm 和 Defender 作为可启用或禁用的两项功能。 有关 Set-EflowVmFeature PowerShell cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
不支持的 DDA 类型: $gpuName 目前，仅 NVIDIA Tesla T4 和 NVIDIA A2 支持 GPU DDA。 如果用户提供另一个 GPU 名称，GPU 传递将失败。 验证是否满足所有 GPU 先决条件。 有关 EFLOW GPU 支持的详细信息，请查看 Azure IoT Edge for Linux on Windows GPU 传递。
请求的 GPU 配置无效，
已启用传递，但请求的 gpuCount == $gpuCount
“$script:WssdProviderVmms”WssdProvider 不支持 GPU PassthroughType“$gpuPassthroughType”
主机不支持请求的 GPU 配置，
GPU“$gpuName”不可用
主机不支持请求的 GPU 配置，
没有足够的 GPU 可用 - 请求的($gpuCount)，可用的($($selectedGpuDevice.Count))
主机不支持请求的 GPU 配置，
不支持 GPU PassthroughType“$gpuPassthroughType”
请求的 GPU 配置无效，传递已禁用，但 gpuCount > 0”		 这些错误通常与未满足的一个或多个 GPU 依赖项相关。 确保满足所有 GPU 先决条件。 有关 EFLOW GPU 支持的详细信息，请查看 Azure IoT Edge for Linux on Windows GPU 传递。

网络

以下部分用于解决与 EFLOW 虚拟机和 Windows 主机 OS 之间的 EFLOW 网络和通信相关的常见错误。 确保了解以下 EFLOW 概念：

错误 错误说明 解决方案
虚拟交换机安装失败
找不到类型为“$switchType”的虚拟交换机“$switchName”		 创建 EFLOW VM 时，可以检查所提供的虚拟交换机是否存在并且是否具有正确的类型。 如果没有使用参数，安装将使用 Windows 客户端提供的默认交换机。 检查正在使用的虚拟交换机是否是 Windows 主机 OS 的一部分。 可以使用 PowerShell cmdlet Get-VmSwitch 检查虚拟交换机。 有关网络配置的详细信息，请参阅 Azure IoT Edge for Linux on Windows 网络。
当前的主机 OS 上不支持类型为“$switchType”的
虚拟交换机“$switchName”		 使用 Windows 客户端 SKU 时，支持外部/默认交换机。 但是，使用 Windows Server SKU 时，支持的是外部/内部交换机。 有关网络配置的详细信息，请参阅 Azure IoT Edge for Linux on Windows 网络。
无法在 ICS 类型的虚拟交换机(默认交换机)上设置静态 IP 默认交换机是在安装 Hyper-V 后 Windows 客户端 SKU 中提供的虚拟交换机。 此交换机已具有用于 IP4Address 分配的 DHCP 服务器，出于安全原因，不支持静态 IP。 如果使用默认交换机，则可以使用 Get-EflowVmAddr cmdlet 或 EFLOW VM 的主机名来获取 VM IP4Address。 如果使用主机名，请尝试使用 Windows-hostname-EFLOW.mshome.net。 有关网络配置的详细信息，请参阅 Azure IoT Edge for Linux on Windows 网络。
$dnsServer 不是有效的 IP4 地址 Set-EflowVmDnsServers cmdlet 需要有效的 IP4Addresses 列表 验证你是否提供了有效的地址列表。 可以使用 PowerShell cmdlet ipconfig /all，然后查找“DNS 服务器”条目来查看 Windows 主机 OS DNS 服务器。 例如，如果要使用 IP 10.0.1.2 和 10.0.1.3 来设置两个 DNS 服务器，请使用 Set-EflowVmDnsServers -dnsServers @("10.0.1.2", "10.0.1.3") cmdlet。
无法检索虚拟机的 IP 地址
无法检索虚拟机名称，未能获取 IP/MAC 地址
未能获取虚拟机的 MAC 地址
未能获取虚拟机的 IP 地址
无法获取主机路由。 与 $computerName 的连接测试失败。
wssdagent 未预配有预期的 vnet 资源。
缺少用于 ($vnicName) 的 EFLOW-VM 来宾接口		 由 EFLOW 虚拟机的连接问题导致的。 这些错误通常与 IP 地址更改（如果使用的是静态 IP）或分配 IP 失败（如果使用的是 DHCP 服务器）相关。 请确保使用适合的网络配置。 如果存在有效的 DHCP 服务器，则可以使用 DHCP 分配。 如果使用的是静态 IP，请确保 IP 配置正确（所有三个参数：ip4Address、ip4GatewayAddress 和 ip4PrefixLength），并且该地址未被网络中的另一台设备使用。 有关网络配置的详细信息，请参阅 Azure IoT Edge for Linux on Windows 网络。
找不到与交换机“$vnetName”相关联的适配器。
找不到与设备 ID“$adapterGuid”相关联的适配器
找不到与交换机名称“$name”相关联的适配器。
网络“$vswitchName”不存在		 由 Windows 主机 OS 和 EFLOW 虚拟机之间的网络通信错误导致的。 确保可以访问 EFLOW VM 并建立 SSH 通道。 使用 Connect-EflowVm PowerShell cmdlet 连接到虚拟机。 如果连接失败，请重新启动 EFLOW VM 并再次检查。
StaticIP 需要 ip4Address 和 ip4PrefixLength！ 在 EFLOW VM 部署期间或添加多个 NIC 时，如果使用的是静态 IP，则需要三个静态 IP 参数：ip4Address、ip4GatewayAddress、ip4PrefixLength。 有关 Deploy-EFlow PowerShell cmdlet 的详细信息，请参阅适用于 IoT Edge for Linux on Windows 的 PowerShell 函数。
找到多个“$switchType”类型的名为
“$switchName”的 VMMS 交换机		 有两个或多个具有相同名称和类型的虚拟交换机。 此环境与 EFLOW VM 安装和 VM 的生命周期冲突。 使用 Get-VmSwitch PowerShell cmdlet 检查 Windows 主机中可用的虚拟交换机，并确保每个 {name,type} 都是唯一的。

后续步骤

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

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