文档中心

对象存储

请输入

FSX

FSX 故障排查与处理

本文介绍在使用 FSX 客户端过程中遇到故障时如何进行排查解决。

权限问题

挂载存储桶时报错 “error: Auth Failed”

问题原因：

挂载存储桶使用的 Access Key ID 和 Secret Access Key 填写有误或权限不足。

解决方案：

检查挂载时填写的 Access Key ID 和 Secret Access Key 是否正确。

确保挂载时使用的 Access Key ID 和 Secret Access Key 所属账号具有挂载存储桶的最小权限，详细介绍，请参见挂载存储桶所需要的权限。

存储桶挂载成功后，读取文件时报错 “Permission denied”

问题原因：

读取的是未恢复的归档存储、冷归档和深度冷归档类型的文件。

挂载时使用的 Access Key ID 和 Secret Access Key 权限不足。

解决方案：

检查读取的文件类型，如果是归档存储、冷归档和深度冷归档类型的文件，需要恢复后才可以读取。

确保挂载时使用的 Access Key ID 和 Secret Access Key 所属账号具有读取文件（GetObject ）的权限，详细介绍，请参见挂载存储桶所需要的权限。

挂载问题

挂载时报错 “Mount target directory is not exist”

问题原因：

挂载存储桶前，未创建指定的挂载目录。

解决方案：

创建指定的挂载目录后，再执行挂载操作。具体操作，请参见 FSX 配置与挂载。

使用 FSX 挂载存储桶后，通过 reboot -t 命令重启 Linux 系统，重启无法正常完成

问题原因：

重启系统前，没有卸载挂载点。由于没有卸载挂载点， reboot 命令会先关闭所有用户进程（包括 FSX 进程），再去执行 umount 命令。FSX 工具支持崩溃恢复， umount 命令不会立即返回失败，会阻塞（等待 FSX 进程恢复），从而阻塞 reboot 命令。

解决方案：

建议您强制重启系统，或者等待一段时间，系统会自动恢复重启。

挂载失败，或访问文件失败

问题原因：

目标存储桶不存在或名称错误。

挂载或访问时使用了 S3 域名。

说明

FSX 仅支持 TOS 域名。

客户端与 TOS 之间网络不通或网络异常。

配置的鉴权信息有误，或使用 IAM 用户挂载存储桶时权限不足。

解决方案：

登录对象存储控制台或通过接口检查存储桶是否真实存在，名称是否正确。

确认使用 TOS 域名而不是 S3 域名，通过以下命令进行连通性测试：

域名说明参考请参见：地域和访问域名（Endpoint）。

检查本机网络、DNS 解析及防火墙规则，确保能正常访问 TOS 服务域名。

检查挂载使用的 AccessKey/SecretKey、Security Token 等鉴权信息是否正确，确认对应 IAM 用户已配置挂载和访问存储桶所需的权限，权限说明请参见 FSX 配置与挂载。

执行挂载命令时 mount 失败

问题原因：

挂载参数中存在不合法或不被支持的参数。

使用 credential_filepath 参数时，凭证文件 JSON 格式错误。

系统磁盘空间不足以满足 FSX 工具运行需要。

解决方案：

检查挂载命令中的参数是否填写正确，去除不合法参数；如版本较旧，建议升级 FSX 客户端到最新版本后重试挂载。

若使用 credential_filepath，检查凭证文件是否为合法 JSON 格式，凭证文件可以是以下任意一种格式：

检查磁盘空间是否充足，建议至少预留 32GiB 内存，50GiB 磁盘空间，并按以下规划准备目录：

目录类型	说明	配置方法
软件安装目录	默认路径：/opt/fsx；建议磁盘空间：≥ 1GiB。	系统内置路径，不支持通过挂载参数修改；详细说明参见下载与安装 FSX。
内部状态记录目录	默认路径：/opt/tmp/fsx；建议磁盘空间：≥ 2GiB。	通过 persist_dir 挂载参数配置，详细说明参见 FSX 挂载参数说明。
读缓存目录	默认：不启用读缓存（目录为空）；启用读缓存时，建议至少预留约 20GiB 磁盘空间（建议独立分区）。	通过 read_cache_dir 指定目录，通过 max_read_cache_size 指定空间大小，详细说明参见 FSX 挂载参数说明。
写缓存目录	默认路径：/tmp；建议磁盘空间：≥ 10GiB（建议与读缓存共用独立分区）。	通过 temp_dir 指定目录，通过 max_temp_capacity、part_size 控制空间和单文件大小，详细说明参见 FSX 挂载参数说明。
运行日志目录	默认路径：/var/log/fsx；建议磁盘空间：≥ 2GiB。	系统内置路径，不支持通过挂载参数修改；相关说明参见 FSX 配置与挂载。

安装问题

安装 FSX 客户端失败报错“Package ca-certificates is not installed”

问题原因：

挂载环境（系统架构、操作系统及发行版）不在 FSX 客户端支持列表内。

依赖组件未安装或版本不符合要求。

解决方案：

检查挂载环境是否符合支持范围。FSX 客户端当前仅支持 x86_64、ARM64（当前仅支持 ecs.c3bl 系列机型）的体系架构，暂不支持在 Windows 和 macOS 环境使用。支持的运行环境如下表所示：

系统架构	操作系统	发行版
x86_64	Debian	11
		CentOS	7、8
		CentOS Stream	8
		Ubuntu	18.04、20.04、22.04、24.04
		veLinux	1.0、2.0
		Rocky	9.1、9.2、9.3、9.4、9.5
ARM64	Ubuntu	22.04
ARM64		veLinux	1.0、2.0

安装依赖，完成后重试安装。

apt update
apt install ca-certificates

升级 FSX 失败

问题原因：

从高版本回滚到低版本导致升级过程异常。

其他偶发性升级失败。

解决方案：

如为高版本降级到低版本，建议先卸载当前版本，再安装目标版本。

再次尝试升级操作。

若多次重试仍失败，请收集相关日志并提交工单联系我们。

卸载问题

卸载时报错 “target is busy”

问题原因：

当存在进程访问挂载目录时，无法执行卸载操作。

解决方案：

以下以挂载目录 /mnt/point为例，介绍卸载时报错的解决方案。

使用 lsof | grep "/mnt/point" 命令找到访问挂载目录的进程。

重新执行 umount /mnt/point 命令，卸载存储桶。

卸载 FSX 失败

问题原因：

仍有挂载点未卸载，对应挂载点被系统认为正在使用。

解决方案：

使用 df -h 检查是否仍存在 FSX 的挂载点。

对所有挂载点执行 umount 卸载，确认无挂载点残留后，再重试卸载命令。

执行 umount 命令卸载挂载点失败

问题原因：

目标挂载点仍有进程在访问，导致卸载时被占用。

解决方案：

以挂载目录/mnt/point 为例，使用以下命令查找正在访问该目录的进程：

强制关闭或正常结束这些访问挂载目录的进程。

再次执行 umount /mnt/point 进行卸载。

读写问题

在 FNS 存储桶追加写场景中，为什么会出现对即将追加的数据进行拷贝的情况？

问题原因：

FSX 工具追加写操作在不同类型的存储桶，实现原理不同，具体实现原理如下：

追加写 FNS 存储桶中的对象时，云端的历史数据会使用 UploadPartCopy 接口对 TOS 中的数据进行复制，追加的新数据则使用 UploadPart 或 PutObject 接口进行上传。该场景下，一次 open 操作仅支持一次 flush 操作。

追加写 HNS 存储桶中的对象时，TOS 会使用 AppendObject 接口进行数据的追加写操作。该场景下，支持对追加写的对象执行多次 flush 操作。

解决方案：

如果您不希望出现请求次数放大的情况，推荐使用 HNS 存储桶。

挂载存储桶后，访问目录失败

问题原因：

通过 FSX 挂载存储桶后，系统会将/结尾的对象识别为目录。如果您创建了同名的目录和文件（例如 test/ 和 test），由于名字相同，系统无法区分，导致访问目录失败。

解决方案：

如果系统中存在同名的目录和文件，建议您重命名文件和目录，确保文件和目录的名称不重复。后续请勿创建同名的目录和文件，以防命名冲突。

对挂载目录发起读请求失败

问题原因：

访问路径上同时存在同名文件和目录，导致路径解析冲突。

当访问 A/B/C/1.txt 失败时，请检查路径中 A、A/B、A/B/C 是否被创建为文件；如是，请将这些文件重命名为其他名称，以避免与目录同名导致的访问冲突。

目标对象为归档存储、冷归档或深度冷归档存储类型，数据尚未取回，无法直接读取。

解决方案：

检查访问路径每一层是否存在同名文件与目录冲突，如有，将冲突的文件重命名，避免与目录同名。

对归档类数据先执行取回操作，待数据恢复为可读状态后再进行访问。

向挂载目录写入文件失败

问题原因：

写入文件过大，超出限制或不符合推荐写入方式。

并发写入同一个文件：第一个写请求成功，其余写请求失败。

使用 O_TRUNC 标志打开正在读写的文件，引发冲突。

以偏移量 0 覆盖写已存在文件，引发 FSX 对写逻辑的拦截。

解决方案：

针对大文件写入，请参考上传大文件进行排查和优化写入方式。

避免对同一文件进行多路并发写入，必要时对应用侧进行串行化或加锁控制。

不要在文件被读写时使用 O_TRUNC 打开文件，避免强制截断正在访问的文件。

避免以偏移量 0 对已存在文件直接覆盖写入，对写逻辑进行调整以规避被拦截场景。

在挂载目录删除文件失败

问题原因：

挂载时未携带 tos_allow_delete 参数，导致删除权限受限。

被删除文件正在被其他进程并发读写。

解决方案：

确认挂载命令中已正确配置 tos_allow_delete 参数，并在必要时重新挂载。

检查是否有其他进程在访问目标文件，停止相关读写操作后重新尝试删除。

追加写请求失败

问题原因：

挂载时未携带 tos_incremental_upload 参数，追加写能力未开启。

追加期间有其他并发修改导致远端数据发生变化，从而追加失败。

解决方案：

在挂载参数中添加 tos_incremental_upload，重新挂载后再进行追加写操作。

避免在追加写时对同一文件进行其他并发修改。

磁盘内存问题

在 FSX 客户端读写过程中，为什么会写满磁盘空间？

问题原因：

FSX 客户端写入数据时，默认会在 /tmp/ 下写入临时文件，如果写入文件超过磁盘空间大小，可能会写满磁盘空间。

在读缓存场景下，配置的读缓存空间大小超过磁盘空间，可能会写满磁盘空间。

解决方案：

写数据的临时文件目录空间至少需要保证 10240*分段数据的大小，在默认分段数据大小为 8MB 的场景下，临时文件目录空间需要 80GiB 的空间，因此需要确保磁盘空间大于 80GiB。

在读缓存场景下，请确保配置的 max_read_cache_size（读缓存占用最大空间）小于磁盘空间。

在开启读缓存和写缓存时，建议至少为 FSX 客户端预留 120GiB 的磁盘空间。为避免跟系统其他应用争抢磁盘空间，推荐为这部分磁盘空间划分独立分区，详细介绍，请参见 FSX 挂载参数说明。

为什么执行 df 命令后显示磁盘空间大小为 8.0EB？

问题原因：

df 命令展示的数值仅为展示值，不代表存储桶的实际物理空间。其中，Size（磁盘空间总大小）和Avail（磁盘空间剩余可用大小）固定为 8EB，Used（已使用磁盘空间大小）固定为 0 。

解决方案：

避免使用df命令的返回结果来判断存储桶的实际磁盘空间使用情况。

其他问题

如果您在使用 FSX 过程中遇到其他异常情况，请依据工具日志进行问题排查与反馈。

最近更新时间：2026.10.21 16:29:34

这个页面对您有帮助吗？

有用

无用