US3FS是一个在Linux/Windows系统环境中，将S3的存储空间（Bucket）挂载到本地挂载点的工具，挂载成功后，您可以像操作本地文件一样操作存储空间（Bucket）中的文件。

软件版本：

linux: v2.0.2

windows: v1.6.8

运行环境：

Linux：
Ubuntu 16.04 及以上 (可通过cat /etc/issue查看)

CentOS 7.0 及以上 (可通过cat /etc/redhat-release查看)

Windows：

开启WinFsp服务

主要功能

支持POSIX文件系统的大部分功能，如读；顺序写；权限；UID/GID。

使用US3的分片上传功能上传大文件。
支持Etag和MD5校验，保证数据一致性。

使用限制
不支持随机写/追加写
rename非原子操作
不支持硬/软链接
多个客户端挂载同一个US3 Bucket时，需要用户自行维护数据一致性。

不支持读取归档类型的文件

---

运行环境

US3FS基于Linux下fuse和Windows平台下winfsp实现，您的机器需要支持fuse或winfsp。

建议您将US3FS运行在以下环境中：

Linux：

ceontos 7.0及以上 (可通过cat /etc/redhat-release查看)

ubuntu 16.04及以上 (可通过cat /etc/issue查看)

Windows：

下载WinFsp Installer

根据官方说明 进行安装

下载链接

Linux下载链接 或

curl -o us3fs https://ufile-release.cn-bj.ufileos.com/us3fs/us3fs_2.0.2CopyErrorSuccess

Windows下载链接

配置账号访问信息

Linux

编辑/etc/us3fs/us3fs.yaml并增加如下信息（如果没有该目录需要自行创建）：

access_key: ************************************secret_key: ************************************endpoint: ufile.cn-north-02.ucloud.cnhosts: []CopyErrorSuccess

冒号后有单个空格

access_key: 公钥，支持token秘钥和api秘钥两种模式，要有覆盖上传权限

secret_key: 私钥，支持token秘钥和api秘钥两种模式，要有覆盖上传权限

endpoint: 访问域名。填写域名为地域域名，并非具体的存储空间域名。

hosts: 指定访问点IP列表，不会走DNS解析逻辑获取US3接入层IP。如果指定个数小于3个不会生效。 如: hosts: [10.9.254.190, 117.50.123.23, 117.50.123.29, 117.50.123.8]

hosts指定的IP列表，在遇到异常(网络不可达)IP节点时会在5s检测周期内自动标记剔除，新的请求不受影响，但已经发起的请求且使用异常网络的链接，由于TCP采用退避指数重试算法，默认重试次数为15次，所以最坏情况要到15min左右才能检测异常，建议在使用该参数时，修改Linux参数net.ipv4.tcp.retries2(或修改系统文件/proc/sys/net/ipv4/tcp_retries2)为6，可使如网络不可达异常在25s左右能检测到，从而剔除已建立异常链接；此外由于目前链接保活探测逻辑会占用一定量的文件描述符，建议调整系统设置，请参考场景问题 中的系统日志出现too many open file问题项解决。

当需要在一台机器上挂载多个Bucket时，可以通过--passwd=passwd_file指定账号信息（默认路径为 /etc/us3fs/us3fs.yaml，不需要指定）。

下载US3FS后。使用chmod +x us3fs增加可执行权限，如果需要直接执行，可将us3fs移动到/bin目录下。示例：

chmod +x us3fs./us3fs --passwd=passwd_file <bucket> <mountpoint> # 移动到可执行目录下 mv us3fs /bin/us3fsus3fs --passwd=passwd_file <bucket> <mountpoint>CopyErrorSuccess

Windows

配置信息内同linux，配置路径自定义。

下载好可执行文件后移动到us3fs的工作目录(自定义)，然后通过按键windows+R打开运行窗口，输入cmd进入命令行工具界面(后续支持图形化界面)，进入可执行文件us3fs.exe 所在路径。示例:

# 进入可执行文件所在盘符，这里是D盘 C:\Users\Administrator> D: # 进入可执行文件所在路径 D:\>cd us3fsD:\us3fs>dir驱动器 D 中的卷没有标签。卷的序列号是 5CAF-F66B D:\us3fs 的目录 2021/09/09 21:16 <DIR> . 2021/09/09 21:16 <DIR> .. 2021/09/09 19:13 19,475,146 us3fs.exe 2021/08/26 11:29 157 us3fs.yaml 2 个文件 19,475,303 字节 2 个目录 213,768,716,288 可用字节 # 进行挂载操作 # * 这里挂载到x盘，并且指定uid,gid为0的用户，日志级别为debug，预读窗口为32MiB，挂载的US3桶名为rickwu D:\us3fs>us3fs.exe --passwd=us3fs.yaml -o debug --uid=0 --gid=0 --level=debug --readahead=32m <bucket> x:CopyErrorSuccess

注意目前Windows下挂载只能前台挂载

---

使用方式

挂载
us3fs [global options] <bucket> <mountpoint>CopyErrorSuccess

卸载
umount <mountpoint>CopyErrorSuccess

参数<bucket>和<mountpoint>必须依次作为最后两个参数，否则其他参数不能生效

windows 对cmd执行Ctrl+C

---

配置访问权限

us3fs挂载的默认访问权限为当前挂载用户，如果需要允许其他用户/用户组访问挂载点，可以使用如下参数:

-o allow_other：允许任何用户都可以访问文件。

--uid=xxx：指定默认的用户

--gid=xxx：指定默认的用户组

--mp_mask： 用来设置挂载点的权限掩码，只有当allow_other选项设置后，该选项才生效，默认值为0000。使用方式基本于umask命令一致；例如需要设置挂载点的权限为770，则使用参数 -o allow_other --mp_mask 0007；**注意root用户会忽略非root用户挂载时设置的mp_mask**。

可通过id命令获取用户的uid/gid信息，示例如下：

// 在ubuntu账户下挂载默认用户和用户组为www的us3fsubuntu:~$ id www uid=1001(www) gid=1001(www) groups=1001(www) ubuntu:~$ us3fs --uid=1001 --gid=1001 -o allow_other <bucket> <mountpoint>CopyErrorSuccess

mp_mask 配置示例如下：

挂载目录权限	mp_mask
rwxrwxrwx	0000
rwxrwx---	0007
rwx------	0077
rwxr--r--	0033
rwxrwxr--	0003
rwxr-xr-x	0022

如果挂载出现以下问题

stderr:/bin/fusermount: option allow_other only allowed if 'user_allow_other' is set in /etc/fuse.confCopyErrorSuccess

在/etc/fuse.conf中增加user_allow_other。

windows下只支持--uid和--gid

设置挂载只读

挂载时时指定-o ro。

windows下不支持

开启日志

--level=info/debug/error 开启指定级别的us3fs日志
--debug_fuse 开启用户态fuse日志
    centos 日志在/var/log/messages
    ubuntu 日志在/var/log/syslog
挂载时指定-f，us3fs会以前台模式挂载，日志会输出到屏幕上。

版本更新

执行如下命令：

us3fs --updateCopyErrorSuccess

更新后的可执行文件放在/bin/目录下

windows无效

---

使用帮助

通过us3fs -h查看us3fs支持的参数

Linux

us3fs - a single posix file system based on us3USAGE us3fs [global options] bucket mountpointVersion US3FS Version: v2.0.2 Commit ID: 223949d Build: 2024-01-24:10:32:50 Go Version: go1.17.13 linux/amd64FUSE -o value Specify fuse/winfsp option --entry_timeout value How long to cache dentry for inode for fuse. (default: 5m0s) --attr_timeout value How long to cache inode attr for fuse (default: 5m0s) --disable_async_read Disable all read (even read-ahead) operations asynchronously --wb Enable writeback mode, which is turned off by default --max_background value Specify the max_background parameter of fuse kernel(>=7.13), currently fuse usespace supports up to 1024 (default: 64) --congestion_threshold value Specify the congestion_threshold parameter of fuse kernel(>=7.13), currently fuse usespace supports up to 768 (default: 48) --async_dio Enable the async_dio parameter of fuse kernel, async_dio is disabled by default --keep_pagecache Turn on pagecache, when the file is opened, it will be decided whether to update according to the modification time of the inode, so please pay attention to the attr_timeout and dcache_timeout parameters will have a certain impact on thisOS --dcache_timeout value How long to cache dentry for us3fs (default: 5m0s) --retry value Number of times to retry a failed I/O (default: 5) --parallel value Number of parallel I/O thread (default: 32) --disable_remove Disable remove op, such as unlink, rmdir, rename --debug Set debug level for fuse/winfsp --level value Set log level: error/warn/info/debug (default: "info") --log_dir value Set log dir --log_max_age value Set log max age (default: 72h0m0s) --log_rotation_time value Set log rotation time (default: 1h0m0s) --enable_load_dentries enable auto init dentries in memory --cache_db value specify cache db path, e.g.: dbtype:dbpath --local_write write file to local and upload async --max_local_file_size value specify local file max size (default: "32m") --read_after_write_finish read operation will wait all write operation done --finish_write_when_release all written data will be uploaded when release --readahead value Readahead size. e.g.: 1m/1k/1 (default: "0") --max_cache_per_file value Max cache per file when enable readahead. e.g.: 32m/64m/128m (default: "1024m") --etag value Check etag for part. value is percent(0~100) (default: 50) --passwd value specify access file (default: "/etc/us3fs/us3fs.yaml") --enable_md5 Enalbe md5 in http header --uid value Specify default uid (default: 0) --gid value Specify default gid (default: 0) --mp_mask value Specify mountpoint mask (default: 0) --disable_check_vdir disable detection of virtual directories --update Update us3fs to /bin/us3fs -n Doesn't check access when mount us3fs -l Enable local cache for small file -p value Specify local cache location (default: "/tmp/us3fs/") --prefix value Specify bucket prefix path --open_rename Use rename api rather than copy and delete --gfl Enable get_file_list --direct_read Enable cache bypass read --perf_dump value How long to output the performance dump (default: 1h0m0s) --skip_ne_dir_lookup Skip non-essential directory checking, such as files ending in ".log",".png",".jpg", etc. --storage_class value Storage type, including "STANDARD", "IA" (default: "STANDARD") --enable_remote_cache --cache_dirs value specify cache db path, e.g.: /tmp/read-cache1,/tmp/read-cache2 --cache_size_limit value specify cache size limit, unit is GB (default: 4) --master_addr value master server addr --data_port value if data_port is specified, then other clients will connect it to get chunk data (default: 0) --page_size value (default: 1048576) --fuse_session_cnt value (default: 0) MISC --help, -h show help -f foregroundCopyErrorSuccess

Windows

us3fs - a single posix file system based on us3USAGE us3fs [global options] bucket mountpointVersion US3FS Version: v1.6.8 Commit ID: c87ec9c Build: 2022-08-17:11:01:05 Go Version: go1.16.3 linux/amd64WinFSP -o value Specify fuse/winfsp option --dir_info_timeout value The expiration time of the directory information, in seconds (default: 5) --file_info_timeout value File information expiration time, in seconds (default: 5) --volume_info_timeout value Volume information expiration time, in seconds (default: 5) --case_insensitive Is case sensitive --keep_filecache keep filecacheOS --dcache_timeout value How long to cache dentry for us3fs (default: 5m0s) --retry value Number of times to retry a failed I/O (default: 5) --parallel value Number of parallel I/O thread (default: 32) --debug Set debug level for fuse/winfsp --level value Set log level: error/warn/info/debug (default: "info") --readahead value Readahead size. e.g.: 1m/1k/1 (default: "0") --etag value Check etag for part. value is percent(0~100) (default: 50) --passwd value specify access file (default: "/etc/us3fs/us3fs.conf") --enable_md5 Enalbe md5 in http header --uid value Specify default uid (default: -1) --gid value Specify default gid (default: -1) --disable_check_vdir disable detection of virtual directories --update Update us3fs to /bin/us3fs -n Doesn't check access when mount us3fs -l Enable local cache for small file -p value Specify local cache location (default: "/tmp/us3fs/") --prefix value Specify bucket prefix path --gfl Enable get_file_list --direct_read Enable cache bypass read --perf_dump value How long to output the performance dump (default: 1h0m0s) --skip_ne_dir_lookup Skip non-essential directory checking, such as files ending in ".log",".png",".jpg", etc. --storage_class value Storage type, including "STANDARD", "IA" (default: "STANDARD") MISC --help, -h show help -f foregroundCopyErrorSuccess

Linux和Windows的参数区别主要体现在FUSE和WinFsp

配置文件对应终端参数

部分终端挂载参数支持配置在配置文件，配置文件的参数和终端参数的对应关系如下:

终端挂载参数名称	配置文件参数名称	配置文件样例
gfl	get_file_list	get_file_list: true
keep_pagecache	keep_pagecache	keep_pagecache: true
n	no_check	no_check: true
disable_check_vdir	disable_check_vdir	disable_check_vdir: true
async_dio	async_dio	async_dio: true
skip_ne_dir_lookup	skip_ne_dir_look	skip_ne_dir_look: true
l	enable_local	enable_local: true
wb	writeback	writeback: true
direct_read	direct_read	direct_read: true
enable_md5	enable_md5	enable_md5: true
debug	debug	debug: true
-o allow_other	allow_other	allow_other: true
enable_load_dentries	enable_load_dentries	enable_load_dentries:true
disable_async_read	disable_async_read	disable_async_read:true
retry	retry	retry: 66
parallel	parallel	parallel: 77
disable_remove	disable_remove	disable_remove: true
congestion_threshold	congestion_threshold	congestion_threshold: 88
max_background	max_background	max_background: 99
uid	uid	uid=100
gid	gid	gid :100
etag	etag	etag :100
dcache_timeout	dcache_timeout	dcache_timeout: 2h
entry_timeout	entry_timeout	entry_timeout: 3h
attr_timeout	attr_timeout	attr_timeout: 4h
perf_dump	perf_dump	attr_timeout: 5h
log_max_age	log_max_age	log_max_age: 6h
log_dir	log_dir	log_dir:/a/b/c
prefix	prefix	prefix: /a/b/c
level	level	level: debug
storage_class	storage_class	storage_class: STANDARD
p	local_path	local_path:/a/b/c
readahead	readahead	readahead: 8m
max_cache_per_file	max_cache_per_file	max_cache_per_file: 1024m
cache_db	cache_db	cache_db: leveldb:/data/us3fs_cachedb
local_write	local_write	local_write: true
max_local_file_size	max_local_file_size	max_local_file_size: 32M
finish_write_when_release	finish_write_when_release	finish_write_when_release: true
read_after_write_finish	read_after_write_finish	read_after_write_finish: true
enable_remote_cache	enable_remote_cache	enable_remote_cache: true
cache_dirs	cache_dirs	cache_dirs: /mnt/nvme01,/mnt/nvme02
cache_size_limit	cache_size_limit	cache_size_limit: 100
master_addr	master_addr	master_addr: :
data_port	data_port	data_port: 3333
page_size	page_size	page_size: 8388608
fuse_session_cnt	fuse_session_cnt	fuse_session_cnt: 4

挂载参数配置在配置文件样例 编辑/etc/us3fs/us3fs.yaml（如果没有该目录需要自行创建）依据具体需求将挂载参数写在配置文件，简化挂载命令

access_key: ************************************secret_key: ************************************endpoint: ufile.cn-north-02.ucloud.cnhosts: []CopyErrorSuccess

选项列表

WinFsp

FUSE

选项名称	描述
o	FUSE支持的option参数
entry_timeout	指定fuse缓存被查找的文件名的时间 默认为5min
attr_timeout	指定fuse缓存文件/目录属性的时间 默认为5min
disable_async_read	关闭fuse kernel预读使用异步模式。默认开启
wb	指定写入使用writeback方式。不支持覆盖写/追加写
max_background	指定fuse kernel的max_background参数(fuse kernel版本>=7.13)， 目前fuse usespace最多支持1024(默认：64)，该参数能提升direct io的并行度
congestion_threshold	指定fuse kernel(fuse kernel版本>=7.13)的congestion_threshold参 数，目前fuse usespace最多支持768（默认：48），该参数会触发并行IO的拥塞控制
async_dio	开启fuse内核的async_dio参数，默认关闭async_dio。该参数开启后， fuse kernel对direct io进行异步处理
keep_pagecache	开启pagecache，文件打开时会根据inode的修改时间以及大小变化决 定是否更新，所以请注意entry_timeout和dcache_timeout参数对此会 有一定影响，使得未能及时感知到文件修改时间、大小变化

fuse常用选项列表（与-o一起使用）

使用方式

-o option=valueCopyErrorSuccess

OS(Object Storage)

MISC

windows下-f参数无效

使用示例

• entry_timeout, attr_timeout, dcache_timeout:

设置dcache_timeout可增加文件/目录属性在内存中的有效时间，增强使用体验。建议entry_timeout , attr_timeout设置时间小于dcache_timeout

注：开启缓存后，可能造成用户读取目录的内容和实际bucket中的内容不一致。默认为开启，需要关闭请设置为0s

示例：ls包含10000个文件的目录耗时

[root@10-9-120-211 ~]# us3fs --dcache_timeout=60s --entry_timeout=60s --attr_timeout=60s <your_bucket> <mountpoint> [root@10-9-120-211 ~]# time ls -la <your_dir> | wc -l10003real 0m5.964suser 0m0.033ssys 0m0.232s[root@10-9-120-211 ~]#[root@10-9-120-211 ~]#[root@10-9-120-211 ~]# time ls -la <your_dir> | wc -l10003real 0m0.872suser 0m0.029ssys 0m0.133sCopyErrorSuccess

disable_async_read

默认读取模式为异步，同步读取性能较差。

示例如下：

[root@10-9-120-211 ~]# us3fs --disable_async_read <your_bucket> <mountpoint> [root@10-9-120-211 ~]# dd if=<your_file> of=/dev/null bs=4M count=1010+0 records in10+0 records out41943040 bytes (42 MB, 40 MiB) copied, 10.2345 s, 4.1 MB/s[root@10-9-120-211 ~]# us3fs <your_bucket> <mountpoint> [root@10-9-120-211 ~]# dd if=<your_file> of=/dev/null bs=4M count=1010+0 records in10+0 records out41943040 bytes (42 MB, 40 MiB) copied, 0.685801 s, 61.2 MB/sCopyErrorSuccess

parallel

增大并发数可提升读写性能，相应的也行增加系统资源占用。

示例如下:

// 默认并发数20[root@10-9-120-211 ~]# us3fs <your_bucket> <mountpoint> [root@10-9-120-211 ~]# dd if=/dev/zero of=<your_file> bs=4M count=10241024+0 records in1024+0 records out4294967296 bytes (4.3 GB, 4.0 GiB) copied, 25.5351 s, 168 MB/s// 调整并发数为32[root@10-9-120-211 ~]# us3fs --parallel=32 <your_bucket> <mountpoint> [root@10-9-120-211 ~]# dd if=/dev/zero of=<your_file> bs=4M count=10241024+0 records in1024+0 records out4294967296 bytes (4.3 GB, 4.0 GiB) copied, 18.3614 s, 234 MB/sCopyErrorSuccess

readahead

调整预读窗口大小对大文件的顺序读有较大影响，建议在16m~32m，但会增加内存消耗，可以适当缩小预读窗口。

示例如下：

// 默认预读大小16MB [root@10-9-120-211 ~]# dd if=<your_file> of=/dev/null bs=4M count=1024 1024+0 records in 1024+0 records out 4294967296 bytes (4.3 GB, 4.0 GiB) copied, 60.0498 s, 71.5 MB/s// 调整预读大小为32MB [root@10-9-120-211 ~]# us3fs --readahead=32m <your_bucket> <mountpoint> [root@10-9-120-211 ~]# dd if=<your_file> of=/dev/null bs=4M count=1024 1024+0 records in 1024+0 records out 4294967296 bytes (4.3 GB, 4.0 GiB) copied, 37.6013 s, 114 MB/sCopyErrorSuccess

场景化参数设置

性能相关参数

parallel：设置并发线程，对cpu负载有一定影响。建议设置在20~40较为合理
critical：写入文件时启用本地etag校验，相比未开启会提高约50%的cpu占用。

readahead：预读窗口大小，由于fuse自身有读写窗口的限制，一定的预读大小对读取性能有显著提升。建议设置在16m~32m，但会增加内存消耗，可以适当缩小预读窗口。

keep_pagecache: 尽可能缓存数据内容在vfs pagecache中，直到文件的修改时间和大小发生变化，才无效掉pagecache中的历史数据。

wb: 该参数会使得写入的IO会尽量在pagecache中合并，然后以大IO(默认128K)发送到us3fs。

fuse_session_cnt: 设置与内核fuse模块通信的连接数，对cpu和内存负载有一定影响，建议在资源空闲的机器上可开启，并将数量设置在CPU核数以内，开启后读写性能都有一定程度的提升

小文件场景

对于大量小文件场景，如果对性能有要求，可指定-l开启本地本地缓存。当启用本地缓存后，us3fs挂载后首先会将指定缓存目录下已存在的所有小于等于4MB的文件按照其路径上传到bucket中。当写入文件大小不大于4MB，文件会尝试写入本地缓存目录，写入成功后即返回，后端异步上传到us3。写入失败（如权限不足，空间不足等）则仍然使用同步方式写入us3对象存储

注：异步上传可能出现写入后端失败,us3fs会一直重试直到写入成功。

高读吞吐场景

cache_dirs: 设置本地读缓存磁盘，推荐使用本地nvme盘来存放读缓存内容，可设置多个盘，使用 , 号分割，注意缓存盘尽量不要使用系统盘，避免由于瞬间的IO上涨导致系统hang住，推荐使用独立的本地nvme盘（盘的读写吞吐能在2GB+）。

cache_size_limit: 设置缓存盘存储量使用上限，当缓存的内容达到该上限时，会进行LRU淘汰

page_size: 在开启本地读缓存功能时，需要将page_size从默认的1048576调整到8388608

共享读缓存

当多个挂载点之间需要共享读缓存内容时，可以通过执行

us3fs run-master --listen_addr 192.168.0.10:6667CopyErrorSuccess

命令来启动一个master节点运行，同时将其余的挂载点的 master_addr 参数设置为 192.168.0.10:6667, 这样各个挂载点会同该master定期保持心跳，这一组挂载点将会成为一个小型的读缓存集群

     enable_remote_cache: 当一个挂载点开启该参数后，其余的挂载点就可能会连接上它检查是否有缓存数据可读，当发现目标数据存在时，会尝试从该挂载点读取数据内容

     data_port: 当一个挂载点开启enable_remote_cache后，暴露在哪个端口对外进行访问

自动挂载

推荐的最佳实践方案是采用systemctl来保证服务异常退出，或者机器重启后能重新挂载us3fs，但需要注意Linux(Windows平台暂未提供方案)的发行版本是否支持systemctl：

Ubuntu >= 15.04

Centos、RHEL >= 7

满足系统要求后，经过如下几个简单步骤即可：

1.设置配置

在/etc/systemd/system/目录下创建名为us3fs.service的文件，并增加如下内容

[Unit]Description=US3FS (User Space FileSystem for US3)Requires=network-online.targetAfter=network-online.target[Service]Type=forkingUser=<user> Group=<group> Restart=alwaysRestartSec=10ExecStart=/bin/us3fs --passwd=/etc/us3fs/us3fs.conf --keep_pagecache <your_bucket> <mountpoint> ExecStop=/bin/umount <monutpoint> [Install]WantedBy=multi-user.targetCopyErrorSuccess

User为需要访问挂载点的用户。如root。

Group为需要访问挂载点的用户组。如root。

ExecStart为挂载命令，按照需要自行填写

执行systemctl daemon-reload配置则会生效。

服务启用或停止

执行systemctl start us3fs.service启动服务；

执行systemctl stop us3fs.service停止服务；

执行systemctl restart us3fs.service重启服务；

执行systemctl status us3fs.service查看服务状态;

设置为开机自启动

执行systemctl enable us3fs.service；