Cloud Storage FUSE CLI

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

Cloud Storage FUSE CLI 總覽

Cloud Storage FUSE 指令列介面 (CLI) 或 gcsfuse CLI，用於將 Cloud Storage 值區掛接為本機的檔案系統。

注意： 對於特定高效能機器類型，系統預設會自動將部分 gcsfuse 指令選項設為特定值，以盡可能提升效能。掛接時手動設定的值會覆寫這些預設值。詳情請參閱「高效能機器類型的自動化設定」。

gcsfuse CLI 指令結構

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

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

其中：

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

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

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

gcsfuse CLI 選項

gcsfuse選項	說明	有效值	預設值
--anonymous-access	停用要求驗證。如果您使用的自訂端點不支援驗證，請設定這個選項。如果您搭配使用 Cloud Storage FUSE 與公開值區，也應設定這個選項。	布林值：true、false。	false
--app-name	掛接點的應用程式名稱。	字串值，例如：my-bucket-mount。	""
--billing-project	指定存取已掛接值區時要使用的計費專案。掛接已啟用要求者付費功能的值區時，通常需要使用這個選項。	代表專案 ID 的字串值。	""
--cache-dir	啟用檔案快取，並指定用於儲存檔案快取資料的目錄。 注意：Google Kubernetes Engine 的 Cloud Storage FUSE CSI 驅動程式使用不同的方法啟用檔案快取。如要瞭解如何在 Google Kubernetes Engine 上啟用檔案快取，請參閱「啟用及使用檔案快取」一文。	路徑，例如：/tmp/gcsfuse-cache-path。如果值為空白，表示這個選項已停用。這個 gcsfuse 選項預設為停用。	""
--client-protocol	指定用於與 Cloud Storage 後端通訊的通訊協定。	http1 (適用於 HTTP/1.1) http2 for HTTP/2 grpc for gRPC。 如要搭配使用 gRPC 與 Cloud Storage FUSE，建議使用 Cloud Storage FUSE 2.10.0 以上版本。	http1
--cloud-metrics-export-interval-secs	以指定間隔將指標匯出至 Cloud Monitoring。 注意：使用這個選項需要額外設定。詳情請參閱「設定 Cloud Monitoring 匯出工具」。	以秒為單位的整數值，例如：10 (10 秒)。 0 指定不匯出。	0
--config-file	指定要用來設定 Cloud Storage FUSE 行為的設定檔路徑。	路徑，例如：/etc/gcsfuse.yaml。	""
--custom-endpoint	指定用於擷取資料的替代自訂端點。 自訂端點必須支援與 Cloud Storage JSON 端點 storage.UNIVERSE_DOMAIN_NAME:443 相同的資源和作業。如未指定自訂端點，Cloud Storage FUSE 會使用全域 Cloud Storage JSON API 端點 storage.googleapis.com:443。如果您指定的自訂端點不支援驗證，請將 --anonymous-access gcsfuse 選項設為 true，略過驗證。	端點，例如：storage.googleapis.com:443。	""
--debug_fuse (已淘汰)	啟用 FUSE 相關偵錯輸出內容。這個選項已由 --log-severity gcsfuse 選項取代。如要啟用偵錯輸出內容，請將 --log-severity gcsfuse 選項設為 trace，其中包含追蹤、偵錯、資訊、警告和錯誤記錄。	布林值：true、false。	false
--debug_gcs (已淘汰)	列印 Cloud Storage 要求和時間資訊。這個 gcsfuse 選項已由 --log-severity gcsfuse 選項取代。如要啟用偵錯輸出內容，請將 --log-severity gcsfuse 選項設為 trace，其中包含追蹤、偵錯、資訊、警告和錯誤記錄。	布林值：true、false。	false
--debug_invariants	偵測到內部不變量違規時，會結束程式。	布林值：true、false。	false
--debug_mutex	在互斥鎖持有時間過長時，列印偵錯訊息。如果指定這個 gcsfuse 選項，記錄的嚴重程度會自動設為 trace，包括追蹤、偵錯、資訊、警告和錯誤記錄。	布林值：true、false。	false
--dir-mode	目錄的權限位元 (八進位)。	介於 000 和 777 之間的整數 (包含首尾)。	755
--enable-buffered-read	指定將 Cloud Storage 物件的部分內容非同步預先擷取到記憶體內緩衝區，以便後續讀取作業可從緩衝區提供服務，而不需發出網路呼叫。	布林值：true、false	false
--enable-nonexistent-type-cache	如果 Cloud Storage 中沒有檔案，則會建立含有 NonexistentType 類型的快取項目。如果檔案是在 Cloud Storage 中建立，但檔案的 NonexistentType 項目已快取，則 Cloud Storage FUSE 無法要求該檔案，直到 NonexistentType 項目從類型快取中移除為止。	布林值：true、false。	false
--enable-streaming-writes	控制寫入路徑流程，以便在寫入資料時直接上傳至 Cloud Storage，而不是在本機完全暫存寫入內容，並在 close() 或 fsync() 時上傳。如要進一步瞭解串流寫入作業，請參閱 Cloud Storage FUSE GitHub 說明文件中的「Cloud Storage FUSE 語意」。	布林值：true、false。	true
--file-cache-max-size-mb	指定檔案快取可使用的最大大小 (以 MiB 為單位)，並限制檔案快取在掛接目錄中可使用的總容量。 注意：設定 --file-cache-max-size-mb gcsfuse 選項前，請先指定 cache-dir gcsfuse 選項。如果是 Compute Engine VM (包括獨立的 Cloud Storage FUSE 或非 Google Kubernetes Engine 的部署作業)，啟用 cache-dir 會自動將 --file-cache-max-size-mb 設為 -1。	整數 -1：指定在為 cache-dir 指定的目錄中，使用快取的所有可用容量。只有在傳遞 cache-dir 時，這才是預設值。 0：停用檔案快取。	-1
--file-cache-cache-file-for-range-read	判斷是否應非同步下載完整物件，並在從非零偏移完成第一次讀取時，儲存在 Cloud Storage FUSE 快取目錄中。如果您打算執行多個隨機讀取或部分讀取作業，請將這個 gcsfuse 選項設為 true。 注意：如果您從偏移量 0 開始執行部分讀取作業，Cloud Storage FUSE 會非同步下載並快取完整物件。	布林值：true、false。	false
--file-cache-download-chunk-size-mb	指定每個 goroutine 在將物件下載至檔案快取時，向 Cloud Storage 發出的每個讀取要求大小 (以 MiB 為單位)。	整數	200
--file-cache-enable-parallel-downloads	使用檔案快取目錄做為預先擷取緩衝區，並使用多個工作站平行下載檔案的多個部分，加快大型檔案的讀取速度。 啟用檔案快取時，系統會自動啟用平行下載功能。 如要進一步瞭解檔案快取，請參閱「使用 Cloud Storage FUSE 檔案快取」。 如要進一步瞭解平行下載功能，以及如何設定支援的屬性，請參閱「平行下載」。	布林值：true、false。	true
--file-cache-max-parallel-downloads	在所有檔案的下載作業中，任何時間點可產生的 goroutine 數量上限。	整數 -1：指定無限次數的平行下載。 0：停用平行下載功能。只有在未傳遞 --enable-parallel-downloads 或傳遞為 false 時，才能使用。	機器上的 CPU 核心數的兩倍或 16，以較高者為準。
--file-cache-parallel-downloads-per-file	每個檔案的並行下載要求數量。	整數	16
--file-mode	以八進位表示檔案的權限位元。	介於 000 和 777 之間的整數 (包含首尾)。	644
--foreground	在前台執行 gcsfuse 指令。	布林值：true、false。	false
--gid	指定所有 inode 的群組 ID (GID) 擁有者。	代表 GID 的整數。 -1：使用呼叫端的 GID。	-1
--help	顯示 Cloud Storage FUSE 的說明。	無	無
--version	顯示您安裝的 Cloud Storage FUSE 版本。	無	無
--http-client-timeout	指定 Cloud Storage FUSE HTTP 用戶端等待伺服器回應的時間長度，超過這個時間就會逾時。	時間長度，例如：1h10m10s 代表 1 小時 10 分 10 秒。0s 表示沒有逾時。	0s
--ignore-interrupts	指示 Cloud Storage FUSE 忽略系統中斷信號，例如 Control+C 觸發的 SIGINT。這可防止信號終止進行中的作業。	布林值：true、false。	true
--implicit-dirs	隱含包含資料夾和代管資料夾。詳情請參閱 Cloud Storage FUSE GitHub 說明文件中的「檔案和目錄」。	布林值：true、false。	false
--kernel-list-cache-ttl-secs	啟用清單快取，並定義快取清單項目的存留時間 (TTL)，以秒為單位。清單快取會保留在頁面快取中的記憶體，而頁面快取是由核心根據可用記憶體控管。	以整數表示秒數，例如：10 (10 秒)。 0：停用清單快取。 -1：略過項目到期時間，並在快取可用時一律傳回清單回應。	0
--key-file	指定憑證 JSON 金鑰檔案的絕對路徑，用於驗證對 Cloud Storage 的要求。根據預設，Cloud Storage FUSE 會使用應用程式預設憑證驗證要求。	路徑，例如：/home/example_user/gcloud-key.json。	如未設定這個選項，系統會使用應用程式預設憑證。
--limit-bytes-per-sec	指定 Cloud Storage FUSE 從 Cloud Storage 讀取資料時的頻寬限制，以 30 秒為測量時間間隔。	浮點數。-1 表示沒有限制。	-1
--limit-ops-per-sec	指定每秒執行的作業數上限，以 30 秒的時間範圍為準。	浮點數。-1 表示沒有限制。	-1
--log-file	指定用於儲存記錄的檔案，這些記錄可由 Fluentd 剖析。	路徑，例如：/tmp/user-example-bucket-gcsfuse-logs.txt。	stdout 在前景執行 Cloud Storage FUSE 時，或 syslog 在背景執行 Cloud Storage FUSE 時
--log-format	指定記錄檔的格式。	text json	json
--log-rotate-backup-file-count	要保留的輪替記錄檔數量上限，不包括寫入記錄的現用檔案。	整數 0：保留所有輪替的記錄檔	10
--log-rotate-compress	指定是否要使用 gzip 壓縮輪替的記錄檔。	布林值：true、false。	true
--log-rotate-max-file-size-mb	記錄檔的大小上限 (以 MB 為單位)，達到上限後就會輪替。	整數。最小值為 1。	512
--log-severity	您希望 Cloud Storage FUSE 產生記錄的嚴重程度。嚴重性等級由低至高排序。舉例來說，當您指定 warning 時，Cloud Storage FUSE 會產生警告和錯誤的記錄。一般而言，我們建議使用 info 嚴重程度。 注意：如果您在指令中指定 --debug_mutex，嚴重程度會自動設為 trace，並覆寫 log-severity。 注意：啟用檔案快取時，使用 trace 或 debug 嚴重程度層級可能會因記錄負荷而導致效能下降，因此應僅暫時使用，例如在進行疑難排解時。	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
--max-conns-per-host	指定每個伺服器允許的 TCP 連線數上限。 這項屬性只會在 --client-protocol 設為 http1 時生效。	介於 0 和 2147483647 之間的整數。 0 指定 TCP 連線沒有限制。	0
--max-idle-conns-per-host	指定每個伺服器允許的閒置連線數量上限。 這項屬性只會在 --client-protocol 設為 http1 時生效。	介於 0 和 2147483647 之間的整數。 0 指定閒置連線沒有限制。	0
--max-retry-attempts	指定作業失敗時的重試次數上限，避免無止盡的重試迴圈。	代表重試次數上限的整數，例如： 10。 0：允許無限次重試。	0
--max-retry-sleep	指定 Cloud Storage FUSE 在指數輪詢的重試迴圈中，可休眠的最長時間。一旦輪詢持續時間超過指定上限，重試作業就會繼續進行，但輪詢持續時間會設為指定上限。	時間長度，例如：1h5m50s (1 小時 5 分 50 秒) 或 60s (60 秒)。	30s
--metadata-cache-negative-ttl-secs	定義負面狀態快取項目的存留時間 (TTL)，以秒為單位，用於儲存快取中不存在的檔案結果。	以整數表示秒數，例如：10 (10 秒)。 0：停用負面統計資料快取。 -1：允許無限次負面狀態快取，並停用存留時間到期。	5
--metadata-cache-ttl-secs	定義快取中繼資料項目的存留時間 (TTL)，以秒為單位。	以秒為單位的整數，例如：30 (30 秒)。 -1：略過 TTL 到期時間，並在檔案可用的情況下，一律從快取提供檔案。 0：使用最新檔案。使用這個值會發出 Get 中繼資料呼叫，確保快取中的檔案物件產生與 Cloud Storage 中儲存的內容相符。詳情請參閱「設定快取撤銷」。	60
-o	指定其他系統專屬的掛接選項。Cloud Storage FUSE 支援 FUSE 中的大多數一般掛接選項 (例如 suid)，並可與 -o 選項一併傳遞。	FUSE 中的掛接選項， 例如： rw：以讀寫模式掛接。 ro：以唯讀模式掛接。	""
--only-dir	只掛接值區內的特定目錄。	路徑，例如：/etc/gcsfuse.yaml。	""
--prometheus-port	在指定通訊埠和 /metrics 路徑上公開 Prometheus 指標端點。 注意：使用這個選項需要額外設定。詳情請參閱「設定 Prometheus 匯出工具」。	代表要指定連接埠的整數。	0
--read-global-max-blocks	指定所有檔案控制代碼可用的緩衝讀取區塊數量上限。 注意：如要使用這個 gcsfuse 選項，必須啟用 --enable-buffered-read 選項。詳情請參閱 --enable-buffered-read 選項。	整數 0：停用緩衝讀取作業。 -1：將值設為無限個方塊。	40
--rename-dir-limit	允許重新命名後代項目少於指定限制的目錄。	介於 0 和 2147483647 之間的整數。	0
--retry-multiplier	指定連續重試之間指數輪詢的乘數。	浮點數。	2
--reuse-token-from-url	指定是否要重複使用從 --token-url 取得的權杖。	布林值：true、false。	true
--sequential-read-size-mb	指定要從 Cloud Storage 下載的資料區塊大小 (以 MB 為單位)。	介於 1 和 1024 之間的整數。	200
--stat-cache-capacity (已淘汰)	指定狀態快取可保留的項目數量。這個 gcsfuse 選項已由 --stat-cache-max-size-mb gcsfuse 選項取代。	整數	4096
--stat-cache-max-size-mb	統計資料快取可使用的記憶體大小上限，以 MiB 為單位。狀態快取一律會完整保留在記憶體中。	整數。建議您採取以下做法： 32，如果工作負載最多包含 20,000 個檔案。 如果工作負載超過 20,000 個檔案，每增加 6,000 個檔案，請將大小增加 10，因為每個檔案的統計資料快取平均會使用 1,500 MiB。 -1：不設限，統計資料快取會視需要使用記憶體。 0：停用統計資料快取。	32
--stat-cache-ttl (已淘汰)	指定要快取 StatObject 結果和 inode 屬性的時間長度。這個選項已由 --metadata-cache-ttl-secs gcsfuse 選項取代。	時間長度，例如：20s (20 秒)。	60s
--temp-dir	指定暫時目錄的路徑，寫入作業會先暫存於該目錄，再上傳至 Cloud Storage。	路徑，例如：/mnt/ssd/example-user-gcsfuse-temp-dir。	/tmp
--token-url	指定在缺少 --key-file 時，用來取得存取權杖的網址。	網址。	""
--type-cache-ttl (已淘汰)	指定要在目錄 inode 中快取名稱與檔案/目錄之間對應的時間長度 (以秒為單位)。這個 gcsfuse 選項已由 --metadata-cache-ttl-secs gcsfuse 選項取代。	時間長度 (秒)，例如：20s (20 秒)。	60s
--type-cache-max-size-mb	類型快取可使用的每個目錄大小上限 (以 MiB 為單位)。 型別快取一律會完整保留在記憶體中。	整數。建議您採取下列做法： 4 如果要掛接的 bucket 中，單一目錄內的檔案數量上限為 20,000 個。 如果單一目錄中要掛接的檔案數量超過 20,000 個，請每增加 5,000 個檔案就將值增加 1，平均每個檔案約 200 個位元組。 -1：指定不設限，讓型別快取視需要使用記憶體。 0：停用型別快取。	4
--uid	指定所有 inode 的使用者 ID (UID) 擁有者。	代表 UID 的整數。 -1：使用呼叫端的 UID。	-1
--write-global-max-blocks	指定所有檔案可用的串流寫入資料區塊數量上限。根據預設，每個檔案會使用一個 32 MiB 的資料區塊。	整數 0：停用串流寫入作業。 -1：將值設為無限制的區塊。	資源有限的低規格機器的預設值： 4 資源量大的高規格機器的預設值：1600

返回頁首