alibabacloud-nas-mount-diagnosis

NAS 挂载失败故障排查

诊断并解决阿里云 NAS 挂载失败问题，涵盖 Linux/Windows 系统上的 NFS/SMB 协议挂载场景。

前提条件

CLI 工具

• aliyun CLI：用于查询 NAS 文件系统、挂载点、权限组、ECS 安全组等。
• 安装参考：https://help.aliyun.com/document_detail/139508.html

aliyun CLI 初始化

每次诊断前，请更新插件，以避免自动安装时发生超时：

aliyun plugin update

CLI 使用说明：

• aliyun CLI 默认输出 JSON。不要添加 --output json 或任何输出格式标志，否则会导致错误。
• 如果命令因插件自动安装失败（超时或提示输入），请先运行 aliyun plugin update，然后重试完全相同的命令。
• 如果命令超时，请重试，不要跳过该命令，也不要用其他 API 响应中的数据替代。

可观测性

诊断会话期间的所有 aliyun CLI 调用都必须包含 --user-agent 标志，以便追踪：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-nas-mount-diagnosis/{session-id}

session-id 生成规则：

• 在每次诊断会话开始时生成一次
• 格式：32 位小写十六进制字符串（例如：a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6）
• 在会话期间的所有 CLI 调用中一致使用相同的 session-id
• 生成示例：python3 -c "import uuid; print(uuid.uuid4().hex)"

用法示例：

aliyun nas describe-file-systems --file-system-id 18bfd49621 --region cn-beijing --user-agent AlibabaCloud-Agent-Skills/alibabacloud-nas-mount-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

**禁止：**不要使用已弃用的机制，例如 aliyun configure ai-mode、export ALIBABA_CLOUD_USER_AGENT 或任何全局 UA 配置。始终在每条命令中传递 --user-agent。

阿里云凭证

必须通过 aliyun CLI 配置凭证配置文件。参考：https://help.aliyun.com/document_detail/123181.html

网络要求

• 运行诊断的机器必须能够访问阿里云 OpenAPI
• 远程 ECS 诊断需要 SSH 访问权限或安装云助手

所需 RAM 权限

此技能仅执行只读诊断操作，不执行任何写入操作。所需 RAM 权限和推荐策略的完整列表请参见 references/ram-policies.md。

工作流

步骤 1：收集基本信息

开始故障排查前，请向用户收集以下信息：

信息	询问方式
挂载点地址	“请提供 NAS 挂载点地址，例如 file-system-id.region.nas.aliyuncs.com”
文件系统协议	“挂载使用的是 NFS 还是 SMB 协议？”
操作系统	“ECS 实例运行的是 Linux 还是 Windows？具体版本是什么？”
错误消息	“请提供完整的错误消息”
挂载命令	“请提供执行过的挂载命令”
地域	“NAS 文件系统所在的地域（例如 cn-hangzhou）”

根据挂载点地址识别 NAS 类型并提取文件系统 ID

如果用户提供了挂载点地址，无需额外提问，即可直接从域名格式中提取 NAS 类型、地域和文件系统 ID：

NAS 类型	挂载点域名格式	示例	文件系统 ID 提取规则
通用型	<fsid>-<suffix>.<region>.nas.aliyuncs.com	18bfd49621-nyh99.cn-beijing.nas.aliyuncs.com	fsid = 第一个 - 之前的部分 → 18bfd49621
极速型	<hex-id>-<suffix>.<region>.extreme.nas.aliyuncs.com	014020e9-ohem.cn-beijing.extreme.nas.aliyuncs.com	fsid = extreme- + 第一个 - 之前的部分 → extreme-014020e9

**快速识别：**域名包含 .extreme. 表示极速型 NAS；否则为通用型 NAS。可直接从域名的第二段提取地域（例如 cn-beijing）。

步骤 2：预检查

在深入排查问题前，请确认以下基本条件：

1. 检查挂载点状态 — 调用 DescribeMountTargets API 检查挂载点的 VPC 和状态。必须单独调用此 API，且调用成功（2xx）；请勿使用 DescribeFileSystems 等其他 API 的数据代替。

   aliyun nas describe-mount-targets --file-system-id <file-system-id> --region <region>
   

   如果挂载点处于休眠状态，请指导用户通过控制台或 OpenAPI 重新启用。

   重要： 如果 DescribeMountTargets 返回 404 或错误，最可能的原因是 --region 值不正确。从挂载点域名中提取正确的地域（例如，xxx.cn-beijing.nas.aliyuncs.com → 地域为 cn-beijing），然后重试。

2. 检查账户余额 — 确认账户没有欠费。逾期未付款会导致 NAS 服务停止。

3. 查询文件系统信息 — 获取文件系统类型和协议信息

   aliyun nas describe-file-systems --file-system-id <file-system-id> --region <region>
   

快速诊断：错误消息模式匹配

进入完整的故障排查工作流前，先检查错误消息是否可以直接定位问题：

• 错误包含 access denied by server while mounting，且挂载路径包含子目录（例如 :/data、:/share/subdir）→ 最可能的原因：子目录不存在。对于通用型和极速型 NAS，手动挂载子目录不会自动创建该目录；如果子目录不存在，则会报告拒绝访问。解决方法：先挂载根目录 :/，创建子目录，然后重新挂载该子目录。
• 错误为 mount.nfs: No such device → sunrpc 模块配置不正确，请参阅“常见错误速查表”。
• 错误包含 Windows 系统错误代码 → 直接参阅“常见错误速查表”。

如果无法通过错误消息快速定位问题，请继续进行下方的场景化故障排查。

步骤 3：场景化故障排查

根据用户的操作系统和协议类型，进入相应的故障排查流程：

场景 A：Linux NFS 协议挂载失败

建议用户先运行官方自动检查脚本，快速诊断问题：

# Download auto-check script
wget --timeout=30 https://nas-client-tools.oss-cn-hangzhou.aliyuncs.com/linux_client/check_alinas_nfs_mount.py -P /tmp/

# Run check
python2.7 /tmp/check_alinas_nfs_mount.py <mount-target-address>:/ /mnt

如果自动脚本无法定位问题，请继续手动排查。请参阅 references/nfs-linux-errors.md。

手动排查清单：

1. 检查子目录挂载 — 如果挂载路径包含子目录（例如 :/data、:/share/subdir），且错误为 access denied，最可能的原因是子目录不存在。此规则适用于通用型和极速型 NAS。解决方法：先挂载根目录 sudo mount ... <mount-target>:/ /mnt，运行 mkdir /mnt/<subdir> 创建目录，然后卸载并重新挂载子目录
2. 检查 NFS 客户端安装情况 — 确认已安装 nfs-utils（RHEL/CentOS）或 nfs-common（Debian/Ubuntu）
3. 网络连通性 — 运行 ping <mount-target-address> 检查网络
4. 端口连通性 — 运行 telnet <mount-target-address> 2049 检查 NFS 端口
5. 权限组配置 — 使用 API 检查权限组是否允许 ECS 访问
6. VPC 一致性 — 确认 ECS 和挂载点位于同一 VPC，或通过云企业网（CEN）连接
7. 安全组规则 — 检查安全组出方向规则是否阻止 NFS 端口 2049（请注意普通安全组和企业安全组的区别；请参阅“检查安全组规则”部分）
8. 挂载命令格式 — 确认挂载命令参数正确

标准挂载命令见 references/nfs-linux-errors.md（错误 2 的解决方法包含通用型 NFS v3/v4 和极速型 NAS 的标准挂载命令）。

场景 B：Windows SMB 协议挂载失败

建议用户先运行官方自动检查脚本：

# Download inspection script
Invoke-WebRequest -TimeoutSec 30 https://nas-client-tools.oss-cn-hangzhou.aliyuncs.com/windows_client/alinas_smb_windows_inspection.ps1 -OutFile alinas_smb_windows_inspection.ps1

# Run inspection script
.\alinas_smb_windows_inspection.ps1 -MountAddress <mount-target-address> -Locale zh-CN

如果自动脚本无法定位问题，请根据错误代码进行手动排查。参见 references/smb-windows-errors.md。

手动排查清单：

1. 445 端口连通性 — telnet <mount-target-address> 445
2. 网络服务 — 确认 TCP/IP NetBIOS Helper 和 Workstation 服务正在运行
3. VPC 一致性 — 确认 ECS 和挂载目标位于同一 VPC
4. 权限组配置 — 检查权限组是否允许 ECS IP 访问
5. 挂载命令格式 — net use <drive-letter> \\<mount-target-address>\myshare

场景 C：Linux SMB 协议挂载失败

排查步骤：

1. 操作系统版本检查 — 确认 Linux 版本在 NAS SMB 支持范围内（参见 references/smb-linux-requirements.md）
2. CIFS 客户端检查 — 确认已安装 cifs-utils
3. 网络连通性 — ping <mount-target-address> 和 telnet <mount-target-address> 445
4. VPC 和账号一致性
5. 权限组配置
6. root/sudo 权限
7. 挂载命令是否正确：

   sudo mount -t cifs //<mount-target-address>/myshare /mnt -o vers=2.0,guest,uid=0,gid=0,dir_mode=0755,file_mode=0755,mfsymlinks,cache=strict,rsize=1048576,wsize=1048576
   

8. SELinux 设置
9. 挂载连接数限制 — 每个文件系统最多 1000 个

场景 D：Windows NFS 协议挂载失败

排查步骤：

1. 账号一致性 — ECS 和挂载目标属于同一账号
2. VPC 一致性
3. 端口检查 — 2049 和 111 端口

   Test-NetConnection <mount-target-address> -Port 2049
   Test-NetConnection <mount-target-address> -Port 111
   

4. 权限组配置

场景 E：容器（K8s/Docker）NAS 挂载失败

出现错误 access denied by server while mounting <mount-address> 时：

1. 确认挂载目录存在
2. 确认容器启动用户具有 root 权限（容器必须以特权模式运行）
3. 确认挂载目标权限组包含容器 IP

步骤 4：借助 API 诊断

通过阿里云 API 执行自动检查。下方每个 API 都必须单独调用并返回 2xx；不得使用其他 API 响应中包含的数据跳过任何 API。

**区域确定：**下方所有 API 调用都需要使用正确的 --region。根据挂载目标域名确定区域（例如，xxx.cn-beijing.nas.aliyuncs.com → cn-beijing）。如果任何 API 返回 404，请在重试前确认区域是否正确。

# 1. Query file system information
aliyun nas describe-file-systems --file-system-id <fs-id> --region <region>

# 2. Query mount targets — MUST call separately to get VPC, status, and access group
aliyun nas describe-mount-targets --file-system-id <fs-id> --region <region>

# 3. Query permission group rules — check if ECS IP is in the allow list
aliyun nas describe-access-rules --access-group-name <access-group-name> --region <region>

# 4. Query ECS instance information — get VPC ID and private IP
aliyun ecs describe-instances --instance-ids '["<instance-id>"]' --biz-region-id <region>

# 5. Query security group rules — check if port is allowed
aliyun ecs describe-security-group-attribute --security-group-id <sg-id> --biz-region-id <region>

诊断逻辑：

• 比较 ECS 的 VpcId 与挂载目标的 VpcId 是否一致。如果 VPC 不同，请通过云助手在 ECS 上探测网络连通性（DNS 解析、ping、端口探测），以确定是否已通过 CEN 建立连通性
• 检查权限组规则是否包含 ECS 私有 IP 或其子网
• 检查安全组出方向规则是否允许访问目标端口（NFS：2049，SMB：445），并考虑安全组类型和默认规则（参见“安全组规则检查”部分）

安全组规则检查

安全组分为普通安全组和企业安全组，默认访问控制规则不同，诊断时必须加以区分：

普通安全组与企业安全组的默认规则

安全组类型	入方向默认规则	出方向默认规则
普通	仅允许同一安全组内实例的内网流量	允许所有流量
企业	拒绝所有流量	拒绝所有流量

主要区别：普通安全组默认允许所有出方向流量。即使没有明确配置匹配 NFS 2049 或 SMB 445 端口的出方向规则，流量仍可通过。只有企业安全组需要配置明确的出方向规则。

如何确定安全组类型

通过 describe-security-groups API 查询 SecurityGroupType 字段：

aliyun ecs describe-security-groups --security-group-id <sg-id> --biz-region-id <region>

• SecurityGroupType: normal → 普通安全组
• SecurityGroupType: enterprise → 企业安全组

describe-security-group-attribute 返回的 InnerAccessPolicy 字段也可作为参考：

• InnerAccessPolicy: Accept → 普通安全组（组内互通）
• 企业安全组没有此字段，或此字段的值不同

安全组诊断流程

1. 确定安全组类型（普通或企业）
2. 如果是普通安全组：
   • 出站流量默认全部放行，通常不会阻止 NAS 挂载
   • 只需检查是否有明确阻止 NAS 相关端口的 Drop 规则
   • 只有匹配 NAS 端口的自定义 Drop 规则会导致挂载失败
3. 如果是企业安全组：
   • 出站流量默认全部拒绝，需要配置明确的 Allow 规则
   • 确认存在允许通过 TCP 出站连接到 NAS 挂载目标 IP 的规则（NFS：2049，SMB：445）
   • 如果缺少相应规则，则需要添加

安全组规则匹配策略

当 ECS 关联多个安全组时，规则匹配顺序如下：

1. 汇总所有安全组的规则
2. 按优先级排序（数字越小，优先级越高）
3. 优先级相同时，Drop 规则优先于 Accept 规则
4. 如果没有匹配的自定义规则，则使用安全组默认规则

安全组始终允许的特殊流量

以下流量始终允许通过安全组，且无法通过规则阻止：

• 阿里云网络连通性检测（按需发起的 Ping 探测）
• ICMP PMTUD 错误消息（路径 MTU 发现）
• SLB 负载均衡器转发流量（由 SLB 的安全组/ACL 控制）
• MetaServer 访问（100.100.100.200，实例元数据服务）

步骤 5：输出诊断报告

使用以下模板输出结果：

# NAS Mount Failure Diagnosis Report

## Basic Information
- File System ID: xxx
- File System Type: General Purpose / Extreme
- Protocol Type: NFS / SMB
- Mount Target Address: xxx
- Mount Target Status: Active / Hibernated
- ECS Instance ID: xxx
- Operating System: xxx

## Check Results
| Check Item | Status | Details |
|-----------|--------|---------|
| Mount target status | ✅/❌ | ... |
| VPC consistency | ✅/❌ | ... |
| Permission group | ✅/❌ | ... |
| Security group type | Normal/Enterprise | ... |
| Security group port | ✅/❌ | Normal SG allows all egress by default; Enterprise SG requires explicit rules |
| Network connectivity | ✅/❌ | ... |
| Client installation | ✅/❌ | ... |
| Mount command format | ✅/❌ | ... |

## Root Cause
[Specific description of the identified issue]

## Solution
[List resolution steps in priority order]

常见错误速查

遇到以下特定错误消息时，可直接判断问题：

错误消息	根本原因	解决方案
mount.nfs: No such device	sunrpc 模块配置错误	在 /etc/modprobe.d/sunrpc.conf 中修正 tcp_slot_table_entries，运行 modprobe sunrpc
mount: can't find ... in /etc/fstab	挂载命令格式不正确	使用正确的 sudo mount -t nfs -o ... 命令
mount.nfs: Operation not permitted（NFSv4）	ECS 主机名冲突	运行 echo 'install nfs /sbin/modprobe --ignore-install nfs nfs4_unique_id=\cat /sys/class/dmi/id/product_uuid`' >> /etc/modprobe.d/nfs.conf`，重启 ECS
access denied by server while mounting .../<dir>	子目录不存在	先挂载根目录，再创建子目录，然后重新挂载
file handle error（Windows NFS）	缺少锁定注册表项	在注册表 ClientForNFS\...\Mount 中创建值为 1 的 DWORD Locking
Windows 系统错误 53	网络路径无法访问	检查网络连接、TCP/IP NetBIOS Helper 服务和 LanmanWorkstation 注册表项
Windows 系统错误 58	SMB 协议版本不兼容	确认 Windows 版本为 2008 R2 或更高版本
Windows 系统错误 64	权限组未获授权	检查权限组规则、账户余额和文件系统类型
Windows 系统错误 67	网络服务未启动	启用 Workstation 和 TCP/IP NetBIOS Helper 服务
Windows 系统错误 85	驱动器号已被占用	使用其他驱动器号重新挂载
Windows 系统错误 1231	未安装 Microsoft 网络客户端	安装并启用 Microsoft 网络客户端以及文件和打印机共享
Windows 系统错误 1272	安全策略阻止来宾访问	将注册表项 AllowInsecureGuestAuth 设置为 1
Windows 系统错误 3227320323	数字签名策略冲突	禁用“Microsoft 网络客户端：对通信进行数字签名（始终）”策略
Windows 系统错误 1312	PowerShell 挂载用户名错误	输入正确的工作组名称和用户名
启动时自动挂载失败（CentOS 7）	未启用 remote-fs.target	systemctl enable remote-fs.target
Windows NFS 网络错误 1222	未安装 NFS 客户端	安装 NFS 客户端

重要说明

• 此技能仅执行只读诊断操作，不会修改任何云资源配置
• 如果诊断发现需要更改的配置（安全组、权限组等），请告知用户解决方案，并由用户执行操作
• 对于无法通过 API 远程诊断的问题（例如 ECS 内部客户端安装状态），请指导用户在 ECS 上执行检查命令
• 子目录挂载访问被拒绝：对于通用型和极速型 NAS，手动执行 mount 命令挂载子目录时不会自动创建该目录。如果子目录不存在，就会报错 access denied by server while mounting。统一解决方法是：先挂载根目录（通用型使用 :/，极速型使用 :/ 或 :/share），手动运行 mkdir 创建子目录，然后再挂载该子目录
• 极速型 NAS 路径映射：:/ 和 :/share 等效，均指向根目录；:/subdir 和 :/share/subdir 等效，均指向同一子目录
• 诊断前务必确定安全组类型：普通安全组默认允许所有出站流量，不要仅因没有显式出站规则就误判端口被阻止；企业安全组默认拒绝出站流量，需要显式添加 Allow 规则