Cloud Storage FUSE 配置文件

本文档介绍了如何使用 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
  parallel-downloads-per-file: PARALLEL_DOWNLOADS_PER_FILE
  max-parallel-downloads: MAX_PARALLEL_DOWNLOADS
  download-chunk-size-mb: DOWNLOAD_CHUNK_SIZE
metadata-cache:
  enable-nonexistent-type-cache: ENABLE_NONEXISTENT_TYPE_CACHE
  negative-ttl-secs: ENABLE_NEGATIVE_TTL_SECS
  stat-cache-max-size-mb: STAT_CACHE_MAX_SIZE
  ttl-secs: TTL_SECS
  type-cache-max-size-mb: TYPE_CACHE_MAX_SIZE
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 配置文件中指定的字段。除非另有说明，否则所有字段均为可选字段。

字段	说明	有效值	默认值
app-name	装载的应用名称。	字符串值，例如："my-bucket-mount"。	""
file-path	日志写入的日志文件的路径。如果未指定此字段，则当 Cloud Storage FUSE 在前台模式下运行时，日志会路由到 stdout；当 Cloud Storage FUSE 在后台模式下运行时，日志会路由到 syslogs。	字符串值，例如："/var/log"。	""
format	指定日志文件的格式。	text json	json
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-file-size-mb	日志文件在轮替之前可以达到的大小上限，以兆字节 (MB) 为单位。	整数。最小值为 1。	512
backup-file-count	要保留的轮替日志文件数上限，不包括日志写入的活跃文件。	整数 0：保留所有轮替的日志文件	10
compress	指定是否使用 gzip 压缩轮替的日志文件。	布尔值：true、false。	true
cache-dir	启用文件缓存并指定用于存储文件缓存数据的目录。 注意：适用于 Google Kubernetes Engine 的 Cloud Storage FUSE CSI 驱动程序使用不同的方法来启用文件缓存。如需了解如何在 Google Kubernetes Engine 上启用文件缓存，请参阅 Cloud Storage FUSE 中的文件缓存。	路径，例如："/tmp/gcsfuse-cache-path"。 空值表示此字段处于停用状态。此字段默认处于停用状态。
max-size-mb	用于指定文件缓存可以使用的大小上限（以 MiB 为单位），并使您能够限制文件缓存可以在其装载的目录中使用的总容量。 注意：在设置 file-cache:max-size-mb 字段之前，您必须先指定 cache-dir 字段。对于 Compute Engine 虚拟机（包括独立 Cloud Storage FUSE 或非基于 Google Kubernetes Engine 的部署），启用 cache-dir 会自动将 file-cache:max-size-mb 设置为 -1。	整数 -1：指定在您为 cache-dir 指定的目录中使用缓存的全部可用容量。仅当传递 cache-dir 时，此值为默认值。 0：停用文件缓存。	-1
cache-file-for-range-read	确定从非零偏移量完成首次读取时，是否应异步下载完整对象并将其存储在 Cloud Storage FUSE 缓存目录中。如果您打算执行多次随机读取或部分读取，则应将此字段设置为 true。 注意：如果您从偏移量 0 处开始执行部分读取，则 Cloud Storage FUSE 会异步下载并缓存整个对象。	布尔值：true、false。	false
enable-parallel-downloads	通过使用文件缓存目录作为预提取缓冲区，并使用多个工作器并行下载文件的多个部分，从而加快大型文件的读取速度。 启用文件缓存后，系统会自动启用并行下载。 如需详细了解文件缓存，请参阅使用Cloud Storage FUSE 文件缓存。 如需详细了解并行下载以及如何配置支持的属性，请参阅并行下载。	布尔值：true、false。	true
parallel-downloads-per-file	指定要为每个文件生成的 goroutine 数量上限，以便将对象从 Cloud Storage 下载到文件缓存中。	整数	16
max-parallel-downloads	在任何给定时间，所有文件下载作业可同时生成的 goroutine 数上限。	整数 -1：指定无限并行下载。 0：停用并行下载。仅当 --enable-parallel-downloads 未传递或以 false 的形式传递时才可使用。	机器上的 CPU 核心数的两倍或 16（以较高者为准）。
download-chunk-size-mb	指定每个 goroutine 将对象下载到文件缓存时向 Cloud Storage 发出的每个读取请求的大小（以 MiB 为单位）。	整数	200
enable-nonexistent-type-cache	如果在 Cloud Storage 中找不到某个文件，则会创建一个类型为 NonexistentType 的类型缓存条目。如果文件是在 Cloud Storage 中创建的，但文件的 NonexistentType 条目已缓存，则在从类型缓存中移除 NonexistentType 条目之前，Cloud Storage FUSE 无法请求该文件。	布尔值：true、false。	false
stat-cache-max-size-mb	统计信息缓存可以使用的内存大小上限（以 MiB 为单位）。统计信息缓存始终完全保留在内存中。	整数。我们建议您执行以下操作： 如果您的工作负载最多涉及 20,000 个文件，请指定 32。 如果您的工作负载超过 20,000 个文件，则每增加 6,000 个文件，大小值将增加 10，统计信息缓存平均为每个文件使用 1,500 MiB。 -1：不设置限制，即统计信息缓存根据需要使用尽可能多的内存。 0：停用统计信息缓存。	32
negative-ttl-secs	定义负统计信息缓存条目的存留时间 (TTL)（以秒为单位），该条目会存储缓存中不存在的文件的结果。	表示秒数的整数，例如：10（10 秒）。 0：停用负统计信息缓存。 -1：允许无限负统计信息缓存，并停用 TTL 到期。	5
ttl-secs	定义缓存元数据条目的存留时间 (TTL)（以秒为单位）。	表示秒数的整数，例如：30（30 秒）。 -1：跳过 TTL 过期时间，在文件可用时从缓存中传送文件。 0：使用最新的文件。使用此值会发出 Get 元数据调用，以确保缓存中文件的对象世代与 Cloud Storage 中存储的文件的对象世代一致。	60
type-cache-max-size-mb	类型缓存可以使用的每个目录的大小上限（以 MiB 为单位）。 类型缓存始终完全保留在内存中。	整数。我们建议您执行以下操作： 如果要装载的存储桶的单个目录内文件数量上限包含 20,000 个或更少的文件，请指定 4。 如果您要装载的单个目录中的文件数上限超过 20,000，则每 5,000 个文件，值将增加 1，平均每个文件大约增加 200 个字节。 -1：指定无限制，让类型缓存根据需要使用尽可能多的内存。 0：停用类型缓存。	4
only-dir	仅在存储桶中装载特定目录。	路径，例如："/etc/gcsfuse.yaml"。
anonymous-access	为请求停用身份验证。如果您使用的是不支持身份验证的自定义端点，应设置此字段。如果您将 Cloud Storage FUSE 与公共存储桶搭配使用，也应设置此字段。	布尔值：true、false。	false
key-file	指定用于对发送到 Cloud Storage 的请求进行身份验证的凭据 JSON 密钥文件的绝对路径。默认情况下，Cloud Storage FUSE 使用应用默认凭据对请求进行身份验证。	网址。	如果未设置此字段，系统将使用应用默认凭证。
reuse-token-from-url	指定是否重复使用从 --token-url 获取的令牌。	布尔值：true、false。	true
token-url	指定不存在 --key-file 时用于获取访问令牌的网址。	网址。
billing-project	指定在访问已装载的存储桶时要用于结算的项目。在装载启用了请求者付款功能的存储桶时，此字段通常是必需的。	表示“项目 ID”的字符串值。	""
client-protocol	指定用于与 Cloud Storage 后端进行通信的协议。	http1 表示 HTTP/1.1 http2 表示 HTTP/2 grpc 表示 gRPC。如需将 gRPC 与 Cloud Storage FUSE 搭配使用，我们建议使用 Cloud Storage FUSE 2.10.0 版或更高版本。	http1
custom-endpoint	指定用于提取数据的备用自定义端点。 自定义端点必须支持与 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。
http-client-timeout	指定 Cloud Storage FUSE HTTP 客户端在超时之前等待多长时间才能收到来自服务器的响应。	时长，例如：1h10m10s 表示 1 小时 10 分钟 10 秒。0s 指定不超时。	0s，表示不超时
limit-bytes-per-sec	指定供 Cloud Storage FUSE 可从 Cloud Storage 中读取数据的带宽限制（根据 30 秒的时间段计量得出）。		"-1"，表示没有限制。
limit-ops-per-sec	指定每秒执行的操作数限制（根据 30 秒的时间段计量得出）。	浮点数。-1 指定无限制。	"-1"
max-conns-per-host	指定每个服务器允许的 TCP 连接数上限。 此选项在 --client-protocol 设置为 http1 时生效。		0
max-idle-conns-per-host	指定每个服务器允许的空闲连接数上限。 此选项在 --client-protocol 设置为 http1 时生效。	介于 0 和 2147483647 之间的整数。 0 指定 TCP 连接数量不受限制。	0
sequential-read-size-mb	指定要从 Cloud Storage 下载的数据的区块大小，以兆字节 (MB) 为单位。	介于 1 和 1024 之间的整数。	200
implicit-dirs	隐式包含文件夹和托管文件夹。 如需了解详情，请参阅 Cloud Storage FUSE GitHub 文档中的文件和目录。	布尔值：true、false。	false
kernel-list-cache-ttl-secs	启用列表缓存，并定义缓存列表条目的存留时间 (TTL)（以秒为单位）。列表缓存保留在页面缓存的内存中，由内核根据可用内存进行控制。	表示秒数的整数，例如：10（10 秒）。 0：停用列表缓存。 -1：跳过条目到期时间，在列表响应可用时始终从缓存返回列表响应。	0
ignore-interrupts	指示 Cloud Storage FUSE 忽略系统中断信号，例如由 Control+C 触发的 SIGINT。这样可以防止信号终止进行中的操作。	布尔值：true、false。	true
dir-mode	目录的权限位，以八进制表示。	介于 000 和 777 之间的整数（含边界值）。	"755"
file-mode	指定文件的权限位，以八进制表示。	介于 000 和 777 之间的整数（含边界值）。	"644"
fuse-options	指定其他系统特定的装载选项。
gid	指定所有 inode 的群组标识符 (GID) 所有者。	表示 GID 的整数。 -1：使用调用方的 GID。	-1
rename-dir-limit	允许重命名包含的后代目录少于指定限制的目录。	介于 0 和 2147483647 之间的整数。	0
temp-dir	指定在上传到 Cloud Storage 之前用于暂存写入数据的临时目录的路径。	字符串路径，例如："/mnt/ssd/example-user-gcsfuse-temp-dir"。	"/tmp"
uid	指定所有 inode 的用户标识符 (UID) 所有者。	表示 UID 的整数。 -1：使用调用方的 UID。	-1
foreground	在前台运行 gcsfuse 命令。	布尔值：true、false。	false
max-retry-attempts	指定操作失败时重试操作的最大次数，以防止无限重试循环。	表示重试次数上限的整数，例如：10。 0：允许无限次重试。	0
max-retry-sleep	使用指数退避算法指定在重试循环中允许 Cloud Storage FUSE 休眠的时长上限。退避时长超过指定的时长上限后，重试会以指定的时长上限继续。	时长，例如：1h5m50s（1 小时 5 分钟 50 秒）或 60s（60 秒）。	30s
multiplier	指定连续重试之间的指数退避算法的乘数。	浮点数	"2"
cloud-metrics-export-interval-secs	以指定的时间间隔将指标导出到 Cloud Monitoring。 注意：使用此字段需要进行额外设置。如需了解详情，请参阅设置 Cloud Monitoring 导出器。	表示以秒为单位的值的整数，例如：10（10 秒）。0 指定禁止导出。	0
prometheus-port	在指定的端口和 /metrics 路径上公开 Prometheus 指标端点。 注意：使用此字段需要进行额外设置。如需了解详情，请参阅设置 Prometheus 导出器。	表示您要指定的端口的整数。	0
log-mutex	当互斥锁持续时间过长时，输出调试消息。如果指定了此字段，日志的严重级别会自动设置为 trace，这包括轨迹日志、调试日志、信息日志、警告日志和错误日志。	布尔值：true、false。	false
exit-on-invariant-violation	检测到内部变体违规行为时退出程序。	布尔值：true、false。	false
enable-streaming-writes	控制写入路径流程，以便在写入数据时将其直接上传到 Cloud Storage，而不是在本地完全暂存写入内容，然后在执行 close() 或 fsync() 时上传。如需详细了解流式写入，请参阅 Cloud Storage FUSE GitHub 文档中的读取/写入。	布尔值：true、false。	true
global-max-blocks	指定可用于跨所有文件进行流式写入的数据块的最大数量。默认情况下，每个文件使用一个 32 MiB 数据块。	整数 0：停用流式写入。 -1：将值设置为无限个块。	适用于资源有限的低规格机器的默认值：4 适用于具有大量资源的高规格机器的默认值：1600
enable-buffered-read	指定将 Cloud Storage 对象的部分内容异步预提取到内存缓冲区中，从而可以从缓冲区进行后续读取操作，而无需进行网络调用。	布尔值：true、false。	false
read:global-max-blocks	指定在所有文件句柄间可用于缓冲读取的最大块数。 注意：使用此字段需要启用 enabled-buffered-read 字段。如需了解详情，请参阅 enable-buffered-read 字段。	整数 0：停用缓冲读取。 -1：将值设置为无限个块。	40
profile	应用一组预定义且经过优化的 Cloud Storage FUSE 配置，用于缓存、线程处理和缓冲区大小，以帮助您针对特定工作负载类型（例如训练、部署和检查点设置）实现高性能。如需详细了解基于工作负载类型的每种预定义配置，请参阅面向 AI/ML 工作负载的基于配置文件的配置。	一个字符串，例如 "aiml-checkpointing"。 "aiml-training"：优化了性能，可实现对大型数据集的高吞吐量读取，并防止 Cloud GPU 和 Cloud TPU 硬件等待数据。 aiml-checkpointing：通过大幅缩短保存数 GB 检查点所需的时间，优化大型文件的高吞吐量写入性能，从而最大限度地减少训练暂停时间。 aiml-serving：通过简化数据访问和应用缓存机制，优化服务工作负载的性能。	""

返回页首