在编写ossfs 2.0配置文件时，您可以根据不同的挂载需求，灵活配置各项参数，生成符合特定场景的配置文件。通过该配置文件，您可以轻松实现对OSS Bucket的多样化文件系统挂载，满足不同业务场景的需求。
基础配置项
|
分类 |
配置项 |
是否必填 |
说明 |
默认值 |
支持版本 |
|
Bucket基本配置 |
oss_endpoint |
是 |
Bucket访问域名。 |
无 |
v2.0.0及以后 |
|
oss_bucket |
是 |
Bucket名称。 |
无 |
v2.0.0及以后 |
|
|
访问凭证配置 |
oss_access_key_id |
条件必填 |
访问密钥ID。AccessKey 认证方式下必填。 |
无 |
v2.0.0及以后 |
|
oss_access_key_secret |
条件必填 |
访问密钥。AccessKey 认证方式下必填。 |
无 |
v2.0.0及以后 |
|
|
ram_role |
条件必填 |
ECS RAM角色。ECS RAM角色认证方式下必填。 |
无 |
v2.0.2及以后 |
|
|
credential_process |
条件必填 |
外部进程获取访问凭证的执行命令。 外部进程认证方式下必填。 |
无 |
v2.0.5及以后 |
常用配置项
|
分类 |
配置项 |
是否必填 |
说明 |
默认值 |
支持版本 |
|
Bucket配置 |
oss_bucket_prefix |
否 |
挂载存储空间中指定的文件目录。 |
空 |
v2.0.0及以后 |
|
oss_region |
否 |
存储空间的region id，用于OSS V4签名算法。若不指定，则使用OSS V1签名算法。 |
空 |
v2.0.0及以后 |
|
|
缓存配置 |
attr_timeout |
否 |
文件元数据缓存失效时间（秒）。 |
60 |
v2.0.0及以后 |
|
negative_timeout |
否 |
无效目录项缓存失效时间（秒）。 |
0 |
v2.0.0及以后 |
|
|
readdirplus |
否 |
开启readdirplus功能，开启后会在执行readdir的过程中将文件的元数据缓存同步构建出来，会消耗更多的内存。 |
true |
v2.0.0及以后 |
|
|
disk_data_cache_dir |
否 |
本地缓存目录路径。配置为非空时启用数据缓存。详细说明请参见本地数据缓存。 |
空 |
v2.0.8 及以后 |
|
|
disk_data_cache_size |
条件必填 |
缓存容量上限，按 GiB 对齐。不可超过缓存目录所在磁盘/分区的可用空间。disk_data_cache_dir 可以为空；disk_data_cache_dir 指定之后，本参数必须填入合法值。 |
空 |
v2.0.8 及以后 |
|
|
disk_data_cache_io_engine |
否 |
磁盘缓存 IO 引擎，可选 psync 或 libaio。 |
psync |
v2.0.8 及以后 |
|
|
写入模式配置 |
temp_dir |
否 |
本地临时目录路径，需为绝对路径。配置为非空时启用基于本地临时目录的随机写入模式，支持任意偏移写入、任意大小截断等完整 POSIX 写入语义；为空则关闭该功能。详细说明请参见配置本地临时目录支持随机写入。 |
空 |
v2.0.9 及以后 |
|
temp_dir_free_bytes |
否 |
为临时目录所在磁盘预留的最小空闲空间（字节，支持 K/M/G 等单位）。当磁盘剩余空闲空间低于该阈值时，新的写入将返回 ENOSPC；挂载时若磁盘空闲空间已低于该值，挂载直接失败。最小 64 MiB。 |
1 GiB |
v2.0.9 及以后 |
|
|
random_write_max_file_size |
否 |
随机写入模式下单个文件的逻辑大小上限（字节，支持 K/M/G 等单位）。超过该限制的写入/截断返回 EFBIG。物理上限为 OSS 分片上传容量（10000 分片 × 5 GiB，约 48.8 TiB）。 |
100 GiB |
v2.0.9 及以后 |
|
|
日志配置 |
log_level |
否 |
日志输出的等级，可选info、debug。 |
info |
v2.0.0及以后 |
|
log_dir |
否 |
日志文件存储目录。 |
/tmp/ossfs2 |
v2.0.0及以后 |
|
|
log_file_max_size |
否 |
单个日志文件最大的大小（Bytes）。 |
67108864 |
v2.0.3及以后 |
|
|
log_file_max_count |
否 |
最多保留的日志文件的个数。 |
8 |
v2.0.3及以后 |
|
|
运行模式 |
f |
否 |
是否使用前台运行模式。 |
false |
v2.0.0及以后 |
|
d |
否 |
是否使用前台运行模式并开启fuse调试日志。 |
false |
v2.0.0及以后 |
|
|
挂载模式 |
ro |
否 |
使用只读的方式进行挂载。 |
false |
v2.0.0及以后 |
|
权限配置 |
gid |
否 |
配置后，挂载点下所有文件和文件夹gid属性将变为配置值。gid 参数仅在挂载时生效，挂载后执行 chown、chmod 等命令会返回成功（exit code 0），但不会修改文件的 gid 或权限。如需修改 gid，需先执行 |
当前执行挂载用户的gid |
v2.0.1及以后 |
|
uid |
否 |
配置后，挂载点下所有文件和文件夹uid属性将变为配置值。uid 参数仅在挂载时生效，挂载后执行 chown、chmod 等命令会返回成功（exit code 0），但不会修改文件的 uid 或权限。如需修改 uid，需先执行 |
当前执行挂载用户的uid |
v2.0.1及以后 |
|
|
file_mode |
否 |
配置后，挂载点下所有文件的权限属性将变为配置值。 |
0777 |
v2.0.1及以后 |
|
|
dir_mode |
否 |
配置后，挂载点下所有文件夹的权限属性将变为配置值。 |
0777 |
v2.0.1及以后 |
|
|
allow_other |
否 |
配置allow_other=true后将允许非root用户访问该挂载点下文件，访问时会根据文件的权限属性进行权限校验。 |
true |
v2.0.1及以后 |
高级配置项
|
分类 |
配置项 |
是否必填 |
说明 |
默认值 |
支持版本 |
|
网络配置 |
bind_ips |
否 |
绑定指定的IP列表作为访问OSS的源IP，使用逗号拼接。例如，192.168.0.1,192.168.0.2。通过指定IP列表可以控制访问OSS时所使用的网卡，支持在多网卡环境下提升总吞吐能力。 |
空 |
v2.0.3及以后 |
|
http_proxy |
否 |
指定用于转发OSS请求的HTTP代理服务器地址。 |
空 |
v2.0.8 及以后 |
|
|
上传配置 |
upload_buffer_size |
否 |
分片上传缓冲区大小（Bytes），即分片大小。该参数决定了能够写入文件最终大小，计算方式为upload_buffer_size * 10000。 |
8388608 |
v2.0.0及以后 |
|
upload_concurrency |
否 |
分片上传并发度。 |
64 |
v2.0.0及以后 |
|
|
sync_upload |
否 |
开启后，关闭文件时会等待文件上传完毕后返回。 |
true |
v2.0.0及以后 |
|
|
下载/预取配置 |
prefetch_concurrency |
否 |
全局下载预取的并发度。 |
256 |
v2.0.0及以后 |
|
prefetch_concurrency_per_file |
否 |
单个文件句柄下载预取的并发度。 |
64 |
v2.0.0及以后 |
|
|
prefetch_chunk_size |
否 |
预取的chunk大小（Bytes）。 |
8388608 |
v2.0.0及以后 |
|
|
prefetch_chunks |
否 |
预取的chunk数量，不设置默认为prefetch_concurrency的3倍。设置为-1时，不再限制预取内存，每个文件句柄都可以获取足够的内存进行预取。 |
0（根据prefetch_concurrency自动配置） |
v2.0.0及以后 |
|
|
内存管理配置 |
total_mem_limit |
否 |
总使用内存限制（Bytes），设置后会根据内存限制自适应调整upload和prefetch的并发程度。 若不配置此选项，默认会使用 total_mem_limit的默认值对于运行机器内存小于等于16 GB的运行环境默认会配置为系统内存的一半，超过16 GB内存的不限制。 |
0 |
v2.0.0及以后 |
|
max_inode_cache_count |
否 |
表示启用主动控制元数据缓存数量。
|
0 |
v2.0.4及以后 |
|
|
文件校验/元数据配置 |
enable_crc64 |
否 |
是否开启文件写入CRC（循环冗余校验）校验。 |
true |
v2.0.0及以后 |
|
close_to_open |
否 |
支持close-to-open语义，开启该选项后，打开文件时会发送GetObjectMeta请求获取OSS中的文件信息，保证元数据信息的实时性。 默认为关闭，此时打开文件时根据文件的元数据缓存过期时间，决定是否发送请求到OSS以获取最新的文件属性。开启此选项后，由于每次打开文件时都会强制发送请求到OSS，在大量读取小文件的场景下会显著增加访问时延。 |
false |
v2.0.0及以后 |
|
|
文件操作配置 |
rename_dir_limit |
否 |
单次重命名操作中，源目录下所有子孙文件与目录数量的上限总和。一旦实际数量超过该上限，重命名操作便会报错。 |
2000000 |
v2.0.0及以后 |
|
enable_appendable_object |
否 |
开启后，写入文件使用AppendObject接口，该模式下可以支持对一个文件边写边读。 |
false |
v2.0.0及以后 |
|
|
appendable_object_autoswitch_threshold |
否 |
在enable_appendable_object开启后，小于等于该参数大小（Bytes）的OSS中非Appendable对象，追加写入时支持自动转换成Appendable对象。 |
0 |
v2.0.5及以后 |
|
|
enable_symlink |
否 |
开启symlink功能，仅支持在挂载点内部以相对路径的方式进行创建。 |
false |
v2.0.6及以后 |
|
|
请求超时配置 |
oss_request_timeout_ms |
否 |
发送至OSS的请求超时时间（毫秒）。 |
60000 |
v2.0.0及以后 |
|
缓存配置 |
oss_negative_cache_timeout |
否 |
OSS 404请求项缓存失效时间（秒）。 |
0 |
v2.0.2及以后 |
|
oss_negative_cache_size |
否 |
OSS 404请求项缓存条目数量。 |
10000 |
v2.0.2及以后 |
|
|
memory_data_cache_size |
否 |
该模式下将预分配固定大小的内存用于读取缓存。目前主要用于解决并发读取文件的预取放大问题，能有效提升多GPU卡加载大模型时的性能。 |
0 |
v2.0.5及以后 |
|
|
kernel_readdir_cache_timeout |
否 |
内核目录缓存失效时间（秒）。仅支持 Linux 内核 4.20 及以上版本。 |
0 |
v2.0.7及以后 |
相关文档
-
关于ossfs 2.0常用场景的配置文件示例，请参见配置ossfs 2.0。