troubleshooting-efs

EFS 故障排除

概述

诊断和解决 Amazon EFS 问题的领域专业知识。涵盖挂载失败、NFS 连接、IAM 和 POSIX 权限、吞吐量和性能，以及加密问题。

如需权威指导，请参阅 EFS 故障排除。

常见任务

0. 验证依赖项

• 你 MUST 验证 aws CLI 是否可用
• 你 MUST 检查实例上是否安装了 amazon-efs-utils 或 nfs-utils
• 你 MUST ONLY 检查工具是否存在及其版本 — 验证期间 MUST NOT 执行破坏性或变更性命令
• 如果缺少任何必需工具，你 MUST 告知用户
• 如果工具不可用，你 MUST 尊重用户中止操作的决定
• 执行前，你 SHOULD 说明每个步骤的作用和原因
• 执行写入命令前，你 SHOULD 显示命令并等待用户确认

1. 对问题进行分类

症状	类别
“wrong fs type” 或挂载命令失败	A：缺少 NFS 客户端
连接超时（挂起 2 分钟以上）	B：网络/安全组
“access denied by server”	C：IAM/权限
吞吐量缓慢或延迟较高	D：性能
加密文件系统上出现 NFS 服务器错误	E：加密/KMS
DNS 名称解析失败	F：VPC DNS

2. 类别 A — 缺少 NFS 客户端

# Amazon Linux / RHEL / CentOS
sudo yum -y install amazon-efs-utils  # preferred (includes mount helper + TLS)
# OR
sudo yum -y install nfs-utils

# Ubuntu / Debian
sudo apt-get install nfs-common

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

连接超时是 EFS 挂载失败的头号原因——几乎总是安全组配置所致。

1. 验证挂载目标是否位于实例所在的可用区（AZ）：

aws efs describe-mount-targets --file-system-id fs-ID --region REGION

1. 验证安全组 — 检查两个方向：

   • 挂载目标 SG：aws ec2 describe-security-groups --group-ids sg-MT — MUST 允许来自计算 SG 的入站 TCP 2049
   • 计算 SG：MUST 允许到挂载目标 SG 的出站 TCP 2049
   • 快速修复：aws ec2 authorize-security-group-ingress --group-id sg-MT --protocol tcp --port 2049 --source-group sg-COMPUTE

2. 测试连接：

nc -zv fs-ID.efs.REGION.amazonaws.com 2049

注意： 这些安全组故障排除步骤同样适用于 S3 Files。唯一的区别是，S3 Files 使用 aws s3files list-mount-targets，而不是 aws efs describe-mount-targets。

4. 类别 C — IAM/权限

使用 -o iam 时出现 “access denied by server”：

• 检查基于身份的 IAM 策略是否具有 elasticfilesystem:ClientMount
• 检查文件系统资源策略：

aws efs describe-file-system-policy --file-system-id fs-ID --region REGION

注意： 只有在文件系统策略要求进行 IAM 授权时，才会强制执行 IAM 授权。如果没有文件系统策略，VPC 中任何可访问端口 2049 的客户端都可以挂载 — 即使使用了 -o iam 也是如此。要强制使用 IAM，你 MUST 创建一个拒绝匿名访问的文件系统策略。

POSIX 权限被拒绝（非 IAM）：

• 检查文件/目录所有权：ls -la /mnt/efs/
• 使用访问点强制设置 UID/GID，确保权限一致

5. 类别 D — 性能

检查吞吐量模式：

aws efs describe-file-systems --file-system-id fs-ID --region REGION --query 'FileSystems[0].ThroughputMode'

突发积分耗尽（仅限 Bursting 模式）：

aws cloudwatch get-metric-statistics --namespace AWS/EFS --metric-name BurstCreditBalance --dimensions Name=FileSystemId,Value=fs-ID --period 3600 --statistics Average --start-time $(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%S) --end-time $(date -u +%Y-%m-%dT%H:%M:%S)

如果积分接近零，请切换到 Elastic 吞吐量：

aws efs update-file-system --file-system-id fs-ID --throughput-mode elastic --region REGION

General Purpose 与 Max I/O：

• 检查 PercentIOLimit 指标 — 如果持续高于 80%，请考虑使用 Max I/O
• 注意：性能模式不可变 — 必须创建新的 FS 并迁移

6. 类别 E — 加密/KMS

加密文件系统上出现 NFS 服务器错误 = KMS 密钥问题。

• 在 KMS 控制台中验证密钥是否已启用
• 验证 EFS 服务关联角色是否具有 KMS 权限
• 如果密钥已删除：如果仍在宽限期内，请取消删除

7. 类别 F — 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

两项 MUST 均为 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

故障排除

挂载挂起后超时

最常见的原因：安全组。验证计算实例与挂载目标之间是否开放了 TCP 2049。

重启后自动挂载失败

/etc/fstab 条目 MUST 包含 _netdev 选项，以便在挂载前等待网络就绪。

重新连接后出现 “nfs not responding”

旧内核存在 TCP 端口重用错误。请更新内核或添加 noresvport 挂载选项。

启用调试日志

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

收集日志以提交给 AWS Support

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

安全注意事项

• 只有在文件系统策略存在时才会强制执行 IAM 授权；如果没有策略，任何可通过端口 2049 访问的 VPC 客户端都可以挂载
• 排查访问被拒绝的问题时，请同时检查基于身份和基于资源的策略
• 使用 -o tls 加密传输中的数据；未加密的 NFS 流量可被网络上的其他方查看
• 限制对 /var/log/amazon/efs/ 的访问；日志可能包含文件系统 ID 和挂载目标 IP

其他资源

• EFS 故障排除
• EFS 性能
• EFS 挂载助手