Cloud Storage FUSE CLI

本文档介绍用于与 Cloud Storage FUSE 交互的 gcsfuse 命令选项。如果您使用 Cloud Storage FUSE CSI 驱动程序将存储桶装载到 Google Kubernetes Engine 中的本地文件系统，请参阅 Cloud Storage FUSE CSI 驱动程序的装载选项。

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。可选。从此命令中排除存储桶名称以执行动态装载。

• MOUNT_POINT 是装载存储桶的本地目录。例如 /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 表示 HTTP/2 grpc 表示 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 条目已缓存，则在从类型缓存中移除 NonexistentType 条目之前，Cloud Storage FUSE 无法请求该文件。	布尔值：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 虚拟机（包括独立 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 的群组标识符 (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	指定用于对发送到 Cloud Storage 的请求进行身份验证的凭据 JSON 密钥文件的绝对路径。默认情况下，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。	如果 Cloud Storage FUSE 在前台运行，则为 stdout；如果 Cloud Storage FUSE 在后台运行，则为 syslog
--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：允许无限负统计信息缓存，并停用 TTL 到期。	5
--metadata-cache-ttl-secs	定义缓存元数据条目的存留时间 (TTL)（以秒为单位）。	表示秒数的整数，例如：30（30 秒）。 -1：跳过 TTL 过期时间，在文件可用时从缓存中传送文件。 0：使用最新的文件。使用此值会发出 Get 元数据调用，以确保缓存中文件的对象世代与 Cloud Storage 中存储的文件的对象世代一致。如需了解详情，请参阅配置缓存失效。	60
-o	指定其他系统特定的装载选项。FUSE 中的大多数通用装载选项（例如 suid）受 Cloud Storage FUSE 支持，并且可与 -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 为单位）。统计信息缓存始终完全保留在内存中。	整数。我们建议您执行以下操作： 如果您的工作负载最多涉及 20,000 个文件，请指定 32。 如果您的工作负载超过 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 为单位）。 类型缓存始终完全保留在内存中。	整数。我们建议您执行以下操作： 如果要装载的存储桶的单个目录内文件数量上限包含 20,000 个或更少的文件，请指定 4。 如果您要装载的单个目录中的文件数上限超过 20,000，则每 5,000 个文件，值将增加 1，平均每个文件大约增加 200 个字节。 -1：指定无限制，让类型缓存根据需要使用尽可能多的内存。 0：停用类型缓存。	4
--uid	指定所有 inode 的用户标识符 (UID) 所有者。	表示 UID 的整数。 -1：使用调用方的 UID。	-1
--write-global-max-blocks	指定可用于跨所有文件进行流式写入的数据块数量上限。默认情况下，每个文件使用一个 32 MiB 数据块。	整数 0：停用流式写入。 -1：将值设置为无限个块。	资源有限的低配置机器的默认值：4 高配置且资源充足的机器的默认值：1600

返回页首