本文說明如何使用 Cloud Storage FUSE 設定檔，以持續性的方式設定 Cloud Storage FUSE 的行為。如要使用設定檔，請在執行 gcsfuse 指令時，於 --config-file 選項中指定設定檔路徑。
Cloud Storage FUSE 設定檔是 YAML 檔案，使用下列格式和欄位。您也可以使用 Cloud Storage FUSE CLI，設定由設定檔欄位控管的行為。
Cloud Storage FUSE 設定檔格式和欄位
下列 YAML 設定範例顯示 Cloud Storage FUSE 中可用的格式和欄位。
app-name: "APP_NAME" logging: file-path: "FILE_PATH" format: FORMAT severity: SEVERITY log-rotate: max-file-size-mb: MAX_FILE_SIZE backup-file-count: BACKUP_FILE_COUNT compress: COMPRESS cache-dir: "CACHE_DIR" file-cache: max-size-mb: MAX_SIZE cache-file-for-range-read: CACHE_FILE_FOR_RANGE_READ enable-parallel-downloads: ENABLE_PARALLEL_DOWNLOADS exclude-regex: EXCLUDE_REGEX include-regex: INCLUDE_REGEX parallel-downloads-per-file: PARALLEL_DOWNLOADS_PER_FILE max-parallel-downloads: MAX_PARALLEL_DOWNLOADS download-chunk-size-mb: DOWNLOAD_CHUNK_SIZE metadata-cache: negative-ttl-secs: ENABLE_NEGATIVE_TTL_SECS stat-cache-max-size-mb: STAT_CACHE_MAX_SIZE ttl-secs: TTL_SECS enable-metadata-prefetch: ENABLE_METADATA_PREFETCH metadata-prefetch-entries-limit: METADATA_PREFETCH_ENTRIES_LIMIT metadata-prefetch-max-workers: METADATA_PREFETCH_MAX_WORKERS only-dir: "ONLY_DIR" gcs-auth: anonymous-access: ANONYMOUS_ACCESS key-file: "KEY_FILE" reuse-token-from-url: REUSE_TOKEN_FROM_URL token-url: "TOKEN_URL" gcs-connection: billing-project: "BILLING_PROJECT" client-protocol: CLIENT_PROTOCOL custom-endpoint: "CUSTOM_ENDPOINT" http-client-timeout: HTTP_CLIENT_TIMEOUT limit-bytes-per-sec: "LIMIT_BYTES_PER_SEC" limit-ops-per-sec: "LIMIT_OPS_PER_SEC" max-conns-per-host: MAX_CONNS_PER_HOST max-idle-conns-per-host: MAX_IDLE_CONNS_PER_HOST sequential-read-size-mb: SEQUENTIAL_READ_SIZE implicit-dirs: IMPLICIT_DIRS file-system: kernel-list-cache-ttl-secs: KERNEL_LIST_CACHE_TTL_SECS ignore-interrupts: IGNORE_INTERRUPTS dir-mode: "DIR_MODE" file-mode: "FILE_MODE" fuse-options: FUSE_OPTIONS gid: GID rename-dir-limit: RENAME_DIR_LIMIT temp-dir: "TEMP_DIR" uid: UID foreground: FOREGROUND gcs-retries: max-retry-attempts: MAX_RETRY_ATTEMPTS max-retry-sleep: MAX_RETRY_SLEEP multiplier: "MULTIPLIER" metrics: cloud-metrics-export-interval-secs: CLOUD_METRICS_EXPORT_INTERVAL prometheus-port: PROMETHEUS_PORT debug: log-mutex: LOG_MUTEX exit-on-invariant-violation: EXIT_ON_INVARIANT_VIOLATION write: enable-streaming-writes: STREAMING_WRITES global-max-blocks: MAXIMUM_GLOBAL_BLOCKS read: enable-buffered-read: ENABLE_BUFFERED_READ global-max-blocks: MAXIMUM_GLOBAL_READ_BLOCKS profile: PROFILE
Cloud Storage FUSE 設定檔欄位
下表說明您可以在 Cloud Storage FUSE 設定檔中指定的欄位。除非另有說明，否則所有欄位皆為選填。
| 欄位 | 說明 | 有效值 | 預設值 |
|---|---|---|---|
|
掛接的應用程式名稱。 | 字串值，例如："my-bucket-mount"。 |
"" |
|
記錄檔的路徑，系統會將記錄寫入該檔案。
如未指定這個欄位，當 Cloud Storage FUSE 在前景模式下執行時，記錄會傳送至 stdout；在背景模式下執行時，記錄會傳送至 syslogs。 |
字串值，例如："/var/log"。 |
"" |
|
指定記錄檔的格式。 |
|
json |
|
您希望 Cloud Storage FUSE 產生記錄的嚴重程度。嚴重性等級由低至高排序。舉例來說，如果您指定 |
|
info |
|
記錄檔的大小上限 (以 MB 為單位)，超過上限就會輪替。 | 整數。最小值為 1。 |
512 |
|
要保留的輪替記錄檔數量上限，不包括寫入記錄的現用檔案。 |
|
10 |
|
指定是否使用 gzip 壓縮輪替的記錄檔。 |
布林值：true、false |
true |
|
啟用檔案快取，並指定用於儲存檔案快取資料的目錄。 |
路徑，例如："/tmp/gcsfuse-cache-path"。
如果值為空白，表示這個欄位已停用。這個欄位預設為停用。 |
|
|
指定檔案快取可使用的 MiB 大小上限，並限制檔案快取在掛接目錄中可使用的總容量。 |
|
-1 |
|
判斷是否應從非零偏移完成第一次讀取時，以非同步方式下載完整物件並儲存在 Cloud Storage FUSE 快取目錄中。如果您打算執行多個隨機讀取或部分讀取作業，請將這個欄位設為 true。 |
布林值：true、false |
false |
|
使用檔案快取目錄做為預先擷取緩衝區，並使用多個工作站平行下載檔案的多個部分，加快大型檔案的讀取速度。 啟用檔案快取功能時，系統會自動啟用平行下載功能。 如要進一步瞭解檔案快取，請參閱「使用 Cloud Storage FUSE 檔案快取」。 如要進一步瞭解平行下載，以及如何設定支援的屬性，請參閱「平行下載」。 |
布林值：true、false。 |
true |
|
指定要從快取排除的檔案的規則運算式。
如果檔案符合這個規則運算式，即使檔案也符合 include-regex，系統也不會快取檔案。
系統會比對規則運算式與格式為 bucket_name/object_key 的檔案路徑。詳情請參閱「使用規則運算式以檔案精細度控制快取功能」。 |
代表規則運算式的字串值。 | "" |
|
指定要納入快取中的檔案的規則運算式。如果使用這個欄位，系統只會快取符合這個規則運算式的檔案。系統會比對規則運算式與格式為 bucket_name/object_key 的檔案路徑。詳情請參閱「使用規則運算式以檔案精細度控制快取功能」。 |
代表規則運算式的字串值。 | "" |
|
指定每個檔案可產生的 goroutine 數量上限，以便從 Cloud Storage 將物件下載至檔案快取。 | 整數 | 16 |
|
在所有檔案的下載作業中，任何時間點可產生的 goroutine 數量上限。 |
|
機器上的 CPU 核心數的兩倍或 16，
以較高者為準。 |
|
指定每個 goroutine 在將物件下載至檔案快取時，向 Cloud Storage 發出的每個讀取要求大小 (以 MiB 為單位)。 | 整數 | 200 |
|
狀態快取可使用的記憶體大小上限 (以 MiB 為單位)。狀態快取一律會完整保留在記憶體中。 |
|
34 |
|
定義負面狀態快取項目的存留時間 (TTL)，以秒為單位。這些項目會將快取中不存在的檔案結果儲存在快取中。 |
|
5 |
|
定義快取中繼資料項目的存留時間 (以秒為單位)。 |
|
60 |
|
如果快取失敗，可啟用目錄中物件的中繼資料背景預先擷取功能。這個選項會對中繼資料快取執行批次更新，大幅縮短目錄中後續檔案查詢的延遲時間。 | 布林值：true、false。 |
false |
|
指定每個目錄預先擷取的最大中繼資料項目數。值：指定超過 5000 個中繼資料項目會導致多個連續的 Cloud Storage Objects: list 呼叫，因為每個個別呼叫最多只能有 5000 個結果。 |
介於 -1 和 2147483647 之間的整數。設為 -1 即可預先擷取所有項目。 |
5000 |
|
允許在所有目錄中執行中繼資料預先擷取的並行背景工作站數量上限。 | 介於 -1 和 2147483647 之間的整數。如要設定無限制的 worker，請設為 -1。 |
10 |
|
只掛接值區內的特定目錄。 | 路徑，例如："/etc/gcsfuse.yaml"。 |
|
|
停用要求的驗證功能。如果您使用的自訂端點不支援驗證，就應設定這個欄位。如果您搭配使用 Cloud Storage FUSE 與公開值區，也應設定這個欄位。 | 布林值：true、false |
false |
|
指定憑證 JSON 金鑰檔案的絕對路徑，用於驗證對 Cloud Storage 的要求。根據預設，Cloud Storage FUSE 會使用應用程式預設憑證驗證要求。 | 網址。 | 如果未設定這個欄位，系統會使用應用程式預設憑證。 |
|
指定是否要重複使用從 --token-url 取得的權杖。 |
布林值：true、false |
true |
|
指定在缺少 --key-file 時，用來取得存取權杖的網址。 |
網址。 | |
|
指定存取已掛接值區時要使用的計費專案。掛接已啟用要求者付費功能的值區時，通常需要這個欄位。 | 代表「專案 ID」的字串值。 | "" |
|
指定與 Cloud Storage 後端通訊時使用的通訊協定。 |
|
http1 |
|
指定用於擷取資料的替代自訂端點。
自訂端點必須支援與 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。 |
|
|
指定 Cloud Storage FUSE HTTP 用戶端等待伺服器回應的時間長度，超過這個時間就會逾時。 | 時間長度，例如：1h10m10s 代表 1 小時 10 分 10 秒。0s 表示沒有逾時。 |
0s，指定沒有逾時 |
|
指定 Cloud Storage FUSE 從 Cloud Storage 讀取資料時的頻寬限制，以 30 秒為測量時間間隔。 | "-1"，表示沒有限制。 |
|
|
指定每秒執行的作業次數上限，以 30 秒為時間範圍。 | 浮點數。-1 表示沒有限制。 |
"-1" |
|
指定每個伺服器允許的 TCP 連線數上限。
當 --client-protocol 設為 http1 時，這項屬性就會生效。 |
0 |
|
|
指定每個伺服器允許的閒置連線數量上限。
當 --client-protocol 設為 http1 時，這項屬性就會生效。 |
介於 0 和 2147483647 之間的整數。
0 表示 TCP 連線沒有限制。 |
0 |
|
指定要從 Cloud Storage 下載的資料區塊大小 (以 MB 為單位)。 | 介於 1 和 1024 之間的整數。 |
200 |
|
隱含包含資料夾和代管資料夾。 詳情請參閱 Cloud Storage FUSE GitHub 說明文件中的「檔案和目錄」。 | 布林值：true、false |
false |
|
啟用清單快取，並定義快取清單項目的存留時間 (TTL)，以秒為單位。清單快取會保留在頁面快取中的記憶體，而頁面快取是由核心根據可用記憶體控管。 |
| 0 |
|
指示 Cloud Storage FUSE 忽略系統中斷信號，例如 Control+C 觸發的 SIGINT。這可防止信號終止進行中的作業。 |
布林值：true、false。 |
true |
|
目錄的權限位元 (八進位)。 | 介於 000 和 777 之間的整數 (包含首尾)。 |
"755" |
|
以八進位指定檔案的權限位元。 | 介於 000 和 777 之間的整數 (包含首尾)。 |
"644" |
|
指定其他系統專屬的掛接選項。 | ||
|
指定所有 inode 的群組 ID (GID) 擁有者。 |
|
-1 |
|
允許重新命名後代數量少於指定限制的目錄。 | 介於 0 和 2147483647 之間的整數。 |
0 |
|
指定暫時目錄的路徑，寫入作業會先暫存於該目錄，再上傳至 Cloud Storage。 | 字串路徑，例如："/mnt/ssd/example-user-gcsfuse-temp-dir"。 |
"/tmp" |
|
指定所有 inode 的使用者 ID (UID) 擁有者。 |
|
-1 |
|
在前台執行 gcsfuse 指令。 |
布林值：true、false |
false |
|
指定作業失敗時的重試次數上限，避免無止盡的重試迴圈。 |
|
0 |
|
指定 Cloud Storage FUSE 在指數輪詢的重試迴圈中，可休眠的最長時間。一旦輪詢持續時間超過指定上限，重試作業就會繼續進行，但會採用指定上限。 | 時間長度，例如：1h5m50s (1 小時 5 分 50 秒) 或 60s (60 秒)。 |
30s |
|
指定連續重試之間指數輪詢的乘數。 | 浮點數 | "2" |
|
以指定間隔將指標匯出至 Cloud Monitoring。 |
代表秒數值的整數，例如：10 (10 秒)。
0 指定不匯出。 |
0 |
|
在指定通訊埠和路徑上公開 Prometheus 指標端點。 |
代表要指定連接埠的整數。 | 0 |
|
在互斥鎖定時間過長時，列印偵錯訊息。如果指定這個欄位，系統會自動將記錄的嚴重性等級設為 trace，包括追蹤記錄、偵錯記錄、資訊記錄、警告記錄和錯誤記錄。 |
布林值：true、false。 |
false |
|
偵測到內部變體違規時，會結束程式。 | 布林值：true、false。 |
false |
|
控制寫入路徑流程，以便在寫入資料時直接上傳至 Cloud Storage，而不是在本機完全暫存寫入內容，並在 close() 或 fsync() 時上傳。如要進一步瞭解串流寫入作業，請參閱 Cloud Storage FUSE GitHub 說明文件中的「讀取/寫入」一節。 |
布林值：true、false。 |
true |
|
指定所有檔案可用的串流寫入資料區塊數量上限。根據預設，每個檔案會使用一個 32 MiB 的資料區塊。 |
|
|
|
指定將 Cloud Storage 物件的部分內容非同步預先擷取到記憶體內緩衝區，讓後續讀取作業可從緩衝區提供服務，而不需發出網路呼叫。 | 布林值：true、false |
false |
|
指定所有檔案控制代碼可用的緩衝讀取區塊數量上限。 |
|
40 |
|
套用預先定義的最佳化 Cloud Storage FUSE 設定組合，用於快取、執行緒和緩衝區大小，協助您針對特定工作負載類型 (例如訓練、服務和檢查點) 達成高效能。如要進一步瞭解各項預先定義的設定 (依工作負載類型而定)，請參閱「AI/ML 工作負載的設定檔式設定」。 |
|
"" |