配置
更新时间：2026-09-18
参数设置
bosfs2 支持通过 -o key=value 设定参数来配置鉴权、性能、缓存与日志等。执行 bosfs2 -h 可获得完整参数说明。
连接与鉴权
| 参数 | 作用 | 说明 |
|---|---|---|
-o endpoint=<url> |
BOS 服务地址 | 如 http://bj.bcebos.com；带 https:// 前缀走 SSL；不指定则按 bucket location 自动定位 |
-o ak=<access key> |
Access Key | 也可用 credentials 文件 |
-o sk=<secret key> |
Secret Key | 也可用 credentials 文件 |
-o credentials=/path |
从文件读取 AK/SK | 使用 STS 时必须用此方式。格式：[defaults] / bce_access_key_id=xxx / bce_secret_access_key=xxx / bce_security_token=xxx / reload_interval_s=60 |
-o region_auto=<ON/OFF> |
自动探测 region 并更新 endpoint | 默认 OFF |
-o ro |
只读挂载 | 拒绝所有写操作 |
性能与缓存
| 参数 | 作用 | 说明 |
|---|---|---|
-o multi_thread=<n> |
最大并发请求线程数 | 默认 20，可按 CPU 核数调整 |
-o multipart_size=<size> |
三步上传每个 part 大小 | 默认 16MB，范围 [1MB, 5GB]。小于该值直接走 PutObject；同时决定单文件最大大小 = 10000 × multipart_size（默认约 156GiB） |
-o block_size=<size> |
顺序读每个预读块的大小 | 默认 4MB，一般无需改动，不得小于 1MB |
-o preload_blocks=<n> |
顺序读每个文件最多预读的块数 | 默认 64。总预读 = preload_blocks × block_size |
-o memory_limit=<size> |
读写缓存总内存上限 | 需带单位 KB/MB/GB；-1 或 ≤0 表示使用空闲内存的 80%；默认 1GB（旧参数 mem_cache_limit_size 已废弃，单位为 MB） |
-o mem_gc_interval=<second> |
内存池闲置回收周期 | 默认 0（不回收） |
-o max_mem_file_size=<size> |
完全缓存到内存、支持随机读写的最大文件大小 | 默认 16MB。需满足 max_mem_file_size × 2 ≤ memory_limit |
-o full_cache_threshold=<size> |
尝试完全缓存的文件大小阈值 | 默认 0（关闭） |
-o max_background=<n> |
内核在途后台（预读/异步）请求上限 | 默认 64；0 用内核默认（12）。同步请求由 max_threads 约束 |
超时
| 参数 | 作用 | 说明 |
|---|---|---|
-o connect_timeout=<ms> |
连接 BOS 超时 | 默认 3000ms |
-o client_timeout=<second> |
数据传输超时 | 默认 120s；传入大于 1000 的值按毫秒换算，最小 30s。内网可适当调小以快速重试 |
-o client_timeout_ms_1st=<ms> |
首次请求超时 | 默认 5000ms |
缓存过期
| 参数 | 作用 | 说明 |
|---|---|---|
-o meta_expires=<second> |
meta/attr 缓存过期时间 | 默认 1s。文件不存在时不受 cache 影响，仍能 list/get 到最新文件 |
-o data_expires=<second> |
文件数据缓存过期时间 | 默认 2s |
-o idle_cache_expires=<ms> |
空闲读缓存回收超时 | 默认 1500ms |
日志
| 参数 | 作用 | 说明 |
|---|---|---|
-o logfile=/path |
日志文件路径 | 需绝对路径（daemon 后工作目录切到 /） |
-o sdklogfile=/path |
SDK 日志路径 | 默认为 fs 日志路径加 _sdk 后缀 |
-o loglevel=<...> |
日志级别 | 可选 fatal / error / warn / info / debug / trace，大小写不敏感，默认 info |
-o sdkloglevel=<...> |
SDK 日志级别 | 可选 fatal / error / warn / info / debug，默认 info |
-o log_rotate_size=<MB> |
单个日志切割大小 | 默认 128MB |
-o log_quota_size=<MB> |
日志总占用容量，超出自动清理最旧 | 默认 1GB |
写入 / Append
| 参数 | 作用 | 说明 |
|---|---|---|
-o append_mode=<off/auto/force> |
新建文件是否使用 append 协议 | off 不使用；auto 仅当以 O_APPEND 打开时创建 appendable 对象；force 所有新建文件都用 append 协议。默认 off。仅影响新建文件：已存在的普通对象不会因此被转换，需配合 append_auto_convert 才会转换 |
-o append_buffer_size=<size> |
append 写缓冲大小 | 0 关闭缓冲，默认 16MB |
-o append_flush_interval=<ms> |
append 缓冲最长驻留时间 | 默认 100ms |
-o append_auto_convert=<on/off> |
已存在的普通对象以 O_APPEND+O_TRUNC 打开时自动转为 appendable | 需 append_mode ≠ off。默认 off |
目录 rename
| 参数 | 作用 | 说明 |
|---|---|---|
-o enable_fast_rename=<on/off> |
NS 桶目录 rename 走服务端 RenameObject | 默认 on；关闭则回退逐对象 DFS |
-o rename_qps_limit=<n> |
FLAT 桶目录 rename 客户端 QPS 上限 | 默认 4000，0 关闭 |
-o rename_max_in_flight=<n> |
目录 rename 并发在途请求数 | 默认 160 |
-o rename_batch_size=<n> |
rename lister 预取 key 上限（限制内存） | 默认 30000 |
-o rename_retry_sleep_ms=<ms> |
NS 桶单次目录 rename 的退避睡眠预算 | 默认 30000ms |
文件属性
| 参数 | 作用 | 说明 |
|---|---|---|
-o uid=<uid> / -o gid=<gid> / -o umask=<umask> |
bosfs 新建文件的属主/权限 | — |
-o direct_io |
开启 direct I/O，绕过 page cache | — |
FUSE 参数
| 参数 | 作用 | 说明 |
|---|---|---|
-o allow_other |
允许其他用户读写 | 默认目录权限 777、文件权限 666 |
-o max_threads=<n> |
FUSE 并发工作线程数 | libfuse 标准选项，默认 10 |
挂载样例
Plain Text
1bosfs2 <bucket>[/<bos_dir_path>] <local-mount-dir> \
2 -o endpoint=http://bj.bcebos.com \
3 -o ak=xxx \
4 -o sk=xxx \
5 -o memory_limit=8192MB \
6 -o mem_gc_interval=1 \
7 -o multi_thread=32 \
8 -o max_threads=32 \
9 -o preload_blocks=256 \
10 -o multipart_size=32M \
11 -o block_size=4M \
12 -o meta_expires=5 \
13 -o log_quota_size=10000 \
14 -o log_rotate_size=1000 \
15 -o loglevel=info \
16 -o logfile=/var/log/bosfs2.log \
17 -o max_mem_file_size=32MB \
18 -o allow_other日志
日志默认输出到 stderr，可用 -o logfile=xxxx/xxxx.log 指定文件。使用 -d 打开 debug 模式时可重定向到本地文件。
注意：
- 切勿将 logfile 或重定向路径指向 mountpoint 内部，否则会持续把日志刷入 BOS，造成不必要的开销。
- 未使用
-d/-f前台模式时，bosfs2 会变成 daemon 并将工作目录切到/，因此 logfile 必须指定绝对路径。
推荐配置
meta_expires适当增大可显著提升 lookup、stat 性能。multi_thread适当增大可提升大文件顺序读写性能。max_threads适当增大可提升小文件读写及非 listdir 的元数据性能。
大文件顺序读
以读为主，总缓存 10GiB、后台任务线程 128、预读块 4M、预读 512 块（约 2GiB），并设内存回收周期让读占更多内存：
Plain Text
1-o memory_limit=10240MB -o multi_thread=128 -o mem_gc_interval=10 -o block_size=4M -o preload_blocks=512大文件顺序写
单文件最大大小 = 10000 × multipart_size：默认 16MB 约支持 156GiB，需要更大时调大 multipart_size（如 32M 约支持 312GiB）。以写为主，总缓存 10GiB、后台任务线程 128、单 part 32M、内存回收周期 3 秒：
Plain Text
1-o memory_limit=10240MB -o multi_thread=128 -o mem_gc_interval=3 -o multipart_size=32M多线程并发读写大量小文件
设置 FUSE 工作线程 64、meta 过期 60 秒：
Plain Text
1-o max_threads=64 -o meta_expires=60需要支持小文件随机写
最大支持配置为总内存的一半。随机写过程中无法释放内存，除非能保证同时只写一个文件，否则不建议放太大以免资源占用死锁；用完应立即 close 把数据写回后端。示例：使用空闲内存 80%，单个随机写文件最大 1GiB：
Plain Text
1-o memory_limit=-1 -o max_mem_file_size=1024MB评价此篇文章