本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 `pcluster-diag 进行故障排除`
`pcluster-diag`是一种诊断工具，用于验证健康 Amazon ParallelCluster 节点应满足的一组条件。
当集群在运行时出现异常行为时，用`pcluster-diag`作第一步。该工具会发出 JSON 诊断报告，以帮助您了解影响集群的问题。如果您无法解决问题，请将报告附加到 Amazon 支持案例中。
从 3.16.0 版开始的每个 Amazon ParallelCluster AMI 中都包含该工具，包括官方 AMI 和您构建时使用的自定义 AMI。`pcluster build-image`如果您使用的是旧 Amazon ParallelCluster 版本，则仍然可以按照中的步骤安装该工具[低于 3.16.0 的版本](#troubleshooting-v3-pcluster-diag-updates-older)。
你可以在任何群集节点`pcluster-diag`上运行。如果你不知道问题出在哪里，请在头节点上运行它。
**主要特性**
+ **上下文感知 ** ——在启动时，它会读取节点类型和已部署的集群配置，然后仅运行适用的检查。检查您的集群未使用的功能将被报告为已跳过。
+ **Read-only 默认情况下**，它永远不会更改集群的配置。非只读支票需要您的明确批准才能运行，如果您拒绝，则将其记录为跳过。
+ **一次运行即可完成 ** ——失败的检查永远不会停止其他检查。每一次适用的检查都会在每次调用时运行，因此，根据可用的检查，一次运行即可获得节点的完整情况。
## 显示可用支票
要查看该工具将执行哪些检查，请使用子命令，该`describe-checks`子命令返回每个注册支票的 JSON 数组，每个检查都有其 ID 和描述。
```
$ pcluster-diag describe-checks
[
{
"check_id": "...",
"check_description": "..."
},
...
]
```
## 执行检查
连接到要诊断的节点，然后以 root 身份执行`run`子命令。
```
$ sudo pcluster-diag run
```
`pcluster-diag`写入两个单独的流：
+ 标准错误的进度日志。
+ 将JSON报告转换为标准输出。同一报告还保存到当前目录下的带有时间戳的文件`./pcluster-diag-output/`中。
可用选项如下：
`--output-file` {{path}}
写入 JSON 报告的文件。例如，默认为下方的`./pcluster-diag-output/`带有时间戳的文件。`./pcluster-diag-output/pcluster-diag-report-2026-08-04T10-12-00.json`
`-y`, `--yes`
批准每张需要确认的支票，无需提示。当你`pcluster-diag`从脚本运行时使用它。
`--version`
打印`pcluster-diag`版本。
`--help`
打印使用信息。`pcluster-diag run --help`打印`run`子命令的选项。
## 解释报告
`pcluster-diag`发出一个 JSON 报告，说明它运行的每一次检查，无论检查是通过、警告、失败还是被跳过。`context`描述了被诊断的节点。该报告的总体结构如下：
```
{
"context": { ... },
"results": [
{
"check_id": "...",
"check_description": "...",
"status": "...",
"errors": [ { "code": "...", "message": "..." } ],
"warnings": [ { "code": "...", "message": "..." } ],
"infos": [ { "code": "...", "message": "..." } ]
}
]
}
```
### 检查状态
每张`status`支票都会告诉你该怎么做。
| Status | 含义 | 操作 |
| --- | --- | --- |
| `PASSED` | 此检查没有发现任何问题。 | - |
| `WARNING` | 此检查发现了一些可能导致节点出现问题的东西。 | 查看清`warnings`单并解决任何可能重要的问题。 |
| `FAILURE` | 此检查在节点上发现了问题。 | 查看清`errors`单并解决所有问题。 |
| `CHECK_ERROR` | 检查无法完成，因此无法确认状态。 | 将其视为没有定论，而不是问题。将错误报告给 Amazon 支持部门，因为这可能是未处理错误的信号。 |
| `SKIPPED_NOT_APPLICABLE` | 该检查不适用于此节点类型或您的集群配置。 | 没什么。这是您的集群未使用的功能的预期状态。 |
| `SKIPPED_BY_USER` | 这张支票需要你确认，但你拒绝了。 | 重新运行`pcluster-diag`，出现提示时批准支票。 |
如果每张支票都有报告`PASSED`，没有`pcluster-diag`发现任何问题。但是，的覆盖范围`pcluster-diag`并不全面，并且会随着每个版本的发布而增加。健康的诊断并不能保证集群运行正常。
### 查看调查结果
检查结果可以包含三种结果，每种结果都有 a `code` 和 a `message`。
+ `errors`，已编码`E{{n}}`，是检查失败的原因。保留代码`E0`仅用于导致无法正确执行检查的内部错误。
+ `warnings`，经过编码`W{{n}}`，是非致命观察结果。
+ `infos`，已编码`I{{n}}`，是上下文注释。
## 从中获取最新的 `pcluster-diag` GitHub
`pcluster-diag`适用于所有 Amazon ParallelCluster 版本 3.16.0 及更高版本，也可以通过一些额外步骤安装在旧版本上。
新的检查和改进的诊断消息已放入网站的 [ aws-parallelcluster-cookbook 存储库](https://github.com/aws/aws-parallelcluster-cookbook)中。GitHub要在不等待下一个 Amazon ParallelCluster 版本的情况下使用最新的支票，请按照相应 Amazon ParallelCluster 版本的步骤进行操作。
### 版本 3.16.0 及更高版本
在 3.16.0 及更高 Amazon ParallelCluster 版本中，该`pcluster-diag`命令已安装并在上可用。`PATH`
要从`develop`分支更新工具，请在要执行该工具的节点上运行以下命令。
```
$ curl -fL https://github.com/aws/aws-parallelcluster-cookbook/archive/refs/heads/develop.tar.gz \
| sudo tar -xz --strip-components=5 -C /opt/parallelcluster/sources/pcluster-diag \
--wildcards '*/cookbooks/aws-parallelcluster-platform/files/pcluster-diag/*'
```
验证该工具是否正常运行：
```
$ sudo pcluster-diag describe-checks
```
要使用提示以外的版本`develop`，请`develop`在 URL 中替换为所需的分支或标签，例如分`release-*`支。
记住以下内容：
+ 刷新仅适用于您运行它的节点。在要使用新检查诊断的每个节点上重复此操作。
+ 工具源代码已内置到 AMI 中，因此被替换的节点会返回来自 AMI 的版本。
### 低于 3.16.0 的版本
在 3.16.0 之前的 Amazon ParallelCluster 版本中，该`pcluster-diag`命令未安装在节点上。
要从`develop`分支安装该工具，请在要执行该工具的节点上运行以下命令。
```
$ sudo mkdir -p /opt/parallelcluster/sources/pcluster-diag
curl -fL https://github.com/aws/aws-parallelcluster-cookbook/archive/refs/heads/develop.tar.gz \
| sudo tar -xz --strip-components=5 -C /opt/parallelcluster/sources/pcluster-diag \
--wildcards '*/cookbooks/aws-parallelcluster-platform/files/pcluster-diag/*'
```
验证该工具是否正常运行：
```
$ PYTHONPATH=/opt/parallelcluster/sources/pcluster-diag /opt/parallelcluster/pyenv/versions/{{3.12.8}}/envs/cookbook_virtualenv/bin/python3 -m pcluster_diag.cli describe-checks
```