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：
根據官方說明 進行安裝
下載鏈接
curl -o us3fs https://ufile-release.cn-bj.ufileos.com/us3fs/us3fs_2.0.2CopyErrorSuccess配置賬號訪問信息
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>CopyErrorSuccessWindows
配置信息內同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>CopyErrorSuccessmp_mask 配置示例如下：
| 掛載目錄權限 | mp_mask |
|---|---|
| rwxrwxrwx | 0000 |
| rwxrwx--- | 0007 |
| rwx------ | 0077 |
| rwxr--r-- | 0033 |
| rwxrwxr-- | 0003 |
| rwxr-xr-x | 0022 |
如果掛載出現以下問題
在/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支持的參數
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（如果沒有該目錄需要自行創建）依據具體需求將掛載參數寫在配置文件，簡化掛載命令
| 選項名稱 | 描述 |
|---|---|
| o | WinFsp支持的option參數 |
| dir_info_timeout | 目錄緩存的超時時間，默認5s |
| file_info_timeout | 文件緩存的超時時間，默認5s |
| volume_info_timeout | 卷信息的超時時間，默認5s |
| keep_filecache | 是否把文件放入緩存 |
| 選項名稱 | 描述 |
|---|---|
| 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一起使用）
| 選項名稱 | 描述 |
|---|---|
| allow_other | 指定文件系統可以所有用戶訪問 默認關閉 |
| ro | 指定當前文件系統為只讀 |
使用方式
-o option=valueCopyErrorSuccess| 選項名稱 | 描述 |
|---|---|
| dcache_timeout | dentry cache在us3fs中的緩存時長 默認為5min |
| retry | 請求失敗后重試次數，默認5次 |
| parallel | I/O并發線程數 默認20個 |
| debug | 指定用戶態fuse日志級別為debuy 默認關閉 |
| level | 指定us3fs日志級別 默認為Info級別 |
| readahead | 預讀大小。 例如：1m/1k/1（默認：“0”） |
| etag | 檢查上傳數據的 etag所占百分比。 值是百分比（0~100）（默認值：50） |
| passwd | 指定賬戶文件，默認路徑/etc/us3fs/us3fs.yaml // windows 平臺自定義 |
| enable_md5 | 在http請求頭中增加md5校驗，默認關閉 |
| uid | 指定文件所屬的默認用戶，默認當前用戶 |
| gid | 指定文件所屬的默認用戶組，默認當前用戶組 |
| disable_check_vdir | 禁用虛擬目錄檢測 |
| update | 更新us3fs版本，新版本路徑為/bin/us3fs |
| n | 掛載時不檢查bucket權限，如果沒有所在地域沒有列表服務可開啟 |
| l | 開啟后對小文件使用本地目錄做緩存，異步上傳。具體使用示例見小文件場景 |
| p | 指定小文件異步上傳的本地緩存目錄 |
| prefix | 指定掛載的bucket前綴目錄，默認為空 |
| gfl | 對于沒有ListObjects API支持的Endpoint, 該參數可以繞過,通過PrefixFileList API模擬 |
| direct_read | 開啟后，繞過us3fs內部緩存組織模塊，直接讀取us3數據， 對于被頻繁訪問的文件會有一定性能降低，反之有利于降低時延 |
| perf_dump | 指定時間周期輸出時延統計信息，默認周期是1hour |
| skip_ne_dir_lookup | 跳過非必要的目錄檢查，目前過濾支持".jpe"、".jpeg"、".png"、 ".gz"、".tgz"、".gz"、".tgz"、".log"、".plot"、".js"、".html"、 ".css"、".apk"為后綴的文件，需要確保bucket下沒有用以上后綴 作為目錄后綴的情況 |
| storage_class | 指定寫入US3中文件的存儲類型，支持STANDARD(標準), IA(低頻)兩種。 (default: STANDARD) |
| cache_db | 指定本地存儲us3fs元數據cache的方式及路徑，格式為：leveldb:/data/us3fs_cachedb |
| finish_write_when_release | 開啟后，支持文件異步結束上傳，用于支持一個fd有多次flush的場景 |
| read_after_write_finish | 開啟后，讀取文件時，如果文件正在寫入，會等待文件寫入完成后才返回讀的內容 |
| local_write | 開啟后，寫入的數據會暫存到本地文件系統后再異步上傳到服務端 |
| max_local_file_size | 和 local_write搭配使用，指定能寫入到本地文件系統的最大文件大小（默認值：32M） |
| 選項名稱 | 描述 |
|---|---|
| help, h | 查看幫助 |
| f | 掛載時啟用前臺模式，相關輸出會打印到標準輸出 |
windows下-f參數無效
設置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/sCopyErrorSuccessparallel：設置并發線程，對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；
增值電信業務經營許可證：B1.B2-20140435 京B1.B2-20070152 域名注冊服務批文號：京信信管發〔2019〕94號 京ICP證000012號
京公網安備11030102000056號
京ICP備09061941號-4
Copyright©1993-2021 北京新網數碼信息技術有限公司 版權所有
商品已成功加入購物車
