ossfs 2.0 本地臨時目錄隨機寫入配置與原理 - Object Storage Service

ossfs 2.0.9 及以後版本支援基於本地臨時目錄的隨機寫入。通過配置 --temp_dir 掛載選項，ossfs 2.0 在本地磁碟為寫入資料建立暫存（staging）區，使掛載點具備任意位移寫入、任意大小截斷、邊寫邊讀等完整 POSIX 隨機寫語義。本文介紹隨機寫入的工作原理、配置方法、使用約束與使用建議。

背景資訊

OSS Object Storage Service中的對象一旦建立，就不能只修改其中的一部分，任何內容變更都只能整體覆蓋重寫。ossfs 2.0 預設模式下的寫入路徑採用流式上傳：資料在寫入過程中按順序分區上傳到 OSS，存在以下限制：

僅支援順序寫，檔案結尾之外位置的 pwrite 不支援；
truncate 僅支援截斷到 0，截斷到任意非零大小返回 ENOTSUP；
檔案寫入期間（未 close）不允許讀取，返回 EBUSY。

AI Agent 代碼執行、指令碼就地編輯、科學計算中間結果等情境普遍依賴隨機寫語義。ossfs 2.0 的隨機寫入功能通過本地臨時目錄暫存寫入的資料，配合分塊（chunk）管理與增量上傳，在Object Storage Service之上實現了隨機寫入。

ossfs 2.0 隨機寫入模式具備以下特點：

完整 POSIX 隨機寫語義：支援任意位移 pwrite、O_APPEND、任意大小 truncate（擴大/縮小）。
邊寫邊讀：檔案寫入期間可同時讀取，已修改部分從本地暫存讀取，未修改部分直接從 OSS 讀取。
增量上傳：flush/close 時僅上傳被修改的資料區塊，未修改部分通過 OSS 服務端拷貝（Copy）完成，零本地 IO、零上傳頻寬消耗。
磁碟空間保護：內建全域磁碟預算，暫存檔空間不足時寫入返回 ENOSPC，掛載時可預留空閑空間閾值，避免佔滿系統硬碟。

說明

本地臨時目錄僅服務於寫路徑，與本機資料緩衝（--disk_data_cache_dir，讀緩衝）相互獨立，二者可同時開啟（需配置不同目錄）、互不影響。

ossfs 1.0 預設使用 /tmp 目錄作為本地臨時目錄。若希望與 ossfs 1.0 的預設路徑保持一致，可配置 --temp_dir=/tmp。

重要

開啟隨機寫入後，寫入效能將受限於本地臨時目錄所在磁碟的讀寫效能；在拷貝大檔案等大批量順序寫入情境下，效能遠不及預設模式。請僅在業務確實需要隨機寫入語義時才開啟該功能。

工作原理

本地暫存與合并上傳

開啟隨機寫入後，ossfs 2.0 會為每個被隨機寫的檔案在本地臨時目錄中建立一個暫存檔案，按固定資料區塊（chunk）粒度在本地儲存最新的修改：

寫入的資料直接落在本地暫存檔案中；若寫入只覆蓋了雲端已有資料區塊的一部分，會先從 OSS 拉取該資料區塊，保證本地暫存的資料完整。
在 fsync 或 close 時，本地暫存的修改自動與雲上資料合併上傳：被修改的部分從本地上傳，未修改的部分通過 OSS 服務端拷貝（Copy）完成，無需整檔案重傳，也不消耗本地磁碟讀取頻寬。
上傳成功後自動釋放暫存磁碟空間。

邊寫邊讀

檔案處於寫入狀態時同樣允許讀取：已修改的部分從本地暫存讀取，未修改的部分直接從 OSS 讀取。

磁碟空間保護

掛載時校正臨時目錄所在磁碟的空閑空間是否滿足預留要求，不滿足則拒絕掛載。磁碟預留空間不足時寫入返回 ENOSPC，進程不會因寫滿磁碟而異常。

配置方法

配置項	是否必填	說明	預設值
temp_dir	否	本地臨時目錄路徑，需為絕對路徑。配置為非空時啟用隨機寫入；為空白則關閉該功能。	空
temp_dir_free_bytes	否	為臨時目錄所在磁碟預留的最小空閑空間（位元組，支援 K/M/G 等單位）。ossfs2 不會使用這部分空間存放暫存資料：當磁碟剩餘空閑空間低於該閾值時，新的寫入將返回 ENOSPC，從而為同盤的其他業務留出安全水位；掛載時若磁碟空閑空間已低於該值，掛載直接失敗。最小 64 MiB。	1 GiB
random_write_max_file_size	否	隨機寫入模式下單個檔案的邏輯大小上限（位元組，支援 K/M/G 等單位）。超過該限制的寫入 / 截斷返回 EFBIG。物理上限為 OSS 分區上傳容量（10000 分區 × 5 GiB，約 48.8 TiB）。	100 GiB

約束：

--temp_dir 指向的目錄不存在時會自動建立；建議使用獨立分區 / 獨立盤，避免與系統硬碟或其他業務爭搶空間。
寫入中的檔案資料儲存在本地臨時目錄中，若磁碟空間無法容納，寫入將返回 ENOSPC。將磁碟剩餘空閑空間減去 temp_dir_free_bytes 預留的空閑空間後的部分稱為磁碟可寫入空間，ossfs2 只會使用這部分空間存放寫入中的資料；磁碟可寫入空間需大於同時在寫入的檔案總大小（最壞情況下整個檔案都會寫入本地）。
同一台機器上掛載多個 ossfs2 執行個體時允許共用同一臨時目錄（暫存檔案命名互不衝突），但多執行個體會爭搶同一磁碟的空間與 IO，建議使用獨立目錄。
--temp_dir 與 --enable_appendable_object 互斥，不可同時開啟。

掛載命令樣本：

ossfs2 mount /mnt/oss/ \
  --oss_bucket <your-bucket> \
  --oss_endpoint <your-endpoint> \
  --oss_access_key_id <ak> \
  --oss_access_key_secret <sk> \
  --temp_dir /mnt/disk/ossfs2/temp \
  --temp_dir_free_bytes 1G

環境要求

參數	要求
臨時目錄磁碟類型	推薦彈性臨時盤 / 本地 NVMe / ESSD；磁碟寫吞吐直接影響隨機寫延遲與上傳速度
磁碟可用空間	不小於 `temp_dir_free_bytes`，且磁碟可寫入空間（見上文使用約束）需能容納同時在寫入的檔案資料

功能效果

開啟 --temp_dir 前後寫入能力對比：

操作	預設模式	隨機寫入模式
順序追加寫	支援	支援
任意位移 pwrite（檔案結尾之外的位置）	不支援	支援
truncate 到 0	支援	支援
truncate 到任意大小（擴大 / 縮小）	不支援（ENOTSUP）	支援
O_APPEND 追加寫已有檔案	支援	支援
寫入期間讀取同一檔案	不支援（EBUSY）	支援
多控制代碼同時寫同一檔案	不支援	支援

持久化語義：

隨機寫入模式預設遵守 fsync 語義：fsync 會觸發本地修改與雲上資料的合并上傳，返回成功即表示資料已持久化到 OSS；檔案 close 時同樣會上傳剩餘資料。
上傳失敗會嚮應用返回錯誤，應用可通過 fsync 重試；若最終未成功且檔案被 close，未持久化資料丟失，檔案內容回退到遠端最後一次成功上傳的版本。
進程異常退出時，未上傳的暫存資料丟失，OSS 上的對象保持最後一次成功上傳的狀態，不會產生損壞的對象。

使用建議

本地臨時目錄隨機寫入適用於需要在 OSS 掛載點上執行類本地檔案系統寫語義的情境。

適合開啟隨機寫入的情境：

情境	使用建議
AI Agent 代碼執行 / 沙箱環境（Agent 與代碼解譯器對檔案做任意位置讀寫、就地編輯）	開啟隨機寫入；臨時目錄建議使用獨立高效能磁碟，磁碟可寫入空間按同時在寫入的檔案總大小預留。
科學計算 / 模擬類應用的中間結果檔案	開啟隨機寫入；磁碟可寫入空間按同時在寫入的檔案總大小規劃。

不建議開啟隨機寫入的情境：

情境	使用建議
大檔案拷貝（cp、rsync 等批量寫入掛載點）	該情境下寫入效能受限於本地磁碟，遠不及預設模式，請使用預設的流式上傳模式。
純順序追加寫（日誌流式寫入）	預設流式上傳路徑開銷更低，無需開啟隨機寫入；如需邊寫邊讀可選 `--enable_appendable_object`。

磁碟預算配置建議：

臨時目錄與系統硬碟分離，避免暫存資料撐滿系統硬碟影響主機穩定性；若機器只有一塊磁碟，建議將 temp_dir_free_bytes 配置為較大的值（例如 10G），為系統預留充足的空閑空間。
磁碟可寫入空間（見上文使用約束）需大於同時在寫入的檔案總大小。
單檔案超過 100 GiB 時，除顯式調大 --random_write_max_file_size（例如 --random_write_max_file_size=500G）外，還需確保磁碟可寫入空間超過該檔案大小。