troubleshooting-s3-files

S3 Files 故障排除

概述

诊断并解决 Amazon S3 Files 问题：挂载失败、IAM 权限、同步、冲突解决和性能问题。

如需权威指南，请参阅 S3 Files 故障排除。

常见任务

0. 验证依赖项

• 你必须确认 aws CLI 可用，并支持 s3files 子命令
• 你必须确认 AWS 凭证有效
• 你只能检查工具是否存在及其版本——验证期间不得执行破坏性或会更改状态的命令
• 如果缺少任何必需工具，你必须告知用户
• 如果工具不可用，你必须尊重用户中止操作的决定
• 对于写入命令，你应在执行前说明步骤并等待用户确认

1. 对问题分类

症状	类别
mount.s3files: command not found	A：客户端安装
挂载期间连接超时	B：网络／安全组
挂载无限期卡住（无超时）	B：网络／安全组
挂载期间访问被拒绝	C：IAM 权限
文件系统卡在“creating”状态	C：IAM 权限
文件操作时权限被拒绝	C：IAM 权限
写入后文件未出现在 S3 中	D：同步
文件出现在 .s3files-lost+found 目录中	E：冲突解决
读取缓慢或延迟较高	F：性能
NFS 服务器错误	G：加密／KMS
DNS 名称解析失败	H：VPC DNS

2. 类别 A — 客户端安装

mount.s3files: command not found 表示缺少 amazon-efs-utils，或其版本低于 v3.0.0。

sudo yum -y install amazon-efs-utils  # Amazon Linux

3. 类别 B — 网络／安全组

连接超时是挂载失败的首要原因——几乎总是由安全组导致。

验证实例所在可用区中是否存在挂载目标：

aws s3files list-mount-targets --file-system-id fs-ID --region REGION

跨可用区挂载可行，但会增加延迟。

验证安全组——这是最常见的修复方法：

• 挂载目标安全组必须允许来自计算安全组的入站 TCP 2049 流量
• 计算安全组必须允许发往挂载目标安全组的出站 TCP 2049 流量
• 修复方法：aws ec2 authorize-security-group-ingress --group-id sg-MT --protocol tcp --port 2049 --source-group sg-COMPUTE

测试连接：

nc -zv az-ID.fs-ID.s3files.REGION.on.aws 2049

注意： 这些安全组故障排除步骤也适用于 EFS——改用 aws efs describe-mount-targets。

在隔离的 VPC 中挂载卡住： 如果 VPC 无法访问互联网，S3 Files 需要 CloudWatch Logs VPC 端点（com.amazonaws.REGION.logs）才能完成挂载。

4. 类别 C — IAM 权限

文件系统卡在“creating”状态： S3 Files 在创建时不会验证 IAM 角色权限。信任策略错误或缺少权限 → 状态会卡在 creating，且 statusMessage 中显示访问被拒绝。

检查状态：

aws s3files get-file-system --file-system-id fs-ID --region REGION

检查 statusMessage。如果显示访问被拒绝，请修复 IAM 角色，然后删除并重新创建文件系统。

挂载访问被拒绝： 计算角色需要 s3files:ClientMount。仅用于开发／测试时，可以使用 AmazonS3FilesClientFullAccess——生产环境中应避免使用。

写入权限被拒绝： 计算角色需要 s3files:ClientWrite

Root 访问被拒绝： 计算角色需要 s3files:ClientRootAccess。⚠️ 这会绕过 POSIX 权限——建议使用配置了受限 POSIX 用户的接入点。

检查文件系统策略：

aws s3files get-file-system-policy --file-system-id fs-ID --region REGION

5. 类别 D — 同步

文件未出现在 S3 中： 写入通常会在约 60 秒内同步。检查状态：

getfattr -n "user.s3files.status;$(date -u +%s)" filename --only-values

常见的 ExportError 值：

错误	修复方法
S3AccessDenied	文件系统 IAM 角色缺少 S3 写入权限
S3BucketNotFound	存储桶已删除或重命名
RoleAssumptionFailed	信任策略配置错误
EncryptionKeyInaccessible	KMS 密钥已禁用或权限已撤销
PathTooLong	文件路径超过 S3 键的 1,024 字节限制

监控：CloudWatch 指标 PendingExports。数值增长 = 超过每秒 800 个文件的速率。

6. 类别 E — 冲突解决

.s3files-lost+found-{fs-id} 中的文件 = 同步冲突（同时通过 FS 和 S3 修改）。以 S3 为准；FS 版本会移至 lost+found。

7. 类别 F — 性能

首次访问延迟： 正常 — 首次访问目录时会导入元数据。

智能读取路由无法正常工作： 计算角色需要对存储桶拥有 s3:GetObject 权限。

写入速度慢： 如果 PendingExports 持续增长，请分散到多个文件系统。

8. 类别 G — 加密/KMS

加密文件系统出现 NFS 服务器错误 = KMS 问题。请确认密钥已启用，且角色拥有 KMS 权限。

9. 类别 H — VPC DNS

DNS 解析失败 = 已禁用 VPC DNS 设置。

aws ec2 describe-vpc-attribute --vpc-id vpc-ID --attribute enableDnsHostnames
aws ec2 describe-vpc-attribute --vpc-id vpc-ID --attribute enableDnsSupport

两者都必须为 true。如果不是：

aws ec2 modify-vpc-attribute --vpc-id vpc-ID --enable-dns-hostnames Value=true
aws ec2 modify-vpc-attribute --vpc-id vpc-ID --enable-dns-support Value=true

故障排除

AWS CLI 端点 URL 无法解析

CLI 版本过旧，不支持 S3 Files。运行 aws --version — 如果是 v1.x，请升级到 AWS CLI v2：安装 AWS CLI。

ECS 任务因 DNS 解析错误而失败

使用了 efsVolumeConfiguration，而不是 s3filesVolumeConfiguration。修复方法：在 S3 Files 专用卷配置中使用 fileSystemArn。

混淆 S3 Files 与其他产品

S3 Files 不是 Mountpoint for S3、S3 File Gateway 或 File Cache。它使用 aws s3files CLI、s3files: IAM 操作和 mount -t s3files。

启用调试日志

在 /etc/amazon/efs/s3files-utils.conf 中设置 logging_level = DEBUG。日志位于 /var/log/amazon/efs/mount.log。

收集日志以提交给 AWS Support

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

安全注意事项

• 诊断 IAM 问题时，请验证是否遵循最小权限原则 — 避免将 FullAccess 作为权宜之计
• 如果没有文件系统策略，任何 VPC 客户端都可以挂载
• 限制对 /var/log/amazon/efs/ 的访问 — 日志包含 S3 密钥名称

更多资源

• S3 Files 故障排除
• S3 Files 最佳实践
• S3 Files 配额