View a markdown version of this page

S3 Files 故障排除 - Amazon Simple Storage Service
挂载命令失败对文件操作的权限被拒绝智能读取路由不起作用文件系统持续返回 NFS 服务器错误文件系统写入后 S3 存储桶中缺少对象S3 对象在文件系统中不可见文件出现在丢失找回目录中同步落后启用客户端调试日志

S3 Files 故障排除

本页有助于帮助您诊断和解决 S3 Files 的常见问题。

挂载命令失败

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

常见原因和操作：

  • “mount.s3files: command not found”：S3 Files 客户端（amazon-efs-utils）未安装或低于版本 3.0.0。安装或升级客户端。有关更多信息，请参阅 S3 Files 的先决条件。

  • “Failed to resolve file system DNS name”：运行您的 EC2 实例的可用区中没有挂载目标。在该可用区中创建一个挂载目标，或者在具有挂载目标的可用区中启动您的实例。有关更多信息，请参阅 创建挂载目标。

  • Connection timed out：安全组配置不支持 NFS 流量。验证挂载目标的安全组是否支持通过端口 2049 从实例的安全组入站的 TCP，以及实例的安全组是否支持通过端口 2049 的出站 TCP 进入挂载目标的安全组。有关更多信息，请参阅 S3 Files 的先决条件。

  • "Access denied" during mount：附加到计算资源的 IAM 角色没有所需的 S3 Files 权限。验证该角色是否已附加 AmazonS3FilesClientFullAccess 或 AmazonS3FilesClientReadOnlyAccess 托管式策略，或者至少具有 s3files:ClientMount 权限。有关更多信息，请参阅 S3 Files 的先决条件。

  • botocore not installed：挂载助手需要 botocore 才能与 AWS 服务进行交互。按照 GitHub 上 amazon-efs-utils 自述文件中的说明安装 botocore。

对文件操作的权限被拒绝

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

常见原因和操作：

  • 缺少写入权限：如果您能够读取但不能写入，请验证附加到计算资源的 IAM 角色是否包含 s3files:ClientWrite 权限，或者附加 AmazonS3FilesClientReadWriteAccess 或 AmazonS3FilesClientFullAccess 托管式策略。有关更多信息，请参阅 Amazon S3 Files 的 AWS 托管式策略。

  • 缺少根访问权限：如果您在访问根用户（UID 0）拥有的文件时收到权限错误，则您的 IAM 角色可能没有 s3files:ClientRootAccess 权限。如果没有此权限，则所有操作均以 NFS 匿名用户（通常为 nfsnobody）的身份执行，该用户可能无权访问文件。附加 AmazonS3FilesClientFullAccess 托管式策略或将 s3files:ClientRootAccess 添加到您的策略中。

  • 文件系统策略拒绝访问：如果您附加了文件系统策略，请确认该策略不会拒绝您的客户端所需的操作。基于身份的策略或文件系统策略中的“允许”足以进行访问。有关更多信息，请参阅 S3 Files 如何与 IAM 结合使用。

  • POSIX 权限不匹配：S3 Files 对文件和目录强制执行标准 POSIX 权限（所有者、组等）。如果您的应用程序以与文件的所有者或组不匹配的用户身份运行，即使 IAM 权限正确，访问也可能会被拒绝。使用接入点为所有请求强制使用特定的 UID/GID。有关更多信息，请参阅 为 S3 文件系统创建接入点。

智能读取路由不起作用

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

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

常见原因和操作：

  • 计算角色上缺少 S3 内联策略：附加到计算资源的 IAM 角色必须包含内联策略，此策略授予对关联 S3 存储桶的 s3:GetObject 和 s3:GetObjectVersion。如果没有此策略，挂载助手将无法直接从 S3 读取，并且所有读取都要通过文件系统。有关更多信息，请参阅 S3 Files 的先决条件。

  • 无法访问 S3 存储桶：请检查 S3BucketReachable 指标。如果它显示 0，请验证计算资源是否具有对 S3 的网络访问权限（例如，通过 VPC 端点或 NAT 网关）。

  • 文件已修改：只有当文件未通过文件系统进行修改时，读取才会直接从 S3 提供。如果您已写入文件，但更改尚未同步到 S3，则会通过文件系统进行读取，直到同步完成。

文件系统持续返回 NFS 服务器错误

加密的文件系统持续返回 NFS 服务器错误。如果由于以下原因之一，S3 Files 无法从 AWS KMS 检索 KMS 密钥，则可能会出现这些错误：

  • 禁用了密钥。

  • 删除了密钥。

  • 撤销了 S3 Files 使用密钥的权限。

  • AWS KMS 暂时不可用。

要采取的操作

首先，确认已启用 AWS KMS 密钥。您可以在 AWS KMS 控制台中查看密钥。有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的查看密钥。

如果未启用密钥，请将其启用。有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的启用和禁用密钥。

如果密钥处于待删除状态，请取消删除并重新启用该密钥。有关更多信息，请参阅《AWS Key Management Service 开发人员指南》中的预定和取消密钥删除。

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

文件系统写入后 S3 存储桶中缺少对象

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

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

S3 对象在文件系统中不可见

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

文件出现在丢失找回目录中

文件已出现在文件系统的根目录内的 .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 版本。

注意

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

同步落后

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

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

启用客户端调试日志

如果您要对挂载、连接或读取旁路问题进行故障排除，则可以在 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。