本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# V2 版 IDT 故障排除 AWS IoT Greengrass
IDT fo AWS IoT Greengrass r V2 会根据错误的类型将错误写入不同位置。IDT 会将错误写入控制台、日志文件和测试报告中。
## 查找错误的位置
在测试运行时，控制台上会显示高级别错误，并且在所有测试完成后会显示失败测试的摘要。`awsiotdevicetester_report.xml` 包含导致测试失败的所有错误的摘要。IDT 将每个测试运行的日志文件都存储在一个包含 UUID 的目录中，用于在测试运行期间在控制台上显示的测试执行。
IDT 测试日志目录是 `{{}}/results/{{}}/logs/`。此目录包含表中显示的以下文件。这对于调试非常有用。
| 文件 | 说明 |
| --- | --- |
| test\_manager.log | 测试运行时写入控制台的日志。此文件末尾的结果摘要包含失败测试的列表。
此文件中的警告和错误日志可以为您提供有关失败的一些信息。 |
| {{test-group-id}}/{{test-case-id}}/{{test-name}}.log | 测试组中特定测试的详细日志。对于部署 Greengrass 组件的测试，测试用例日志文件称为 greengrass-test-run.log。 |
| {{test-group-id}}/{{test-case-id}}/greengrass.log | AWS IoT Greengrass 核心软件的详细日志。IDT 在运行在设备上安装 C AWS IoT Greengrass ore 软件的测试时，会从被测设备复制此文件。有关此日志文件中消息的更多信息，请参阅[故障排除 AWS IoT Greengrass V2](troubleshooting.md)。 |
| {{test-group-id}}/{{test-case-id}}/{{component-name}}.log | 测试运行期间部署的 Greengrass 组件的详细日志。IDT 在运行部署特定组件的测试时，会从被测设备复制组件日志文件。每个组件日志文件的名称对应于已部署组件的名称。有关此日志文件中消息的更多信息，请参阅[故障排除 AWS IoT Greengrass V2](troubleshooting.md)。 |
## 解决 AWS IoT Greengrass V2 错误的 IDT
在运行 IDT 之前 AWS IoT Greengrass，请准备好正确的配置文件。如果接收解析和配置错误，第一步应找到并使用适合环境的配置模板。
如果仍有问题，请参阅以下调试过程。
**Topics**
+ [别名解析错误](#alias-resolution-errors)
+ [冲突错误](#conflict-error)
+ [无法启动测试错误](#could-not-start-test)
+ [Docker 资格认证镜像存在错误](#docker-qualification-image-exists)
+ [无法读取凭证](#failed-to-read-credential-windows)
+ [Greengrass 的 PreInstalled 指导错误](#guice-errors)
+ [签名异常无效](#invalid-signature-exception-lambda)
+ [机器学习资格认证错误](#machine-learning-qualification-failure)
+ [开放测试框架（OTF）部署失败](#otf-deployment-failure)
+ [解析错误](#parse-error)
+ [权限被拒绝错误](#permission-denied-pwd-sudo)
+ [资格认证报告生成错误](#qualification-report-policy-error)
+ [缺少必需参数错误](#required-param-missing)
+ [macOS 上的安全例外](#security-exception-macos)
+ [SSH 连接错误](#ssh-connect-errors)
+ [流管理器资格认证错误](#stream-manager-qualification-failure)
+ [超时错误](#test-timeout)
+ [版本检查错误](#version-compatibility-check-failure)
### 别名解析错误
运行自定义测试套件时，您可能会在控制台和 `test_manager.log` 中看到以下错误。
```
Couldn't resolve placeholders: couldn't do a json lookup: index out of range
```
当 IDT 测试编排工具中配置的别名无法正确解析或者配置文件中不存在已解析的值时，就会发生此错误。要解决此错误，请确保 `device.json` 和 `userdata.json ` 包含测试套件所需的正确信息。有关 AWS IoT Greengrass 资格认证所需的配置的信息，请参见[配置 IDT 设置以运行 AWS IoT Greengrass 资格套件](set-config.md)。
### 冲突错误
当您在多台设备上同时运行 AWS IoT Greengrass 资格套件时，您可能会看到以下错误。
```
ConflictException: Component [com.example.IDTHelloWorld : 1.0.0] for account [{{account-id}}] already exists with state: [DEPLOYABLE] { RespMetadata: { StatusCode: 409, RequestID: “{{id}}” }, Message_: “Component [com.example.IDTHelloWorld : 1.0.0] for account [{{account-id}}] already exists with state: [DEPLOYABLE]” }
```
AWS IoT Greengrass 资格套件尚不支持并行测试执行。按顺序为每台设备运行资格认证套件。
### 无法启动测试错误
您可能会遇到错误，这些错误指向测试尝试开始时发生的故障。有几种可能的原因，因此，请执行以下操作：
+ 确保执行命令中的池名称实际存在。IDT 直接从 `device.json` 文件中引用池名称。
+ 确保池中的设备具有正确的配置参数。
### Docker 资格认证镜像存在错误
Docker 应用程序管理器资格认证测试使用 Amazon ECR 中的 `amazon/amazon-ec2-metadata-mock` 容器镜像来鉴定被测设备。
如果镜像已存在于被测设备上的 Docker 容器中，则可能会收到以下错误。
```
The Docker image amazon/amazon-ec2-metadata-mock:{{version}} already exists on the device.
```
如果您之前下载了此镜像并在设备上运行了 `amazon/amazon-ec2-metadata-mock` 容器，请务必在运行资格认证测试之前从被测设备中移除此镜像。
### 无法读取凭证
在测试 Windows 设备时，如果用于连接被测设备的用户未在该设备的凭证管理器中设置，则可能会在 `greengrass.log` 文件中遇到 `Failed to read credential` 错误。
要解决此错误，请在被测设备的凭证管理器中配置 IDT 用户的用户名和密码。
有关更多信息，请参阅 [为 Windows 设备配置用户凭证](device-config-setup.md#configure-windows-user-for-idt)。
### Greengrass 的 PreInstalled 指导错误
在使用 Gre PreInstalled engrass 运行 IDT 时，如果遇到`ErrorInCustomProvider`或的错误`Guice`，请检查文件是否`userdata.json`已`InstalledDirRootOnDevice`设置为 Greengrass 安装文件夹。IDT 检查 `/config/effectiveConfig.yaml` 下的文件 `effectiveConfig.yaml`。
有关更多信息，请参阅 [为 Windows 设备配置用户凭证](device-config-setup.md#configure-windows-user-for-idt)。
### 签名异常无效
运行 Lambda 资格认证测试时，如果 IDT 主机遇到网络访问问题，则可能会遇到 `invalidsignatureexception` 错误。重置路由器并再次运行测试。
### 机器学习资格认证错误
在运行机器学习 (ML) 资格测试时，如果您的设备不符合部署 AWS提供的机器学习组件的[要求](dlr-component.md#dlr-component-requirements)，则可能会遇到资格认证失败的情况。要排查 ML 资格认证错误，请执行以下操作：
+ 在组件日志中查找测试运行期间部署的组件的错误详细信息。组件日志位于 `{{}}/results/{{}}/logs/{{}}` 目录中。
+ 将 `-Dgg.persist=installed.software` 参数添加到失败测试用例的 `test.json` 文件中。`test.json` 文件位于 `{{}}/tests/GGV2Q_{{version}} directory. ` 中。
### 开放测试框架（OTF）部署失败
如果 OTF 测试未能完成部署，则可能的原因可能是为 `TempResourcesDirOnDevice` 和 `InstallationDirRootOnDevice` 的父文件夹设置了权限。要正确设置此文件夹的权限，请运行以下命令。将 `{{folder-name}}` 替换为父文件夹的名称。
```
sudo chmod 755 {{folder-name}}
```
### 解析错误
有时候，JSON 配置中的拼写错误可能会导致解析错误。大部分情况下，问题是因 JSON 文件中漏掉括号、逗号或引号所导致。IDT 执行 JSON 验证并输入调试信息。它输出发生错误的行、行号以及语法错误的列号。这些信息应该足以帮助您修复错误，但是如果您仍然找不到错误，则可以在IDE、Atom或Sublime等文本编辑器中手动进行验证，也可以通过诸如此类的在线工具进行验证。 JSONLint
### 权限被拒绝错误
IDT 将对被测设备中的各种目录和文件执行操作。其中一些操作需要根用户访问权限。要自动执行这些操作，IDT 必须能够在不键入密码的情况下使用 sudo 运行命令。
请按照以下步骤操作，以允许在不键入密码的情况下进行 sudo 访问。
**注意**
`user` 和 `username` 是指 IDT 用来访问所测试设备的 SSH 用户。
1. 使用 **sudo usermod -aG sudo {{}}** 将 SSH 用户添加到 sudo 组。
1. 注销，然后重新登录，以使更改生效。
1. 打开 `/etc/sudoers` 文件，并将以下行添加到文件末尾：`{{}} ALL=(ALL) NOPASSWD: ALL`
**注意**
作为最佳实践，我们建议您在编辑 `/etc/sudoers` 时使用 **sudo visudo**。
### 资格认证报告生成错误
IDT 支持四个最新`{{major}}.{{minor}}`版本的 AWS IoT Greengrass V2 资格套件 (GGV2Q) 来生成资格报告，您可以提交这些报告 AWS Partner Network 以将您的设备包含在设备目录中 AWS Partner 。早期版本的资格认证套件不生成资格认证报告。
如果您对支持策略有疑问，请联系 [AWS 支持](https://aws.amazon.com/contact-us/)。
### 缺少必需参数错误
当 IDT 添加新功能时，它可能会对配置文件进行更改。使用旧配置文件可能会破坏您的配置。如果出现这种情况，`/results/{{}}/logs` 下的 `{{}}.log` 文件明确列出了所有缺少的参数。IDT 还将验证 JSON 配置文件架构，以验证您是否使用最新支持的版本。
### macOS 上的安全例外
在 macOS 主机上运行 IDT 时，它会阻止 IDT 运行。要运行 IDT，请向可执行文件授予安全异常，这是 IDT 运行时功能的一部分。当主机上显示警告消息时，请对每个适用的可执行文件执行以下操作：
**要向 IDT 可执行文件授予安全异常，请执行以下操作**
1. 在 macOS 电脑上，在苹果菜单中打开**系统偏好设置**。
1. 选择**安全与隐私**，然后在**通用**选项卡上，选择锁定图标以更改安全设置。
1. 如果 `devicetester_mac_x86-64` 受阻，查找消息 `"devicetester_mac_x86-64" was blocked from use because it is not from an identified developer.` 并选择**仍然允许**。
1. 恢复 IDT 测试，直到完成所有涉及的可执行文件。
### SSH 连接错误
当 IDT 无法连接到被测设备时，会在 `/results/{{}}/logs/{{}}.log` 中记录连接失败。SSH 消息将显示在此日志文件的顶部，因为连接到被测设备是 IDT 最先执行的操作之一。
大多数 Windows 配置使用 Pu TTy 终端应用程序连接到 Linux 主机。该应用程序要求将标准 PEM 私有密钥文件转换为称为 PPK 的专有 Windows 格式。如果您在 `device.json` 文件中配置 SSH，请使用 PEM 文件。如果您使用 PPK 文件，IDT 将无法与 AWS IoT Greengrass 设备建立 SSH 连接，也无法运行测试。
从 IDT v4.4.0 开始，如果您尚未在被测设备上启用 SFTP，则可能会在日志文件中看到以下错误。
```
SSH connection failed with EOF
```
要解决此错误，请在设备上启用 SFTP。
### 流管理器资格认证错误
运行流管理器资格认证测试时，您可能会在 `com.aws.StreamManagerExport.log` 文件中看到以下错误。
```
Failed to upload data to S3
```
当流管理器使用设备上`~/root/.aws/credentials`文件中的 AWS 凭证而不是使用 IDT 导出到被测设备的环境凭证时，可能会发生此错误。为防止出现此问题，请删除设备上的 `credentials` 文件，然后重新运行资格认证测试。
### 超时错误
您可以通过指定超时乘数来增加每个测试的超时，该超时乘数应用于每个测试超时的默认值。为此标志配置的任何值都必须大于或等于 1.0。
要使用超时乘数，请在运行测试时使用标志 `--timeout-multiplier`。例如：
```
./devicetester_linux run-suite --suite-id GGV2Q_1.0.0 --pool-id DevicePool1 --timeout-multiplier 2.5
```
有关更多信息，请运行 `run-suite --help`。
由于配置问题而无法完成 IDT 测试用例时，会出现一些超时错误。您无法通过增加超时乘数来解决这些错误。使用测试运行中的日志对基础配置问题进行故障排除。
+ 如果 MQTT 或 Lambda 组件日志包含 `Access denied` 错误，则 Greengrass 安装文件夹可能没有正确的文件权限。对 `userdata.json` 文件中定义的安装路径中的每个文件夹运行以下命令。
```
sudo chmod 755 {{folder-name}}
```
+ 如果 Greengrass 日志表明 Greengrass CLI 部署尚未完成，请执行以下操作：
+ 验证 `bash` 是否已安装在被测设备上。
+ 如果 `userdata.json` 文件包含 `GreengrassCliVersion` 配置参数，请将其移除。此参数在 IDT v4.1.0 及更高版本中已弃用。有关更多信息，请参阅 [配置 userdata.json](set-config.md#userdata-config)。
+ 如果 Lambda 部署测试失败并显示错误消息“Validating Lambda publish: time out”，并且在测试日志文件（`idt-gg2-lambda-function-idt-{{}}.log`）中收到一条显示 `Error: Could not find or load main class com.amazonaws.greengrass.runtime.LambdaRuntime.` 的错误，请执行以下操作：
+ 验证 `userdata.json` 文件中的 `InstallationDirRootOnDevice` 使用了哪个文件夹。
+ 确保在您的设备上设置了正确的用户权限。有关更多详细信息，请参阅[在设备上配置用户权限](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-config-setup.html#root-access)。
### 版本检查错误
当 IDT AWS 用户的用户证书没有所需的 IAM 权限时，IDT 会发出以下错误。
```
Failed to check version compatibility
```
没有所需 IAM 权限的 AWS 用户。