Object Storage Service：ossfs 2.0常見問題

掛載報錯ERROR: failed to mount ossfs2, see more details in log file

問題分析：該問題為通用報錯，具體資訊需要去日誌中查看對應報錯。常見錯誤主要是許可權或配置參數有誤導致的。例如：

2025/03/21 15:09:59.124152|ERROR|th=00007F1238FF5780|ossfs_v2.cpp:1469|Check bucket failed with err: AccessDenied

所使用的AccessKey（存取金鑰）不具有該Bucket的存取權限，請確認您的AccessKey（存取金鑰）是否具備存取權限，同時確保Bucket名稱配置正確。

2025/03/21 15:14:29.671470|ERROR|th=00007F2304FF5780|ossfs_v2.cpp:1469|Check bucket failed with err: InvalidAccessKeyId

您配置的AccessKey（存取金鑰）參數有誤。

2025/03/21 15:15:13.805814|ERROR|th=00007FD591D38780|ossfs_v2.cpp:1469|Check bucket failed with err: SignatureDoesNotMatch

解決方案：根據日誌中的對應報錯資訊，修改正確後重新掛載。

掛載報錯MOUNTPOINT: Directory does not exist: /mnt/ossfs2

問題分析：未建立該目錄導致。

解決方案：先建立對應的目錄，之後再進行掛載操作。

掛載報錯MOUNTPOINT: directory /mnt/ossfs2 is not empty.

問題分析：要掛載的目標檔案夾非空，ossfs 2.0要求掛載檔案夾必須為空白檔案夾。

解決方案：排查該檔案夾是否已經掛載其他檔案系統，若已經掛載其他檔案系統可以嘗試使用umount命令先卸載對應檔案系統，若未掛載其他檔案系統，請排查該檔案夾下是否有殘留檔案。也可以切換到其他空目錄進行掛載。

掛載報錯version `FUSE_3.12' not found

問題分析：安裝檔案缺失導致ossfs 2.0嘗試使用系統安裝的libfuse庫但版本過低。

解決方案：卸載對應的安裝包重新安裝。

掛載報錯fuse: device not found, try 'modeprobe fuse' first 或在日誌中看到 fuse_session_mount failed with error: No such file or directory

問題分析：無法訪問到/dev/fuse裝置，常見於容器環境下沒有對應的存取權限。

解決方案：若在容器環境中掛載，需要使用特權模式啟動對應容器。

寫入檔案報錯File too large

問題分析：ossfs 2.0預設配置part大小為8 MiB，最大支援78.125 GiB的檔案。當您寫入的檔案大小超過這個限制時會遇到該報錯。

解決方案：掛載Bucket時，通過配置upload_buffer_size選項來增加最大支援的檔案大小。請注意配置upload_buffer_size意味著需要更多的記憶體資源。ossfs 2.0支援配置total_mem_limit來控制記憶體使用量，具體請參見掛載選項說明。

寫入檔案報錯Invalid argument

問題分析：ossfs 2.0不支援對檔案進行隨機位置寫入，僅支援順序地往檔案的末尾追加寫入，若寫入的位置非檔案當前末尾的位置會報錯Invalid argument。日誌報錯資訊如下：

2025/04/14 11:00:39.307250|INFO |th=00007FEB88011870|fs.cpp:877|open file /fio/random-write-file.0.0
  nodeid: 5, flags: 32770, read_only: 0, truncate: 0, append: 0
2025/04/14 11:00:39.307551|ERROR|th=00007FEB88011DB0|file.cpp:294|append only file size: 0, offset: 63963136, write_off_: 0

解決方案：若您的業務對隨機寫入為強需求時，需要切換到ossfs 1.0以支援隨機寫入。通常情況下，您的隨機寫入可能來自於同一個檔案控制代碼的並發寫入，若是這類情況，ossfs 2.0已經針對順序寫入進行了效能最佳化，單線程已經具有比較好的吞吐效能，可以切換到單線程順序寫入解決該問題。

在掛載點下運行git clone運行失敗（讀取檔案報錯非預期的No such file or directory）

問題分析：ossfs 2.0預設不支援對同一個檔案同時進行寫入和讀取，對正在寫入的檔案進行讀取操作可能讀到舊的資料或讀取報錯。git clone命令存在邊寫邊讀的訪問模式，您可以在日誌中找到如下報錯資訊：

2025/03/21 14:50:52.412572|ERROR|th=00007FE970FF4940|file.cpp:1385|src file /libfuse/.git/objects/pack/tmp_pack_PFRsQf read failed, read : -1, expectRead : 1048576, size_ : 4556308, offset : 0, errno: 2

其中errno 2為Linux錯誤碼ENOENT，說明這個檔案的資料沒有被正確讀取到。如果您遇到其他應用讀取報錯，可以先查看日誌中是否有類似報錯資訊。在讀取資料時無法返迴文件不存在，則有可能是應用寫入的檔案還沒有關閉導致檔案沒有上傳到OSS中所導致。

解決方案：避免使用相關命令，可以git clone到本地磁碟上再使用cp命令拷貝到掛載點中。

並發寫入同一個檔案寫入報錯Device or resource busy

問題分析：ossfs 2.0某個檔案同一時間被多次開啟時，僅有一個檔案控制代碼支援順序寫入，後續的其他檔案控制代碼寫入會報錯。報錯資訊如下：

2025/03/21 14:59:22.765822|ERROR|th=00007FE990006990|file.cpp:231|file 181 has already been written!

解決方案：避免並發寫入同一個檔案，ossfs 2.0針對順序寫入進行了效能最佳化，單線程已經具有比較好的吞吐效能。

卸載時報錯umount: /mnt/ossfs2: target is busy.

問題分析：有進程正在訪問掛載目錄/mnt/ossfs2下的檔案，所以無法卸載。

解決方案：

1. 使用lsof /mnt/ossfs2找出訪問該目錄的進程。

2. 停止該進程訪問。

3. 重新卸載。

使用ossfs 2.0時出現大量404日誌

背景資訊：在使用 ossfs 2.0 的過程中，日誌中出現的 404 Not Found 記錄是常見現象。大多數情況下這並非系統錯誤，而是 ossfs 2.0為類比本地檔案系統語義所採取的正常互動行為。

在操作檔案前，作業系統會主動檢查目標對象是否存在。該過程可能導致向 OSS 發起大量探測請求，其中“對象不存在”的響應即返回404狀態代碼。

ossfs 2.0檢查對象存在性的完整流程如下：

1. 發送 GetObjectMeta 請求查詢指定路徑（如 object）是否作為實際對象存在。

   如果對象存在，則系統直接返迴文件元資訊；如果對象不存在，則系統返回404並繼續執行下一步。

   說明

   即使對象不存在，ossfs 2.0仍需判斷該路徑是否代表“目錄”。

2. 收到404後，發送 ListObjects 請求判斷指定路徑是否為“目錄”，即查詢以 object/為首碼的對象。

   如果返回結果為空白，則最終判定路徑不存在；如果返回結果非空，則表示目錄存在，系統列出目錄內容。

問題分析：

• 使用 stat 等命令訪問不存在的檔案時，系統返回 404並映射為本地檔案系統的 No such file or directory 錯誤。

• 大量建立檔案或目錄前，作業系統會先檢查目標檔案是否存在，檔案不存在時才發送建立請求。檢查過程中產生的404錯誤屬於預期行為，非系統異常。

解決方案：雖然 404 屬於正常行為，但在高並發或大量操作情境下，頻繁的探測請求會影響效能，可通過以下配置進行最佳化：

1. 通過調大--attr_timeout延長中繼資料快取時間（預設60s）。

   在中繼資料失效前查詢檔案或目錄，可避免重複發起OSS請求。

2. 通過配置--oss_negative_cache_size和--oss_negative_cache_timeout啟用負緩衝（Negative Cache）。

   首次查詢檔案不存在時，將結果緩衝在記憶體中。後續在緩衝失效前查詢檔案時，直接查詢本地負緩衝而不發送OSS請求。

   • --oss_negative_cache_size：OSS檔案負緩衝的條目數量，預設為10000。

   • --oss_negative_cache_timeout：OSS檔案負緩衝的失效時間，預設為0。