ossfs 2.0 本地临时目录随机写入配置与原理-对象存储(OSS)-阿里云帮助中心

ossfs 2.0.9 及以后版本支持基于本地临时目录的随机写入。通过配置 --temp_dir 挂载选项，ossfs 2.0 在本地磁盘为写入数据建立暂存（staging）区，使挂载点具备任意偏移写入、任意大小截断、边写边读等完整 POSIX 随机写语义。本文介绍随机写入的工作原理、配置方法、使用约束与使用建议。

背景信息

OSS 对象存储中的对象一旦创建，就不能只修改其中的一部分，任何内容变更都只能整体覆盖重写。ossfs 2.0 默认模式下的写入路径采用流式上传：数据在写入过程中按顺序分片上传到 OSS，存在以下限制：

仅支持顺序写，文件结尾之外位置的 pwrite 不支持；
truncate 仅支持截断到 0，截断到任意非零大小返回 ENOTSUP；
文件写入期间（未 close）不允许读取，返回 EBUSY。

AI Agent 代码执行、脚本就地编辑、科学计算中间结果等场景普遍依赖随机写语义。ossfs 2.0 的随机写入功能通过本地临时目录暂存写入的数据，配合分块（chunk）管理与增量上传，在对象存储之上实现了随机写入。

ossfs 2.0 随机写入模式具备以下特点：

完整 POSIX 随机写语义：支持任意偏移 pwrite、O_APPEND、任意大小 truncate（扩大/缩小）。
边写边读：文件写入期间可同时读取，已修改部分从本地暂存读取，未修改部分直接从 OSS 读取。
增量上传：flush/close 时仅上传被修改的数据块，未修改部分通过 OSS 服务端拷贝（Copy）完成，零本地 IO、零上传带宽消耗。
磁盘空间保护：内置全局磁盘预算，暂存盘空间不足时写入返回 ENOSPC，挂载时可预留空闲空间阈值，避免占满系统盘。

说明

本地临时目录仅服务于写路径，与本地数据缓存（--disk_data_cache_dir，读缓存）相互独立，二者可同时开启（需配置不同目录）、互不影响。

重要

开启随机写入后，写入性能将受限于本地临时目录所在磁盘的读写性能；在拷贝大文件等大批量顺序写入场景下，性能远不及默认模式。请仅在业务确实需要随机写入语义时才开启该功能。

工作原理

本地暂存与合并上传

开启随机写入后，ossfs 2.0 会为每个被随机写的文件在本地临时目录中创建一个暂存文件，按固定数据块（chunk）粒度在本地保存最新的修改：

写入的数据直接落在本地暂存文件中；若写入只覆盖了云端已有数据块的一部分，会先从 OSS 拉取该数据块，保证本地暂存的数据完整。
在 fsync 或 close 时，本地暂存的修改自动与云上数据合并上传：被修改的部分从本地上传，未修改的部分通过 OSS 服务端拷贝（Copy）完成，无需整文件重传，也不消耗本地磁盘读取带宽。
上传成功后自动释放暂存磁盘空间。

边写边读

文件处于写入状态时同样允许读取：已修改的部分从本地暂存读取，未修改的部分直接从 OSS 读取。

磁盘空间保护

挂载时校验临时目录所在磁盘的空闲空间是否满足预留要求，不满足则拒绝挂载。磁盘预留空间不足时写入返回 ENOSPC，进程不会因写满磁盘而异常。

配置方法

配置项	是否必填	说明	默认值
temp_dir	否	本地临时目录路径，需为绝对路径。配置为非空时启用随机写入；为空则关闭该功能。	空
temp_dir_free_bytes	否	为临时目录所在磁盘预留的最小空闲空间（字节，支持 K/M/G 等单位）。ossfs2 不会使用这部分空间存放暂存数据：当磁盘剩余空闲空间低于该阈值时，新的写入将返回 ENOSPC，从而为同盘的其他业务留出安全水位；挂载时若磁盘空闲空间已低于该值，挂载直接失败。最小 64 MiB。	1 GiB
random_write_max_file_size	否	随机写入模式下单个文件的逻辑大小上限（字节，支持 K/M/G 等单位）。超过该限制的写入 / 截断返回 EFBIG。物理上限为 OSS 分片上传容量（10000 分片 × 5 GiB，约 48.8 TiB）。	100 GiB

约束：

--temp_dir 指向的目录不存在时会自动创建；建议使用独立分区 / 独立盘，避免与系统盘或其他业务争抢空间。
写入中的文件数据保存在本地临时目录中，若磁盘空间无法容纳，写入将返回 ENOSPC。将磁盘剩余空闲空间减去 temp_dir_free_bytes 预留的空闲空间后的部分称为磁盘可写入空间，ossfs2 只会使用这部分空间存放写入中的数据；磁盘可写入空间需大于同时在写入的文件总大小（最坏情况下整个文件都会写入本地）。
同一台机器上挂载多个 ossfs2 实例时允许共用同一临时目录（暂存文件命名互不冲突），但多实例会争抢同一磁盘的空间与 IO，建议使用独立目录。
--temp_dir 与 --enable_appendable_object 互斥，不可同时开启。

挂载命令示例：

ossfs2 mount /mnt/oss/ \
  --oss_bucket <your-bucket> \
  --oss_endpoint <your-endpoint> \
  --oss_access_key_id <ak> \
  --oss_access_key_secret <sk> \
  --temp_dir /mnt/disk/ossfs2/temp \
  --temp_dir_free_bytes 1G

环境要求

参数	要求
临时目录磁盘类型	推荐弹性临时盘 / 本地 NVMe / ESSD；磁盘写吞吐直接影响随机写延迟与上传速度
磁盘可用空间	不小于 `temp_dir_free_bytes`，且磁盘可写入空间（见上文使用约束）需能容纳同时在写入的文件数据

功能效果

开启 --temp_dir 前后写入能力对比：

操作	默认模式	随机写入模式
顺序追加写	支持	支持
任意偏移 pwrite（文件结尾之外的位置）	不支持	支持
truncate 到 0	支持	支持
truncate 到任意大小（扩大 / 缩小）	不支持（ENOTSUP）	支持
O_APPEND 追加写已有文件	支持	支持
写入期间读取同一文件	不支持（EBUSY）	支持
多句柄同时写同一文件	不支持	支持

持久化语义：

随机写入模式默认遵守 fsync 语义：fsync 会触发本地修改与云上数据的合并上传，返回成功即表示数据已持久化到 OSS；文件 close 时同样会上传剩余数据。
上传失败会向应用返回错误，应用可通过 fsync 重试；若最终未成功且文件被 close，未持久化数据丢失，文件内容回退到远端最后一次成功上传的版本。
进程异常退出时，未上传的暂存数据丢失，OSS 上的对象保持最后一次成功上传的状态，不会产生损坏的对象。

使用建议

本地临时目录随机写入适用于需要在 OSS 挂载点上执行类本地文件系统写语义的场景。

适合开启随机写入的场景：

场景	使用建议
AI Agent 代码执行 / 沙箱环境（Agent 与代码解释器对文件做任意位置读写、就地编辑）	开启随机写入；临时目录建议使用独立高性能磁盘，磁盘可写入空间按同时在写入的文件总大小预留。
科学计算 / 仿真类应用的中间结果文件	开启随机写入；磁盘可写入空间按同时在写入的文件总大小规划。

不建议开启随机写入的场景：

场景	使用建议
大文件拷贝（cp、rsync 等批量写入挂载点）	该场景下写入性能受限于本地磁盘，远不及默认模式，请使用默认的流式上传模式。
纯顺序追加写（日志流式写入）	默认流式上传路径开销更低，无需开启随机写入；如需边写边读可选 `--enable_appendable_object`。

磁盘预算配置建议：

临时目录与系统盘分离，避免暂存数据撑满系统盘影响主机稳定性；若机器只有一块磁盘，建议将 temp_dir_free_bytes 配置为较大的值（例如 10G），为系统预留充足的空闲空间。
磁盘可写入空间（见上文使用约束）需大于同时在写入的文件总大小。
单文件超过 100 GiB 时，除显式调大 --random_write_max_file_size（例如 --random_write_max_file_size=500G）外，还需确保磁盘可写入空间超过该文件大小。