ossfs 2.0常见问题

挂载报错ERROR: failed to mount ossfs2, see more details in log file

问题分析：该问题为通用报错，具体信息需要去日志中查看对应报错。常见错误主要是权限或配置参数有误导致的。例如：

所使用的AccessKey（访问密钥）不具有该Bucket的访问权限，请确认您的AccessKey（访问密钥）是否具备访问权限，同时确保Bucket名称配置正确。

您配置的AccessKey（访问密钥）参数有误。

解决方案：根据日志中的对应报错信息，修改正确后重新挂载。

挂载报错MOUNTPOINT: Directory does not exist: /mnt/ossfs2

问题分析：未创建该目录导致。

解决方案：先创建对应的目录，之后再进行挂载操作。

挂载报错MOUNTPOINT: directory /mnt/ossfs2 is not empty.

问题分析：要挂载的目标文件夹非空，ossfs 2.0要求挂载文件夹必须为空文件夹。

解决方案：排查该文件夹是否已经挂载其他文件系统，若已经挂载其他文件系统可以尝试使用umount命令先卸载对应文件系统，若未挂载其他文件系统，请排查该文件夹下是否有残留文件。也可以切换到其他空目录进行挂载。

挂载报错version `FUSE_3.12' not found

问题分析：安装文件缺失导致ossfs 2.0尝试使用系统安装的libfuse库但版本过低。

解决方案：卸载对应的安装包重新安装。

挂载报错fuse: device not found, try 'modeprobe fuse' first 或在日志中看到 fuse_session_mount failed with error: No such file or directory

问题分析：无法访问到/dev/fuse设备，常见于容器环境下没有对应的访问权限。

解决方案：若在容器环境中挂载，需要使用特权模式启动对应容器。

写入文件报错File too large

问题分析：ossfs 2.0默认配置part大小为8 MiB，最大支持78.125 GiB的文件。当您写入的文件大小超过这个限制时会遇到该报错。

解决方案：挂载Bucket时，通过配置upload_buffer_size选项来增加最大支持的文件大小。请注意配置upload_buffer_size意味着需要更多的内存资源。ossfs 2.0支持配置total_mem_limit来控制内存使用，具体请参见挂载选项说明。

写入文件报错Invalid argument

问题分析：ossfs 2.0不支持对文件进行随机位置写入，仅支持顺序地往文件的末尾追加写入，若写入的位置非文件当前末尾的位置会报错Invalid argument。日志报错信息如下：

解决方案：若您的业务对随机写入为强需求时，需要切换到ossfs 1.0以支持随机写入。通常情况下，您的随机写入可能来自于同一个文件句柄的并发写入，若是这类情况，ossfs 2.0已经针对顺序写入进行了性能优化，单线程已经具有比较好的吞吐性能，可以切换到单线程顺序写入解决该问题。

在挂载点下运行git clone运行失败（读取文件报错非预期的No such file or directory）

问题分析：ossfs 2.0默认不支持对同一个文件同时进行写入和读取，对正在写入的文件进行读取操作可能读到旧的数据或读取报错。git clone命令存在边写边读的访问模式，您可以在日志中找到如下报错信息：

其中errno 2为Linux错误码ENOENT，说明这个文件的数据没有被正确读取到。如果您遇到其他应用读取报错，可以先查看日志中是否有类似报错信息。在读取数据时无法返回文件不存在，则有可能是应用写入的文件还没有关闭导致文件没有上传到OSS中所导致。

解决方案：避免使用相关命令，可以git clone到本地磁盘上再使用cp命令拷贝到挂载点中。

并发写入同一个文件写入报错Device or resource busy

问题分析：ossfs 2.0某个文件同一时间被多次打开时，仅有一个文件句柄支持顺序写入，后续的其他文件句柄写入会报错。报错信息如下：

解决方案：避免并发写入同一个文件，ossfs 2.0针对顺序写入进行了性能优化，单线程已经具有比较好的吞吐性能。

卸载时报错umount: /mnt/ossfs2: target is busy.

问题分析：有进程正在访问挂载目录/mnt/ossfs2下的文件，所以无法卸载。

解决方案：

1. 使用lsof /mnt/ossfs2找出访问该目录的进程。

2. 停止该进程访问。

3. 重新卸载。

使用ossfs 2.0时出现大量404日志

背景信息：在使用 ossfs 2.0 的过程中，日志中出现的 404 Not Found 记录是常见现象。大多数情况下这并非系统错误，而是 ossfs 2.0为模拟本地文件系统语义所采取的正常交互行为。

在操作文件前，操作系统会主动检查目标对象是否存在。该过程可能导致向 OSS 发起大量探测请求，其中“对象不存在”的响应即返回404状态码。

ossfs 2.0检查对象存在性的完整流程如下：

1. 发送 GetObjectMeta 请求查询指定路径（如 object）是否作为实际对象存在。

   如果对象存在，则系统直接返回文件元信息；如果对象不存在，则系统返回404并继续执行下一步。

   说明

   即使对象不存在，ossfs 2.0仍需判断该路径是否代表“目录”。

2. 收到404后，发送 ListObjects 请求判断指定路径是否为“目录”，即查询以 object/为前缀的对象。

   如果返回结果为空，则最终判定路径不存在；如果返回结果非空，则表示目录存在，系统列出目录内容。

问题分析：

• 使用 stat 等命令访问不存在的文件时，系统返回 404并映射为本地文件系统的 No such file or directory 错误。

• 批量创建文件或目录前，操作系统会先检查目标文件是否存在，文件不存在时才发送创建请求。检查过程中产生的404错误属于预期行为，非系统异常。

解决方案：虽然 404 属于正常行为，但在高并发或批量操作场景下，频繁的探测请求会影响性能，可通过以下配置进行优化：

1. 通过调大--attr_timeout延长元数据缓存时间（默认60s）。

   在元数据失效前查询文件或目录，可避免重复发起OSS请求。

2. 通过配置--oss_negative_cache_size和--oss_negative_cache_timeout启用负缓存（Negative Cache）。

   首次查询文件不存在时，将结果缓存在内存中。后续在缓存失效前查询文件时，直接查询本地负缓存而不发送OSS请求。

   • --oss_negative_cache_size：OSS文件负缓存的条目数量，默认为10000。

   • --oss_negative_cache_timeout：OSS文件负缓存的失效时间，默认为0。