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

IoT 中心设备更新故障排除指南

项目
05/24/2023

本文档列出了设备更新用户报告的一些常见问题。如果遇到本故障排除指南中未出现的问题，请参阅联系 Microsoft 支持部门部分以记录你的情况。

导入更新

问：将 Device Update 实例连接到 IoT 中心实例时遇到问题

请确保根据设备更新资源文档正确配置 IoT 中心消息路由。

可能未正确配置访问权限。请确保根据设备更新访问控制文档正确配置访问权限。

问：将内容导入 Device Update 服务时遇到 500 类型的错误

500 范围内的错误代码表示设备更新服务可能出现问题。请等待 5 分钟，然后重试。如果相同错误仍然存在，请按照联系 Microsoft 支持部门部分中的说明向 Microsoft 提出支持请求。

问：我想保留相同的兼容性属性(将更新定位到同一设备类型)，但更改导入清单中的提供程序或名称。但是当我这样做时，我收到错误“失败: 由于超出限制而导致导入更新时出错”

同一完整的兼容性属性集不能与多个更新提供程序和名称组合一起使用。这允许设备更新服务确定哪些更新应可用于部署到给定设备。如果需要在单个设备上更新多个组件或分区，代理更新功能提供此功能。

问：我在导入内容时遇到了一条错误消息，想要详细了解这个错误

要详细了解与导入相关的错误消息，请参阅设备更新错误代码文档。

设备故障

问：如何确保我的设备已连接到 IoT 中心设备更新？

通过检查设备是否在 Azure 门户合规性视图的“未分组”设备部分下显示，来验证设备是否已连接到设备更新。

问：一个或多个设备更新失败

设备更新失败可能存在许多根本原因。请验证此设备：1) 是否连接到 IoT 中心实例，2) 是否连接到设备更新实例，以及 3) 传递优化 (DO) 服务是否正在运行。如果设备满足这三个条件，请按照联系 Microsoft 支持部门部分中的说明向 Microsoft 提出支持请求。

问：我的 Device Update 代理无法启动

Device Update 代理启动失败的最常见原因之一是配置文件 (du-config.json) 格式不正确。请参阅配置文件文档，确保代理配置正确。请注意，配置文件中的所有值都必须使用双引号。

部署更新

问：我已将更新部署到设备，但合规性状态指出设备未使用最新更新。应采取何种操作？

设备合规性状态最多需要 5 分钟才会刷新。请等待，然后重新检查。

问：设备部署状态显示不兼容，我该怎么办？

将目标设备连接到 IoT 中心后，设备的制造商和型号属性可能已更改，导致设备现在被视为与当前部署的更新内容不兼容。

检查 ADU Core 接口查看设备报告给设备更新服务的制造商和型号，确保其与正在部署的更新内容的导入清单中指定的制造商和型号相匹配。可以使用设备更新配置文件更改给定设备的这些属性。

问：看到部署处于“活动”阶段，但没有任何设备“正在进行”更新。应采取何种操作？

请确保部署的开始日期是否未设置为将来的日期。为安全起见，创建新部署时，部署的开始日期默认为第二天，除非进行显式更改。你可等待部署开始日期到来，也可取消正在进行的部署，并创建具有所需开始日期的新部署。

问：尝试将设备分组，但在创建组时，在下拉菜单中没有看到标记

确保根据设备更新资源文档在 IoT 中心中正确配置消息路由。配置路由后，必须再次对设备进行标记。

另一个根本原因可能是，在将设备连接到 IoT 中心设备更新之前已应用了标记。请确保已将设备连接到设备更新。通过检查设备是否在合规性视图的“未分组”设备下显示，来验证设备是否已连接到 IoT 中心设备更新。临时添加一个其他值的标记，然后在连接设备后再次添加预期标记。

如果使用的是设备预配服务 (DPS)，请确保在预配设备之后标记设备，而不是在设备创建过程中。如果已在设备创建步骤期间标记设备，则必须在设备预配后使用其他值临时标记设备，然后再次添加预期标记。

问：部署已成功完成，但某些设备更新失败

这可能是由失败的设备上的客户端错误引起。请参阅本故障排除指南的“设备故障”部分。

问：尝试启动部署时遇到 UX 错误

这可能是由服务/UX bug 或 API 权限问题引起的。请按照联系 Microsoft 支持部门部分中的说明向 Microsoft 提出支持请求。

问：启动了部署，但未完成

这可能是由服务性能问题、服务 bug 或客户端 bug 引起的。请在 10 分钟后重新尝试部署。如果遇到相同问题，请拉取设备日志并参阅本故障排除指南的“设备故障”部分。如果相同问题仍然存在，请按照联系 Microsoft 支持部门部分中的说明向 Microsoft 提出支持请求。

问：我从设备级别代理进行了迁移，现在可以在设备上将代理添加为模块标识。我的更新显示为“正在进行中”，虽然它已应用到了设备

如果你未删除通过设备孪生通信的较旧代理，则可能会导致此问题。将 Device Update 代理预配为模块（参见操作方法）时，设备和 Device Update 服务之间的所有通信都通过模块孪生进行。因此，请记住：在创建组时标记设备的模块孪生；所有通信都必须通过模块孪生进行。

将更新下载到设备

问：当设备断开连接一段时间后重新连接时，如何恢复下载？

恢复连接后 24 小时内将自行恢复下载。 24 小时后，将需要用户重新启动下载。

使用 Microsoft 联网缓存 (MCC)

问：尝试在 IoT Edge 设备上部署 MCC 模块时遇到问题

请参阅 IoT Edge 文档了解如何将 Edge 模块部署到 IoT Edge 设备。可以通过导航到 http://localhost:5100/Summary.，检查 IoT Edge 设备上是否正在成功运行 MCC 模块

问：其中一个 IoT 设备尝试通过 MCC 下载更新，但失败了

有多个问题可能导致 IoT 设备无法连接到 MCC。为对问题做出诊断，请从失败的设备中收集 DO 客户端和 Nginx 的日志（有关收集客户端日志的说明，请参阅联系 Microsoft 支持部门部分）。

设备可能无法从 Internet 拉取内容以传递到其 MCC 模块，因为它使用的 URL 未获得允许。若要确定是否如此，需要在 Azure 门户中检查 IoT Edge 环境变量。

排查 Azure 门户中缺少实例的问题

问：选择“齿轮”图标时，看不到 Device Update for IoT Hub 实例

导致此问题的可能原因有多个。有关故障排除步骤，请参阅下文。

Device Update 实例需要与同一资源组和订阅中的 Azure IoT 中心相关联。如果已将 Device Update 实例或中心移到其他资源组或订阅，则可能不会在 Azure 门户中看到实例。需要执行以下步骤之一才能继续使用 Device Update for IoT Hub：

将移动的项返回其原始配置。
如果仅将 IoT 中心从一个资源组移到另一个资源组，请使用 IoT 中心的新 resourceId 修改 Device Update 实例。
如果已将项从一个订阅移到另一个订阅，请确保 Device Update 帐户和 IoT 中心位于同一订阅中，然后使用 IoT 中心的新 resourceId 修改 Device Update 实例。

若要通过 Azure 门户中的 IoT 中心体验访问 Device Update 功能，IoT 中心和 Device Update for IoT Hub 帐户至少需要读取级别权限。

若要管理 IoT 中心的权限，请执行以下操作：
- 从 Azure 门户选择中心
- 从左侧导航栏中选择“访问控制(IAM)”。
- 选择“添加角色分配”。
- 选择至少具有读取访问权限的角色，然后选择“下一步”。
- 在“成员”旁边选择“+ 选择成员”。
- 在右侧浮出控件中添加帐户，然后选择“选择”按钮。
- 选择“查看 + 分配”。
若要管理 Device Update for IoT Hub 帐户的权限，请让帐户所有者执行以下步骤：
- 从 Azure 门户选择 Device Update 帐户。
- 从左侧导航栏中选择“访问控制(IAM)”。
- 选择“添加角色分配”。
- 选择“读取者”角色（或具有等效权限的角色）。
- 在“成员”旁边选择“+ 选择成员”。
- 在右侧浮出控件中添加帐户，然后选择“选择”按钮。
- 选择“查看 + 分配”。

详细了解 Device Update 服务的基于角色的访问控制。

请联系 Microsoft 支持人员

如果遇到使用上述 FAQ 无法解决的问题，可以通过 Azure 门户接口向 Microsoft 支持部门提出支持请求。根据你指出的问题所属类别，你可能需要收集和共享其他数据，以帮助 Microsoft 支持部门调查你的问题。

请参阅以下说明了解如何收集每种数据类型。

可以使用 getDevice 在 API 的有效负载响应中检查其他信息。

此外，以下信息有助于确定问题的根本原因：

尝试进行更新的设备类型（IoT Edge 网关等）
使用的设备更新客户端类型（基于映像、基于包、模拟器）
设备运行的 OS
有关设备体系结构的详细信息
曾经是否成功使用设备更新来更新过设备

如果可以提供上述任何信息，请将其包含在问题说明中。

收集客户端日志

在 Raspberry Pi 设备上，可在以下位置找到两组日志：
```
/adu/logs
```
```
/var/cache/do-client-lite/log
```
对于打包的客户端，可在以下位置找到日志：
```
/var/log/adu
```
```
/var/cache/do-client-lite/log
```
对于模拟器，可在以下位置找到日志：
```
/tmp/aduc-logs
```

错误代码

报告有关导入更新、设备故障或部署更新的问题时，你可能需要提供错误代码。

通过查看 ADUCoreInterface 接口，可以获取错误代码。有关如何分析错误代码以便自行诊断和排除故障的信息，请参阅设备更新错误代码文档。

跟踪 ID

报告有关导入或部署更新的问题时，你可能需要提供跟踪 ID。

在 API 响应或 Azure 门户用户界面的“导入历史记录”部分中，可以找到给定用户操作的跟踪 ID。

目前，仅能通过 API 响应来访问部署操作的跟踪 ID。

部署 ID

报告有关部署更新的问题时，你可能需要提供部署 ID。

部署 ID 是用户在调用 API 来启动部署时创建的。

目前，从 Azure 门户用户界面启动的部署的部署 ID 会自动生成，且不会向用户显示。

IoT 中心实例名称

报告有关设备故障或部署更新的问题时，你可能需要提供 IoT 中心实例的名称。

IoT 中心名称是用户在首次预配时选择的名称。

设备更新帐户名称

报告有关导入更新、设备故障或部署更新的问题时，你可能需要提供设备更新帐户的名称。

设备更新帐户名称是用户在首次注册服务时选择的名称。可以在设备更新资源文档中找到更多信息。

设备更新实例名称

报告有关导入更新、设备故障或部署更新的问题时，你可能需要提供设备更新实例的名称。

设备更新实例名称是用户在首次预配时选择的名称。可以在设备更新资源文档中找到更多信息。

设备 ID

报告有关设备故障或部署更新的问题时，你可能需要提供设备 ID。

设备 ID 是客户在首次预配设备时定义的。此外，也可以从设备的设备孪生中检索它。

更新 ID

报告有关部署更新的问题时，你可能需要提供更新 ID。

更新 ID 是客户在启动部署时定义的。

Nginx 日志

报告有关 Microsoft 联网缓存的问题时，你可能需要提供 Nginx 日志。

ADU-conf.txt

报告有关部署更新的问题时，你可能需要提供设备更新配置文件（“adu-conf.txt”）。

配置文件是可选的，它由用户按照设备更新配置文档中的说明来创建。

导入清单

报告有关导入或部署更新的问题时，你可能需要提供导入清单文件。

导入清单是客户在将更新内容导入设备更新服务时创建的文件。

后续步骤

详细了解 Device Update 错误代码

通过