# S3 Files 故障排除
<a name="s3-files-troubleshooting"></a>

本页有助于帮助您诊断和解决 S3 Files 的常见问题。
+ [挂载命令失败](#s3-files-troubleshooting-mount-fails)
+ [对文件操作的权限被拒绝](#s3-files-troubleshooting-permission-denied)
+ [智能读取路由不起作用](#s3-files-troubleshooting-read-routing)
+ [文件系统持续返回 NFS 服务器错误](#s3-files-troubleshooting-encrypted-fs)
+ [文件系统写入后 S3 存储桶中缺少对象](#s3-files-troubleshooting-missing-object)
+ [S3 对象在文件系统中不可见](#s3-files-troubleshooting-object-not-visible)
+ [文件出现在丢失找回目录中](#s3-files-troubleshooting-lost-found)
+ [同步落后](#s3-files-troubleshooting-sync-behind)
+ [启用客户端调试日志](#s3-files-troubleshooting-debug-logs)

## 挂载命令失败
<a name="s3-files-troubleshooting-mount-fails"></a>

`mount -t s3files` 命令失败并显示错误。

**常见原因和操作：**
+ **“mount.s3files: command not found”**：S3 Files 客户端（amazon-efs-utils）未安装或低于版本 3.0.0。安装或升级客户端。有关更多信息，请参阅 [S3 Files 的先决条件](s3-files-prereq-policies.md)。
+ **“Failed to resolve file system DNS name”**：运行您的 EC2 实例的可用区中没有挂载目标。在该可用区中创建一个挂载目标，或者在具有挂载目标的可用区中启动您的实例。有关更多信息，请参阅 [创建挂载目标](s3-files-mount-targets-creating.md)。
+ **Connection timed out**：安全组配置不支持 NFS 流量。验证挂载目标的安全组是否支持通过端口 2049 从实例的安全组入站的 TCP，以及实例的安全组是否支持通过端口 2049 的出站 TCP 进入挂载目标的安全组。有关更多信息，请参阅 [S3 Files 的先决条件](s3-files-prereq-policies.md)。
+ **"Access denied" during mount**：附加到计算资源的 IAM 角色没有所需的 S3 Files 权限。验证该角色是否已附加 `AmazonS3FilesClientFullAccess` 或 `AmazonS3FilesClientReadOnlyAccess` 托管式策略，或者至少具有 `s3files:ClientMount` 权限。有关更多信息，请参阅 [S3 Files 的先决条件](s3-files-prereq-policies.md)。
+ **botocore not installed**：挂载助手需要 botocore 才能与 AWS 服务进行交互。按照 GitHub 上 amazon-efs-utils 自述文件中的说明安装 botocore。

## 对文件操作的权限被拒绝
<a name="s3-files-troubleshooting-permission-denied"></a>

您可以挂载文件系统，但在读取、写入或访问文件时收到“权限被拒绝”或“不允许的操作”错误。

**常见原因和操作：**
+ **缺少写入权限**：如果您能够读取但不能写入，请验证附加到计算资源的 IAM 角色是否包含 `s3files:ClientWrite` 权限，或者附加 `AmazonS3FilesClientReadWriteAccess` 或 `AmazonS3FilesClientFullAccess` 托管式策略。有关更多信息，请参阅 [Amazon S3 Files 的 AWS 托管式策略](s3-files-security-iam-awsmanpol.md)。
+ **缺少根访问权限**：如果您在访问根用户（UID 0）拥有的文件时收到权限错误，则您的 IAM 角色可能没有 `s3files:ClientRootAccess` 权限。如果没有此权限，则所有操作均以 NFS 匿名用户（通常为 nfsnobody）的身份执行，该用户可能无权访问文件。附加 `AmazonS3FilesClientFullAccess` 托管式策略或将 `s3files:ClientRootAccess` 添加到您的策略中。
+ **文件系统策略拒绝访问**：如果您附加了文件系统策略，请确认该策略不会拒绝您的客户端所需的操作。基于身份的策略或文件系统策略中的“允许”足以进行访问。有关更多信息，请参阅 [S3 Files 如何与 IAM 结合使用](s3-files-security-iam.md)。
+ **POSIX 权限不匹配**：S3 Files 对文件和目录强制执行标准 POSIX 权限（所有者、组等）。如果您的应用程序以与文件的所有者或组不匹配的用户身份运行，即使 IAM 权限正确，访问也可能会被拒绝。使用接入点为所有请求强制使用特定的 UID/GID。有关更多信息，请参阅 [为 S3 文件系统创建接入点](s3-files-access-points-creating.md)。

## 智能读取路由不起作用
<a name="s3-files-troubleshooting-read-routing"></a>

S3 Files 执行智能读取路由，因为它会自动将读取请求路由到最适合它们的存储层，同时保持完整的文件系统语义，包括一致性、锁定和 POSIX 权限。可以从高性能存储中对活跃使用的文件进行少量的随机读取，以实现低延迟。对不在文件系统上的数据的大量顺序读取和读取直接从 S3 存储桶提供，以实现高吞吐量，而不收取文件系统数据费用。

如果其中一个客户端连接指标（`NFSConnectionAccessible`、`S3BucketAccessible` 和 `S3BucketReachable`）显示 0，或者您看不到预期的读取吞吐量，则智能读取路由可能无法正常工作。

**常见原因和操作：**
+ **计算角色上缺少 S3 内联策略**：附加到计算资源的 IAM 角色必须包含内联策略，此策略授予对关联 S3 存储桶的 `s3:GetObject` 和 `s3:GetObjectVersion`。如果没有此策略，挂载助手将无法直接从 S3 读取，并且所有读取都要通过文件系统。有关更多信息，请参阅 [S3 Files 的先决条件](s3-files-prereq-policies.md)。
+ **无法访问 S3 存储桶**：请检查 `S3BucketReachable` 指标。如果它显示 0，请验证计算资源是否具有对 S3 的网络访问权限（例如，通过 VPC 端点或 NAT 网关）。
+ **文件已修改**：只有当文件未通过文件系统进行修改时，读取才会直接从 S3 提供。如果您已写入文件，但更改尚未同步到 S3，则会通过文件系统进行读取，直到同步完成。

## 文件系统持续返回 NFS 服务器错误
<a name="s3-files-troubleshooting-encrypted-fs"></a>

加密的文件系统持续返回 NFS 服务器错误。如果由于以下原因之一，S3 Files 无法从 AWS KMS 检索 KMS 密钥，则可能会出现这些错误：
+ 禁用了密钥。
+ 删除了密钥。
+ 撤销了 S3 Files 使用密钥的权限。
+ AWS KMS 暂时不可用。

**要采取的操作**

首先，确认已启用 AWS KMS 密钥。您可以在 AWS KMS 控制台中查看密钥。有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[查看密钥](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html)。

如果未启用密钥，请将其启用。有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[启用和禁用密钥](https://docs.aws.amazon.com/kms/latest/developerguide/enabling-keys.html)。

如果密钥处于待删除状态，请取消删除并重新启用该密钥。有关更多信息，请参阅《AWS Key Management Service 开发人员指南》**中的[预定和取消密钥删除](https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html)。

如果密钥已启用，但您仍遇到问题，请联系 AWS Support。

## 文件系统写入后 S3 存储桶中缺少对象
<a name="s3-files-troubleshooting-missing-object"></a>

您通过文件系统写入了一个文件，并希望它作为对象显示在您的 S3 存储桶中，但该对象不存在。S3 Files 批处理更改约 60 秒，然后将其复制到 S3。如果对象仍未出现，则导出可能已失败。在此类情况下，您会看到 `FailedExports` CloudWatch 指标有所增加。

**要采取的操作**：

使用扩展的属性检查文件的导出状态：

```
getfattr -n "user.s3files.status;$(date -u +%s)" missing-file.txt --only-values
```

属性名称中的时间戳可确保您获得最新状态。输出示例：

```
S3Key: s3://bucket/prefix/missing-file.txt
ExportError: PathTooLong
```

如果没有导出失败，则不会显示 `ExportError`。如果 S3 对象从未与该文件关联，则 `S3Key` 为空。

下表列出了所有可能的 `ExportError` 值：


| 错误 | 原因 | 
| --- | --- | 
| S3AccessDenied | S3 Files 代入的 IAM 角色没有足够的权限，无法写入 S3 存储桶。有关更多信息，请参阅 [S3 Files 的先决条件](s3-files-prereq-policies.md)。 | 
| S3BucketNotFound | 源 S3 存储桶不再存在或已重命名。请验证它是否存在于预期的 AWS 区域和账户中。 | 
| InternalError | 出现内部系统错误。 | 
| S3UserMetadataTooLarge | 已超出 S3 用户元数据大小限制。有关这些限制的信息，请参阅[不支持的功能、限制和配额](s3-files-quotas.md)。 | 
| FileSizeExceedsS3Limit | 文件大小超过 S3 对象大小限制。有关这些限制的信息，请参阅[不支持的功能、限制和配额](s3-files-quotas.md)。 | 
| EncryptionKeyInaccessible | S3 Files 无法访问 S3 存储桶使用的加密密钥。授予 S3 Files 访问加密密钥的权限。有关更多信息，请参阅 [加密](s3-files-encryption.md)。 | 
| RoleAssumptionFailed | 无法代入该角色。请检查您的信任策略。有关更多信息，请参阅 [S3 Files 的先决条件](s3-files-prereq-policies.md)。 | 
| KeyTooLongToBreakCycle | 由于文件路径超过 S3 密钥长度限制，S3 Files 无法解析循环依赖关系（例如，由于将两个文件重命名为彼此的名称）。缩短目录路径以解决此错误。 | 
| PathTooLong | 您的文件路径超过 S3 密钥长度限制。有关这些限制的信息，请参阅[不支持的功能、限制和配额](s3-files-quotas.md)。 | 
| DependencyExportFailed | 父项或依赖项出现不可重试的导出失败。使用 getfattr 检查父项或任何依赖项的状态。 | 
| S3ObjectArchived | S3 对象已归档（S3 Glacier Flexible Retrieval 或 S3 Glacier Deep Archive），无法读取。首先使用 S3 API 还原对象。 | 

S3 Files 会自动重试失败的导出。对于不可重试的错误，仅显示 `ExportError`。

## S3 对象在文件系统中不可见
<a name="s3-files-troubleshooting-object-not-visible"></a>

对象存在于您的 S3 存储桶中，但未出现在文件系统中。对象键名称可能无法映射到有效的 POSIX 文件路径。S3 Files 不支持访问带有空路径组件 (`foo//bar`)、相对路径组件（`foo/./bar`、`foo/../bar`）的 S3 键名称，包含 null 字节的键名称，或任何路径组件超过 255 字节的键名称。键名称不兼容的对象不会导入到文件系统中。

## 文件出现在丢失找回目录中
<a name="s3-files-troubleshooting-lost-found"></a>

文件已出现在文件系统的根目录内的 `.s3files-lost+found-{{file-system-id}}` 目录中。在此类情况下，您会看到 `LostAndFoundFiles` CloudWatch 指标有所增加。当出现同步冲突时，会发生这种情况。如果在 S3 Files 将文件系统更改同步回 S3 之前，通过文件系统修改了同一个文件，并且相应的 S3 对象发生了更改，则会发生冲突。S3 Files 将 S3 存储桶视为事实来源，将冲突文件移至丢失找回目录，并将最新版本从 S3 存储桶导入到文件系统。

**识别丢失找回目录中的文件**

当 S3 Files 将文件移到丢失找回目录时，它会在文件名前面加上十六进制标识符，以区分同一文件的多个版本，这些版本可能会随着时间推移而变动。长度超过 100 个字符的文件名会被截断，以便为该标识符腾出空间。文件的原始目录路径未保留在丢失找回目录中。

**要采取的操作**

获取文件的原始路径和相应的 S3 对象键：

```
getfattr -n "user.s3files.status;$(date -u +%s)" .s3files-lost+found-{{fs-12345678}}/{{abcdef1234_report.csv}} --only-values
```

输出示例：

```
S3Key: s3://bucket/prefix/report.csv
FilePath: /data/report.csv
```


| 字段 | 说明 | 
| --- | --- | 
| S3Key | 导致冲突的对象的完整 S3 路径，如果该对象已在 S3 存储桶中删除，则为空。 | 
| FilePath | 冲突前文件的相对路径。 | 

然后，您可以保留 S3 存储桶中的最新版本并从丢失找回目录中删除该文件，也可以将文件从丢失找回目录复制回其原始路径以覆盖 S3 版本。

**注意**  
丢失找回目录中的文件会无限期地保留在那里，并计入您的文件系统存储成本。当不再需要文件时，从丢失找回目录中将其删除。

## 同步落后
<a name="s3-files-troubleshooting-sync-behind"></a>

`PendingExports` CloudWatch 指标正在增长，这表明您的工作负载生成更改的速度超过 S3 Files 将更改同步到 S3 的速度。

这意味着您的工作负载可能超过同步速率。S3 Files 对于每个文件系统每秒最多可导出 800 个文件。考虑降低文件修改速率或将工作分散到多个文件系统。随时间推移监控 `PendingExports` 指标。如果该指标稳定或下降，则 S3 Files 正在迎头赶上。如果该指标继续增长，请联系 AWS Support。

## 启用客户端调试日志
<a name="s3-files-troubleshooting-debug-logs"></a>

如果您要对挂载、连接或读取旁路问题进行故障排除，则可以在 S3 Files 客户端上启用调试级日志记录以捕获更多细节。

**挂载助手和 watchdog 日志**

编辑 `/etc/amazon/efs/s3files-utils.conf` 并将日志记录级别从 INFO 更改为 DEBUG：

```
[DEFAULT]
logging_level = DEBUG
```

卸载并重新挂载文件系统以使更改生效：

```
sudo umount /mnt/s3files
sudo mount -t s3files {{file-system-id}}:/ /mnt/s3files
```

日志会写入到 `/var/log/amazon/efs/`。挂载助手日志为 `mount.log`。

**代理（efs-proxy）日志**

此代理处理 NFS 流量和 S3 读取旁路。要为代理启用调试日志记录，请编辑 `/etc/amazon/efs/s3files-utils.conf`：

```
[proxy]
proxy_logging_level = DEBUG
```

卸载并重新挂载以使更改生效。代理日志会写入 `/var/log/amazon/efs/`。

**TLS 隧道（stunnel）日志**

默认情况下，禁用 TLS 隧道日志。要启用它们，请编辑 `/etc/amazon/efs/s3files-utils.conf` 并设置以下内容：

```
[mount]
stunnel_debug_enabled = true
```

要将文件系统的所有 stunnel 日志保存到单个文件中，还要取消注释 `stunnel_logs_file` 行：

```
stunnel_logs_file = /var/log/amazon/efs/{fs_id}.stunnel.log
```

**日志大小限制**

日志文件会自动轮换。您可以在 `s3files-utils.conf` 中配置轮换文件的最大大小和数量：

```
[DEFAULT]
logging_max_bytes = 1048576
logging_file_count = 10
```

默认值为每个日志文件 1 MB，包含 10 个轮换文件，每种日志类型的最大值为 10 MB。

**与 AWS Support 共享日志**

联系 AWS Support 时，请将客户端日志和配置收集到单个归档中：

```
sudo tar -czf /tmp/s3files-support-logs.tar.gz \
  /var/log/amazon/efs/ \
  /etc/amazon/efs/s3files-utils.conf
```

在您的支持案例中包含 `/tmp/s3files-support-logs.tar.gz`。