gcsfuse CLI

本頁說明用來與 Cloud Storage FUSE 互動的 gcsfuse 指令列選項。如果您使用 Cloud Storage FUSE CSI 驅動程式，將值區掛接至 Google Kubernetes Engine 中的本機檔案系統，請參閱「Cloud Storage FUSE CSI 驅動程式的掛接選項」。

gcsfuse CLI 總覽

gcsfuse CLI 可用來將 Cloud Storage bucket 掛接為本機電腦上的檔案系統。

Cloud Storage FUSE CLI 選項指令結構

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

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

其中：

  • GLOBAL_OPTIONS 是用來控管掛接設定方式和 Cloud Storage FUSE 運作方式的選項。

  • BUCKET_NAME 是要掛接的值區名稱。例如，my-mount-bucket。(選用步驟) 從這項指令排除 bucket 名稱，即可執行動態掛接。

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

全域選項

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

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

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

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

 以秒為單位的整數值，例如：10 (10 秒)。 0 指定不匯出。 0
指定要用來設定 Cloud Storage FUSE 行為的設定檔路徑。 路徑，例如：/etc/gcsfuse.yaml。 ""
指定用於擷取資料的替代自訂端點。 自訂端點必須支援與 Cloud Storage JSON 端點 storage.UNIVERSE_DOMAIN_NAME:443 相同的資源和作業。如未指定自訂端點，Cloud Storage FUSE 會使用全域 Cloud Storage JSON API 端點 storage.googleapis.com:443。如果您指定的自訂端點不支援驗證，請將 --anonymous-access 標記設為 true，略過驗證。 端點，例如：storage.googleapis.com:443。 ""
啟用 FUSE 相關偵錯輸出內容。這個選項已由 --log-severity 選項取代。如要啟用偵錯輸出內容，請將 --log-severity 選項設為 trace，其中包含追蹤、偵錯、資訊、警告和錯誤記錄。 布林值：true、false。 false
列印 Cloud Storage 要求和時間資訊。這個選項已由 --log-severity 選項取代。如要啟用偵錯輸出內容，請將 --log-severity 選項設為 trace，其中包含追蹤、偵錯、資訊、警告和錯誤記錄。 布林值：true、false。 false
偵測到內部不變量違規時，會結束程式。 布林值：true、false。 false
在互斥鎖持有時間過長時，列印偵錯訊息。如果指定這個選項，記錄的嚴重性等級會自動設為 trace，包括追蹤、偵錯、資訊、警告和錯誤記錄。 布林值：true、false。 false
目錄的權限位元 (八進位)。 介於 000 和 777 之間的整數 (包含首尾)。 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 說明文件。 布林值：true、false。 true

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

使用檔案快取目錄做為預先擷取緩衝區，並使用多個工作站平行下載檔案的多個部分，加快大型檔案的讀取速度。

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

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

 布林值：true、false。 true
在所有檔案的下載作業中，任何時間點可產生的 goroutine 數量上限。
  • 整數
  • -1：指定無限次數的平行下載。
  • 0：停用平行下載功能。只有在未傳遞 --enable-parallel-downloads 或傳遞為 false 時，才能使用。
 機器上的 CPU 核心數的兩倍或 16，以較高者為準。
每個檔案的並行下載要求數量。 整數 16
以八進位表示檔案的權限位元。 介於 000 和 777 之間的整數 (包含首尾)。 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
隱含包含資料夾和代管資料夾。詳情請參閱 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。 stdout 在前景執行 Cloud Storage FUSE 時，或 syslog 在背景執行 Cloud Storage FUSE 時
指定記錄檔的格式。
  • 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 作業和函式呼叫的詳細資料，說明與核心 FUSE 驅動程式和 Cloud Storage 的 gcsFUSE 互動。這個嚴重程度也包含 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：略過 TTL 到期時間，並在檔案可用的情況下，一律從快取提供檔案。
  • 0：使用最新檔案。使用這個值會發出 Get 中繼資料呼叫，確保快取中的檔案物件產生與 Cloud Storage 中儲存的內容相符。詳情請參閱「設定快取撤銷」。
 60
指定其他系統專屬的掛接選項。Cloud Storage FUSE 支援 FUSE 中的大多數一般掛接選項 (例如 suid)，並可與 -o 選項一併傳遞。 FUSE 中的掛接選項， 例如：
  • rw：以讀寫模式掛接。
  • ro：以唯讀模式掛接。
 ""
只掛接值區內的特定目錄。 路徑，例如：/etc/gcsfuse.yaml。 ""

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

 代表要指定連接埠的整數。 0

指定所有檔案控制代碼可用的緩衝讀取區塊數量上限。
  • 整數
  • 0：停用緩衝讀取作業。
  • -1：將值設為無限個方塊。
 40
允許重新命名後代項目少於指定限制的目錄。 介於 0 和 2147483647 之間的整數。 0
指定連續重試之間指數輪詢的乘數。 浮點數。 2
指定是否要重複使用從 --token-url 取得的權杖。 布林值：true、false。 true
指定要從 Cloud Storage 下載的資料區塊大小 (以 MB 為單位)。 介於 1 和 1024 之間的整數。 200
指定狀態快取可保留的項目數量。這個選項已由 --stat-cache-max-size-mb 選項取代。 整數 4096
統計資料快取可使用的記憶體大小上限，以 MiB 為單位。狀態快取一律會完整保留在記憶體中。
  • 整數。建議您採取以下做法：
    • 32，如果工作負載最多包含 20,000 個檔案。
    • 如果工作負載超過 20,000 個檔案，每增加 6,000 個檔案，請將大小增加 10，因為每個檔案的統計資料快取平均會使用 1,500 MiB。
  • -1：不設限，統計資料快取會視需要使用記憶體。
  • 0：停用統計資料快取。
 32
指定要快取 StatObject 結果和 inode 屬性的時間長度。這個選項已由 --metadata-cache-ttl-secs 選項取代。 時間長度，例如：20s (20 秒)。 60s
指定暫時目錄的路徑，寫入作業會先暫存於該目錄，再上傳至 Cloud Storage。 路徑，例如：/mnt/ssd/example-user-gcsfuse-temp-dir。 /tmp
指定在缺少 --key-file 時，用來取得存取權杖的網址。 網址。 ""
指定要在目錄 inode 中快取名稱與檔案/目錄之間對應的時間長度 (以秒為單位)。這個選項已由 --metadata-cache-ttl-secs 選項取代。 時間長度 (秒)，例如：20s (20 秒)。 60s
類型快取可使用的每個目錄大小上限 (以 MiB 為單位)。 型別快取一律會完整保留在記憶體中。
  • 整數。建議您採取下列做法：
    • 4 如果要掛接的 bucket 中，單一目錄內的檔案數量上限為 20,000 個。
    • 如果單一目錄中要掛接的檔案數量超過 20,000 個，請每增加 5,000 個檔案就將值增加 1，平均每個檔案約 200 個位元組。
  • -1：指定不設限，讓型別快取視需要使用記憶體。
  • 0：停用型別快取。
 4
指定所有 inode 的使用者 ID (UID) 擁有者。
  • 代表 UID 的整數。
  • -1：使用呼叫端的 UID。
 -1

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

返回頁首