文档中心

对象存储

请输入

FSX

TOS FSX 概述

本文为您介绍 FSX 客户端的功能特性、运行环境、使用限制、使用流程及版本更新日志等信息，帮助您快速了解并使用该工具。FSX 是用于挂载存储桶的客户端，通过该客户端，您可以把 TOS 存储桶挂载到 Linux 系统，并将其作为本地文件系统使用。这使您无需适配 TOS API，即可直接通过文件系统操作来管理 TOS 存储桶数据，从而简化开发流程，提升数据操作效率。

使用场景

FSX 支持将存储桶挂载到 Linux 系统作为本地文件系统使用，适用于需要按照文件系统语义使用存储桶中数据的场景，例如 AI 机器学习场景下需要按照文件系统语义训练模型数据。

FSX 支持在挂载存储桶时配置预读、数据缓存，用于提升文件读取性能，使用场景及性能优化详情请参见 FSX 性能调优。

功能特性

支持挂载桶或桶下的目录到 Linux 系统。

挂载存储桶到 Linux 后，在本地新增或覆盖等操作会自动同步到 TOS 存储桶，在 TOS 存储桶的新增、覆盖等操作也会自动同步到本地。

支持数据缓存，具体包括读缓存和写缓存功能，可以减少数据访问的延迟，提升系统性能。

支持元数据缓存，提升文件操作效率。

运行环境

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

硬件资源要求

FSX 工具会占用系统的存储空间用于存放缓存数据、日志文件等内容。为了确保 FSX 工具的高效稳定运行，建议系统至少为 FSX 预留 32GiB 内存和 50GiB 磁盘空间。以下是关于 FSX 工具各类文件所需磁盘空间以及目录规划的详细说明：

说明

请勿修改或删除以下目录里的文件，否则可能导致 FSX 工具使用异常。

目录类型	说明	配置方法
软件安装目录	FSX 所有可执行文件的存放目录，固定为 /opt/fsx，建议至少预留 1GiB 的磁盘空间。	系统内置，不可修改。
内部状态记录目录	FSX 过程记录文件的存放目录。默认为 /opt/tmp/fsx。这些文件占用空间大小取决于系统活跃的文件数量和并发请求数。建议至少预留 2GiB 的磁盘空间。	通过 persist_dir 挂载参数指定 FSX 过程记录文件的存放目录。
读缓存目录	对于小数据量频繁读取某一批文件场景，FSX 客户端提供了读数据缓存功能。如果使用读缓存功能，建议与写缓存一起使用独立分区，并指定存放路径，至少预留 20GiB 的磁盘空间。关于读缓存的详细介绍，请参见读缓存性能。	通过 read_cache_dir 挂载参数指定读缓存的存放路径。通过 max_read_cache_size 挂载参数指定读缓存的空间占用大小。
写缓存目录	FSX 客户端默认会先写入数据到本地临时文件目录，具体的占用量与系统并发写入的数据量成正比。默认情况下，建议与读缓存一起使用独立分区，指定存放路径，并预留 10GiB 的磁盘空间。关于写缓存的详细介绍，请参见写缓存性能。	通过 temp_dir 挂载参数指定写缓存的存放路径。通过 max_temp_capacity 挂载参数指定写缓存的最大占用磁盘空间。通过 part_size 挂载参数指定单个写缓存临时文件的最大大小。
运行日志目录	FSX 客户端在运行过程中会产生运行日志，默认情况下，运行日志会存放在 /var/log/fsx 目录下，建议预留 2GiB 的磁盘空间。	系统内置，不可修改。

使用限制

读写限制

限制	说明
访问限制	归档存储、冷归档或深度冷归档的数据需要取回后才能访问，不支持直接读取。使用 FSX 工具挂载存储桶时，仅支持 TOS 域名，暂不支持 S3 域名。
写入限制	多客户端同时挂载同一存储桶并写入同一文件时，无法保证数据一致性。新写入的文件必须在文件关闭后才会上传到 TOS，因此文件关闭后，才能对其他客户端可见。对文件执行追加写操作后，不同类型的对象，支持执行的 flush 操作次数不同，说明如下：追加写 FNS 桶中的对象时，云端的历史数据会使用 UploadPartCopy 接口对 TOS 中的数据进行复制，追加的新数据则使用 UploadPart 或 PutObject 接口进行上传。该场景下，一次 open 操作仅支持一次 flush 操作。追加写 HNS 桶中的对象时，TOS 会使用 AppendObject 接口进行数据的追加写操作。该场景下，支持对追加写的对象执行多次 flush 操作。对已存在的文件覆盖写时，打开该文件需要设置 O_TRUNC 标志位。文件写入时，大文件会通过分片上传的方式进行上传，单个对象最多 10000 个分片，默认参数分片大小为 8MB，如需上传超过 80000MB 的文件，请按需调大分片大小，详细介绍，请参见 FSX 挂载参数说明章节中的 part_size参数。挂载 FNS 桶时，重命名文件可能为非原子操作： FSX 会优先使用 RenameObject API，如果执行成功，则为原子操作；如果该 Object 不支持使用 RenameObject，FSX 会使用 CopyObject + DeleteObject 实现重命名行为，如果 DeleteObject 失败，那么重命名的源对象会被保留。不支持并发写入同一个文件，如果发生并发写入请求，则第一个请求会成功，后续的请求将失败。

POSIX 语义兼容

挂载存储桶到 Linux 系统后，Linux 系统可以通过兼容的 POSIX 文件接口管理桶内对象。由于 FSX 客户端只兼容部分 POSIX 语义，因此在 Linux 系统对存储桶执行的操作受限。

关于表格中的标识，说明如下：

✅ ：表示支持该功能。

✔️：表示部分支持，具体支持情况请参考备注。

❌ ：表示不支持该功能。

分类	POSIX 接口	说明	是否支持	备注
文件属性	statfs	用于获取文件系统的状态信息。	✅	无。
		fstat	查询文件属性。	✅	无。
		getattr/setattr	用于获取/修改文件或目录的属性。	✔️	时间、权限相关功能支持需打开兼容优先模式。 chmod 与 chown 说明：建议在文件关闭后再执行该操作。未设置 mode 和 own 相关的属性，则以挂载参数中的对应参数值为准（详见 FSX 挂载参数说明中 uid、gid、file_mode 和 dir_mode 参数。） FSX 通过对象的自定义元数据进行相关属性的持久化，在 readdir 时默认会查询文件夹对应的元数据，如果您想要提升性能，则挂载时可以按需配置 tos_num_readdir_meta 参数。
		lookup	查找文件或目录的操作。	✅	无。
文件写入	flush	将缓冲区中的数据强制写入到输出流。	✅	无。
目录操作	opendir	打开一个目录流，用于读取该目录中的文件和子目录。	✅	无。
		readdirplus	提供更详细的目录项信息。	✅	无。
		releasedir	释放与目录流相关资源。	✅	无。
		mkdir	创建一个新目录。	✅	无。
		rmdir	删除空目录。	✅	无。
文件基本操作	create	创建新文件。	✅	无。
		open	打开文件。	✔️	携带 O_TRUNC 时需打开兼容优先模式。
		close	用于关闭已打开的文件描述符。	✅	无。
		read	顺序读。	✅	无。
		pread	随机读。	✅	无。
		write	顺序写入。	✅	并发写入会串行执行。业务软件以文件结尾为偏移量来写文件，即使未携带 O_APPEND 标记，FSX 仍统一视为追加写，予以支持。
		pwrite	随机写入。	✔️	需打开兼容优先模式。
		release	释放文件描述符。	✅	无。
		forget	通知文件系统服务器忘记某个文件的状态信息。	✅	无。
		rename（文件）	更改文件名称。	✅	文件在读写过程中，不支持 rename 该文件和文件对应的文件夹。说明在对对象执行 rename 操作前，您需要先开启 rename 功能，具体操作，请参见开启 RenameObject 。仅支持对开启 RenameObject 功能后新上传的对象执行 rename 操作。具体操作，请参见开启 RenameObject 。
		rename（目录）	更改目录的名称。	✅	不保证 rename 目录的原子性。
		unlink	用于删除文件。	✅	文件在读/写过程中，不允许删除。
文件操作	setlk	设置文件锁。	❌	无。
		getlk	获取当前对文件的锁定状态	❌	无。
		flock	在文件上施加或释放锁。	✅	无。
		truncate	调整文件的大小。	✔️	需打开兼容优先模式。
		ftruncate	对打开的文件调整大小。	✔️	需打开兼容优先模式。
		utime	修改文件的存取时间和更改时间。	✔️	需打开兼容优先模式。
		lseek	指定打开文件中的读写位置。	✅	无。
		access	校验文件权限。	❌	内核会自动检查权限。
链接	硬链接	使用硬链接。	❌	无。
		symlink	创建软链接。	✅	未打开兼容模式时：软链接指向的目标文件如果为软链接，那么在非 FSX 场景下，客户使用 TOS 协议访问该软链接时，将无法通过二级软链接访问指向的目标文件。
		readlink	读取软链接。	✅	无。
扩展属性	setxattr	设置文件或目录的扩展属性。	❌	无。
扩展属性		getxattr	获取文件或目录的扩展属性。	❌	无。
其他	mknod	创建文件系统中的特殊文件，包括字符设备文件和块设备文件。	✅	无。
		fallocate	为文件分配空间。	❌	无。
		copy_file_range	在同一文件系统内高效地复制文件内容。	❌	无。
		poll	监视多个文件描述符，以便检测它们是否准备好进行 I/O 操作。	❌	无。
		bmap	函数用于获取文件在磁盘上的物理块号。	❌	无。
		ioctl	设备控制操作，允许程序在文件描述符上执行特定的控制命令。	❌	无。
		fsync	将文件的内存缓冲区中的数据同步到磁盘。	✅	持久化写到本地盘，flush 后上传到 tos。

更新日志

版本号	版本类型	发布日期	更新说明
1.4.0.1846	最新版本	2026-10-08	优化版本稳定性。
1.3.6.1271	历史版本	2026-07-27	优化元数据操作请求，降低 io 次数。
1.3.4.285	历史版本	2026-06-26	修复读场景下低概率卡住问题。
1.3.4.282	历史版本	2026-06-16	兼容优先模式支持带 path 的 truncate。修复 opendir 并发过高导致 mount 失败的问题。
1.3.2.790	历史版本	2026-04-03	提供 posix 语义兼容性，可通过 compatible_mode=true 挂载参数开启。 FSX 稳定性加固，修复若干稳定性问题。
1.3.1.730	历史版本	2026-03-16	优化目录识别兼容性。优化大文件写入场景。
1.3.1.440	历史版本	2026-01-20	优化大目录写入场景，提升业务稳定性。
1.3.1.372	历史版本	2026-01-19	优化软链接兼容模式。提升目录权限场景兼容性。写流程数据校验加固。
1.3.0.855	历史版本	2025-12-26	提升软链接兼容性。
1.3.0.370	历史版本	2025-12-04	支持 Rocky Linux 9.1 ～ 9.5 操作系统。
1.2.7.546	历史版本	2025-11-24	新增挂载参数 tos_symlink_mode，用于设置软链接模式，详细介绍，请参见 FSX 挂载参数说明。
1.2.7.534	历史版本	2025-11-13	优化读缓存性能。
1.2.7.530	历史版本	2025-11-03	支持在 ARM64 架构的操作系统中安装和使用 FSX 客户端，详细介绍，请参见运行环境。提升软链接场景的兼容性。
1.2.6.210	历史版本	2025-09-24	优化版本稳定性。支持通过 FSX 免密挂载存储桶或指定目录。详细介绍，请参见免密挂载。
1.2.5.520	历史版本	2025-09-03	修复部分操作系统通过 HTTPS 协议挂载存储桶失败的问题。
1.2.5.506	历史版本	2025-09-01	优化版本稳定性。
1.2.5.331	历史版本	2025-08-15	在非追加写场景下，支持为 FNS 桶配置服务端加密。详细介绍，请参见基本参数。
1.2.4.386	历史版本	2025-07-31	优化版本稳定性。
1.2.4.355	历史版本	2025-07-24	优化版本稳定性。
1.2.3.711	历史版本	2025-07-11	优化版本稳定性。
1.2.3.592	历史版本	2025-07-04	FSX 客户端由邀测转为正式发布。
1.1.0.400	历史版本	2024-12-30	首次发布。

使用流程

下载与安装 FSX。

FSX 配置与挂载。

最近更新时间：2026.10.08 15:45:52

这个页面对您有帮助吗？

有用

无用