Cloud Storage FUSE CLI 參考資料

Cloud Storage FUSE 指令列介面 (CLI) 或 gcsfuse CLI 可讓您將 Cloud Storage bucket 掛接為本機電腦上的檔案系統。本文說明可用來與 Cloud Storage FUSE 互動的 gcsfuse 指令選項。

如果您使用 Cloud Storage FUSE CSI 驅動程式，將 bucket 掛接至 Google Kubernetes Engine 中的本機檔案系統，請參閱「Cloud Storage FUSE CSI 驅動程式的掛接選項」。

gcsfuse CLI 指令結構

以下範例顯示 gcsfuse 指令的結構，包括必要指令和選用的 gcsfuse 選項。

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

更改下列內容：

  • GLOBAL_OPTIONS 是gcsfuse選項，可控制掛接設定和 Cloud Storage FUSE 行為。

  • BUCKET_NAME 是要掛接的值區名稱。例如，my-mount-bucket。選用。請勿在這個指令中加入 bucket 名稱，以便執行動態掛接。

  • MOUNT_POINT 是要掛接 bucket 的本機目錄。例如：/path/to/mount/point。

gcsfuse CLI 選項

gcsfuse選項 說明 有效值 預設值
停用要求驗證。如果您使用的自訂端點不支援驗證，請設定這個選項。如果您搭配公開 bucket 使用 Cloud Storage FUSE，也應設定這個選項。 布林值：true、false。 false
掛接點的應用程式名稱。 字串值，例如：my-bucket-mount。 ""
指定存取掛接 bucket 時，要用於計費的專案。如要掛接已啟用要求者付費功能的值區，通常需要這個選項。 代表專案 ID 的字串值。 ""

啟用檔案快取，並指定儲存檔案快取資料的目錄。

 路徑，例如：/tmp/gcsfuse-cache-path。如果值為空白，表示這個選項已停用。系統預設會停用這個 gcsfuse 選項。 ""
指定與 Cloud Storage 後端通訊時使用的通訊協定。 http1

以指定間隔將指標匯出至 Cloud Monitoring。

 代表值的整數 (以秒為單位)，例如：10 (10 秒)。0 指定不匯出。 0
指定設定檔的路徑，用於設定 Cloud Storage FUSE 行為。 路徑，例如：/etc/gcsfuse.yaml。 ""
指定擷取資料的替代自訂端點。 自訂端點必須支援與 Cloud Storage gRPC 端點 storage.googleapis.com:443 或 Cloud Storage JSON 端點 https://storage.googleapis.com/storage/v1 相同的資源和作業。如未指定自訂端點，Cloud Storage FUSE 會使用全域 Cloud Storage JSON 端點。如果您指定的自訂端點不支援驗證，請將 --anonymous-access gcsfuse 選項設為 true，略過驗證。 端點，例如：storage.googleapis.com:443。 ""
啟用 FUSE 相關偵錯輸出。這個選項已由 --log-severity gcsfuse 選項取代。如要啟用偵錯輸出，請將 --log-severity gcsfuse 選項設為 trace，其中包含追蹤、偵錯、資訊、警告和錯誤記錄。 布林值：true、false。 false
列印 Cloud Storage 要求和時間資訊。這個 gcsfuse 選項已由 --log-severity gcsfuse 選項取代。如要啟用偵錯輸出，請將 --log-severity gcsfuse 選項設為 trace，其中包含追蹤、偵錯、資訊、警告和錯誤記錄。 布林值：true、false。 false
偵測到內部不變量違規時，結束程式。 布林值：true、false。 false
在 mutex 保留時間過長時，列印偵錯訊息。如果指定這個 gcsfuse 選項，記錄的嚴重性等級會自動設為 trace，包括追蹤、偵錯、資訊、警告和錯誤記錄。 布林值：true、false。 false
目錄的權限位元，以八進位表示。 字串值，代表介於 "000" 和 "777" (含) 之間的八進位整數，例如："755"。 755
指定將 Cloud Storage 物件的部分內容非同步預先擷取至記憶體內緩衝區，以便後續讀取作業從緩衝區提供，而不需網路呼叫。 布林值：true、false false
如果 Cloud Storage 中找不到檔案，則建立類型為 NonexistentType 的類型快取項目。如果檔案是在 Cloud Storage 中建立，但檔案的 NonexistentType 項目已快取，則 Cloud Storage FUSE 無法要求該檔案，直到 NonexistentType 項目從類型快取中移除為止。 布林值：true、false。 false
控制寫入路徑流程，讓資料在寫入時直接上傳至 Cloud Storage，而不是在本機完整暫存寫入，並在 close() 或 fsync() 時上傳。如要進一步瞭解串流寫入，請參閱 Cloud Storage FUSE GitHub 說明文件中的 Cloud Storage FUSE 語意。 布林值：true、false。 true

指定檔案快取可使用的 MiB 大小上限，並限制檔案快取在掛接目錄中可使用的總容量。
  • 整數
  • -1：指定在 cache-dir 指定的目錄中，使用快取的所有可用容量。只有在傳遞 cache-dir 時，這才是預設值。
  • 0：停用檔案快取。
 -1
決定是否要在從非零偏移量完成第一次讀取時，以非同步方式下載完整物件，並儲存在 Cloud Storage FUSE 快取目錄中。如果您打算執行多項隨機讀取或部分讀取作業，請將這個 gcsfuse 選項設為 true。 布林值：true、false。 false
指定每個 goroutine 將物件下載至檔案快取時，向 Cloud Storage 發出的每個讀取要求大小 (以 MiB 為單位)。 整數 200

將檔案快取目錄做為預先擷取緩衝區，並使用多個 worker 同時下載檔案的多個部分，加快大型檔案的讀取速度。

啟用檔案快取功能時，系統會自動啟用平行下載功能。 如要進一步瞭解檔案快取，請參閱「Cloud Storage FUSE 中的檔案快取」。

如要進一步瞭解平行下載，以及如何設定支援屬性，請參閱「平行下載」。

 布林值：true、false。 true
規則運算式，指定要從快取中排除的檔案。 如果檔案符合這個規則運算式，即使也符合 --file-cache-include-regex，也不會快取。規則運算式會與 bucket_name/object_key 格式的檔案路徑進行比對。詳情請參閱「使用規則運算式控制檔案層級的可快取性」。 代表規則運算式的字串值。 ""
指定要納入快取的規則運算式。如果使用這個選項，系統只會快取符合這個規則運算式的檔案。規則運算式會與 bucket_name/object_key 格式的檔案路徑進行比對。詳情請參閱「使用規則運算式控制檔案層級的可快取性」。 代表規則運算式的字串值。 ""
在所有檔案下載工作中，任何時間可產生的 goroutine 數量上限。
  • 整數
  • -1：指定不限數量的平行下載。
  • 0：停用平行下載。只有在未傳遞 --enable-parallel-downloads 或傳遞為 false 時，才能使用。
 機器 CPU 核心數量的兩倍或 16，以較高者為準。
每個檔案的並行下載要求數量。 整數 16
以八進位制指定檔案的權限位元。 字串值，代表介於 "000" 和 "777" (含) 之間的八進位整數，例如："644"。 644
在前景執行 gcsfuse 指令。 布林值：true、false。 false
指定所有 inode 的群組 ID (GID) 擁有者。
  • 代表 GID 的整數。
  • -1：使用呼叫端的 GID。
 -1
顯示 Cloud Storage FUSE 的說明。 無 無
顯示已安裝的 Cloud Storage FUSE 版本。 無 無
指定 Cloud Storage FUSE HTTP 用戶端在逾時前，可等待伺服器回應的時間。 時間長度，例如：1h10m10s 代表 1 小時 10 分 10 秒。0s 表示沒有逾時。 0s
指示 Cloud Storage FUSE 忽略系統中斷信號，例如 Control+C 觸發的 SIGINT。這可防止信號終止執行中的作業。 布林值：true、false。 true
隱含包含資料夾和代管資料夾。詳情請參閱 Cloud Storage FUSE GitHub 說明文件中的「檔案和目錄」。 布林值：true、false。 false

啟用清單快取，並定義快取清單項目的存留時間 (TTL)，以秒為單位。清單快取會保留在頁面快取的記憶體中，由核心根據可用記憶體控制。
  • 代表秒數的整數，例如：10 (10 秒)。
  • 0：停用清單快取功能。
  • -1：略過項目到期時間，並一律從快取傳回清單回應 (如有)。
 0
指定憑證 JSON 金鑰檔案的絕對路徑，用於驗證傳送至 Cloud Storage 的要求。根據預設，Cloud Storage FUSE 會使用應用程式預設憑證驗證要求。 路徑，例如：/home/example_user/gcloud-key.json。 如未設定這個選項，系統會使用應用程式預設憑證。
指定 Cloud Storage FUSE 從 Cloud Storage 讀取資料的頻寬限制，以 30 秒為單位測量。 浮點數。-1 表示不設限。 -1
指定每秒執行的作業數量上限，以 30 秒為單位計算。 浮點數。-1 表示不設限。 -1
指定用於儲存記錄的檔案，這些記錄可由 Fluentd 剖析。 路徑，例如：/tmp/user-example-bucket-gcsfuse-logs.txt。 Cloud Storage FUSE 在前景執行時為 stdout，在背景執行時則為 syslog
指定記錄檔的格式。
  • text
  • json
 json
要保留的輪替記錄檔數量上限，不含寫入記錄檔的有效檔案。
  • 整數
  • 0：保留所有輪替的記錄檔
 10
指定是否使用 gzip 壓縮輪替的記錄檔。 布林值：true、false。 true
記錄檔在輪替前可達到的最大大小 (以 MB 為單位)。 整數。最小值為 1。 512

Cloud Storage FUSE 產生記錄的嚴重性等級。嚴重性等級由低到高排序。例如，指定 warning 時，Cloud Storage FUSE 會產生警告和錯誤的記錄。一般來說，建議使用 info 嚴重性等級。
  • off：停用所有記錄功能。
  • error：包含嚴重問題的訊息，這些問題會導致 Cloud Storage FUSE 無法完成作業，或指出失敗，例如掛接失敗、權限錯誤和重大輸入/輸出 (I/O) 錯誤。
  • warning：包含指出潛在問題的訊息，這些問題並非重大問題，但如果不解決，可能會導致問題。潛在問題包括非致命連線問題、淘汰警告、可能導致效能稍微降低的資源爭用，以及暫時性失敗的重試。這個嚴重性等級也包含 error 嚴重性等級提供的資訊。
  • info：包含一般記錄資訊，例如啟動和關機訊息，或成功掛接作業、進度更新和配置設定的相關資訊。這個嚴重程度等級也包含 warning 和 error 嚴重程度等級的資訊。
  • debug：包含記錄資訊，例如啟動和關機訊息，或成功掛接作業、進度更新和配置設定的相關資訊。這個嚴重性等級也包含 info、warning 和 error 嚴重性等級提供的資訊。
  • trace：包含每項 Cloud Storage FUSE 作業和函式呼叫的詳細資料，概述 gcsfuse 與核心 FUSE 驅動程式和 Cloud Storage 的互動。這個嚴重程度等級也包含 debug、info、warning 和 error 嚴重程度等級提供的詳細資料。
 info
指定每部伺服器允許的 TCP 連線數量上限。 --client-protocol 設為 http1 時，這項設定就會生效。 介於 0 和 2147483647 之間的整數。0 指定 TCP 連線數量沒有限制。 0
指定每個伺服器允許的閒置連線數量上限。 --client-protocol 設為 http1 時，這項設定就會生效。 介於 0 和 2147483647 之間的整數。0 指定閒置連線數量沒有限制。 0
指定作業失敗時的重試次數上限，避免無限重試迴圈。
  • 代表重試次數上限的整數，例如：10。
  • 0：允許無限次重試。
 0
指定 Cloud Storage FUSE 在指數輪詢重試迴圈中，可休眠的最長時間。一旦輪詢持續時間超過指定的時間長度上限，重試作業就會繼續執行，直到達到指定的時間長度上限。 時間長度，例如：1h5m50s (1 小時 5 分 50 秒) 或 60s (60 秒)。 30s

定義負面統計資料快取項目的存留時間 (TTL，以秒為單位)，用於儲存快取中不存在檔案的結果。
  • 代表秒數的整數，例如：10 (10 秒)。
  • 0：停用負面統計資料快取。
  • -1：允許無限的負面狀態快取，並停用存留時間到期。
 5
定義快取中繼資料項目的存留時間 (TTL)，以秒為單位。
  • 代表秒數的整數，例如：30 (30 秒)。
  • -1：略過存留時間到期，並在檔案可用時從快取提供檔案。
  • 0：使用最新檔案。使用這個值會發出 Get 中繼資料呼叫，確保快取中檔案的物件世代與 Cloud Storage 中儲存的世代相符。
 60
指定其他系統專屬掛接選項。Cloud Storage FUSE 支援 FUSE 中的大多數一般掛接選項 (例如 suid)，且可與 -o 選項一併傳遞。 FUSE 中的掛接選項，例如：
  • rw：以讀寫模式掛接。
  • ro：以唯讀方式掛接。
 ""
只掛接 bucket 中的特定目錄。 路徑，例如：/etc/gcsfuse.yaml。 ""
套用預先定義且經過最佳化的 Cloud Storage FUSE 設定，包括快取、執行緒和緩衝區空間，協助您針對特定工作負載類型 (例如訓練、提供和檢查點) 達到高效能。如要進一步瞭解各個預先定義的設定 (依工作負載類型區分)，請參閱「AI/機器學習工作負載的設定檔設定」。
  • 字串，例如 "aiml-checkpointing"。
  • "aiml-training"：針對大型資料集的高處理量讀取作業最佳化效能，並防止 Cloud GPU 和 Cloud TPU 硬體等待資料。
  • aiml-checkpointing：大幅縮短儲存數 GB 查核點所需的時間，盡可能減少訓練暫停次數，進而最佳化大型檔案高處理量寫入作業的效能。
  • aiml-serving：簡化資料存取流程並套用快取機制，提升服務工作負載的效能。
 ""

在指定的通訊埠和 /metrics 路徑上公開 Prometheus 指標端點。

 代表要指定通訊埠的整數。 0

指定所有檔案處理中，緩衝讀取可用的區塊數量上限。
  • 整數
  • 0：停用緩衝讀取。
  • -1：將值設為無限個方塊。
 40
允許重新命名子系數量少於指定限制的目錄。 介於 0 和 2147483647 之間的整數。 0
指定連續重試之間指數輪詢的乘數。 浮點數。 2
指定是否重複使用從 --token-url 取得的權杖。 布林值：true、false。 true
指定要從 Cloud Storage 下載的資料區塊大小，以 MB 為單位。 介於 1 和 1024 之間的整數。 200
指定統計資料快取可保留的項目數量。這個 gcsfuse 選項已由 --stat-cache-max-size-mb gcsfuse 選項取代。 整數 4096
統計資料快取可使用的記憶體大小上限 (以 MiB 為單位)。狀態快取一律會完整保留在記憶體中。
  • 整數。建議採取以下做法：
    • 如果工作負載涉及最多 20,000 個檔案，請使用 34。
    • 如果工作負載超過 20,000 個檔案，每增加 6,000 個檔案，請將大小增加 10，其中統計資料快取平均每個檔案使用 1,720 個位元組 (包括 220 個類型資訊)。
  • -1：不設限，統計資料快取會視需要使用記憶體。
  • 0：停用統計資料快取。
 34
指定 StatObject 結果和 inode 屬性的快取時間長度。這個選項已由 --metadata-cache-ttl-secs gcsfuse 選項取代。 時間長度，例如：20s (20 秒)。 60s
指定暫存目錄的路徑，寫入作業會先暫存在該目錄，再上傳至 Cloud Storage。 路徑，例如：/mnt/ssd/example-user-gcsfuse-temp-dir。 /tmp
指定在缺少 --key-file 時，用於取得存取權杖的網址。 網址。 ""
指定名稱與目錄 inode 中檔案或目錄之間的對應關係快取時間長度，以秒為單位。這個 gcsfuse 選項已由 --metadata-cache-ttl-secs gcsfuse 選項取代。 時間長度 (秒)，例如：20s (20 秒)。 60s
類型快取可使用的每個目錄大小上限 (以 MiB 為單位)。類型快取一律會完整保留在記憶體中。
  • 整數。建議採取下列做法：
    • 如果掛接的 bucket 中，單一目錄內的檔案數量不超過 20,000 個，則為 4。
    • 如果掛接的單一目錄中最多包含超過 20,000 個檔案，請每 5,000 個檔案將值增加 1，平均每個檔案約 200 個位元組。
  • -1：不指定限制，讓類型快取視需要使用記憶體。
  • 0：停用類型快取。
 4
啟用這項功能後，如果快取失敗，系統會在背景預先擷取目錄中物件的中繼資料。這個旗標會批次更新中繼資料快取，大幅縮短後續查詢目錄中檔案的延遲時間。 布林值：true、false。 false
指定每個目錄預先擷取的中繼資料項目數量上限。如果指定的值超過 5,000 個中繼資料項目，系統會連續多次呼叫 Cloud Storage Objects: list，因為每次呼叫最多只能傳回 5,000 個結果。 介於 -1 和 2147483647 之間的整數。設為 -1 即可預先擷取所有項目。 5000
在所有目錄中，可同時執行中繼資料預先擷取作業的背景 worker 數量上限。 介於 -1 和 2147483647 之間的整數。如不限制 worker 數量，請設為 -1。 10
指定所有 inode 的使用者 ID (UID) 擁有者。
  • 代表 UID 的整數。
  • -1：使用呼叫端的 UID。
 -1

指定所有檔案中可用於串流寫入的資料區塊數量上限。根據預設，每個檔案會使用一個 32 MiB 的資料區塊。
  • 整數
  • 0：停用串流寫入。
  • -1：將值設為不限區塊數量。
  • 資源有限的低規格機器預設值：4
  • 高規格機器 (具備大量資源) 的預設值：1600

返回頁首