Object Storage Service：ossfs 2.0掛載選項說明

分類

配置項

是否必填

說明

預設值

支援版本

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，需先執行 fusermount -u <掛載點> 卸載，再重新執行 ossfs2 mount 命令並指定新的 --gid 參數。重新掛載後，所有檔案（含已有檔案和建立檔案）均顯示新的 gid。

當前執行掛載使用者的gid

v2.0.1及以後

uid

否

配置後，掛載點下所有檔案和檔案夾uid屬性將變為配置值。uid 參數僅在掛載時生效，掛載後執行 chown、chmod 等命令會返回成功（exit code 0），但不會修改檔案的 uid 或許可權。如需修改 uid，需先執行 fusermount -u <掛載點> 卸載，再重新執行 ossfs2 mount 命令並指定新的 --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請求的HTTPProxy 伺服器地址。

空

v2.0.8 及以後

path_style

否

開啟後，支援配置使用PrivateLink網域名稱進行掛載。

false

v2.0.10 及以後

enable_ipv6

否

是否使用IPv6的地址訪問OSS。

true

v2.0.10 及以後

上傳配置

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的並發程度。

若不配置此選項，預設會使用prefetch_chunk_size * prefetch_chunks大小的記憶體作為資料讀取預取緩衝區，使用upload_buffer_size * upload_concurrency大小的記憶體作為資料寫入緩衝區，讀寫操作最大會分配約8 GB 記憶體。請確保您的裝置有足夠的記憶體資源，以避免潛在的OOM（記憶體不足）問題。

total_mem_limit的預設值對於運行機器記憶體小於等於16 GB的運行環境預設會配置為系統記憶體的一半，超過16 GB記憶體的不限制。

0

v2.0.0及以後

max_inode_cache_count

否

表示啟用主動控制中繼資料快取數量。

• 預設為0，表示不主動進行中繼資料數量控制，依賴作業系統自動淘汰中繼資料。

• 配置為正整數時，表示啟用中繼資料數量主動控制。當緩衝條目數超過設定值時，ossfs2.0 將按照一定的規則淘汰超出部分的條目。

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及以後