gcsfuse CLI

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

摘要

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

其中：

  • GLOBAL_OPTIONS 是用于控制装载的设置方式以及 Cloud Storage FUSE 行为方式的选项。

  • BUCKET_NAME 是要装载的存储桶的名称。例如 my-mount-bucket。可选。从此命令中排除存储桶名称以执行动态装载。

  • MOUNT_POINT 是装载存储桶的本地目录。例如 /path/to/mount/point。

说明

gcsfuse CLI 用于将 Cloud Storage 存储桶作为文件系统装载到本地机器上。

全局选项

选项 说明 有效值 默认值
--anonymous-access 停用请求的身份验证。如果您使用的是不支持身份验证的自定义端点，则应设置此选项。如果您将 Cloud Storage FUSE 与公共存储分区搭配使用，也应设置此选项。 布尔值：true、false。 false
--app-name 装载的应用名称。 字符串值，例如：my-bucket-mount。 ""
--billing-project 指定在访问已装载的存储桶时要用于结算的项目。在装载启用了请求者付款功能的存储分区时，此选项通常是必需的。 表示项目 ID 的字符串值。 ""
--cache-dir

指定用于存储文件缓存数据的目录。

如需了解如何启用文件缓存，请参阅使用文件缓存。

 路径，例如：/tmp/gcsfuse-cache-path。 ""
--client-protocol 指定用于与 Cloud Storage 后端进行通信的协议。
  • http1（适用于 HTTP/1.1）
  • http2（适用于 HTTP/2）
  • 适用于 gRPC 的 grpc
 http1
--config-file 指定要用于配置 Cloud Storage FUSE 行为的配置文件的路径。 路径，例如：/etc/gcsfuse.yaml。 ""
--custom-endpoint 指定用于提取数据的备用自定义端点。 自定义端点必须支持与 Cloud Storage JSON 端点 https://storage.googleapis.com/storage/v1 等效的资源和操作。 如果未指定自定义端点，Cloud Storage FUSE 会使用全球 Cloud Storage JSON API 端点 https://storage.googleapis.com/storage/v1。 如果您指定的自定义端点不支持身份验证，请将 --anonymous-access 标志设置为 true 以绕过身份验证。 端点，例如：http://localhost:443/storage/v1。 ""
--debug_fuse（已弃用） 启用与 FUSE 相关的调试输出。此选项已被 --log-severity 选项取代。如需启用调试输出，请将 --log-severity 选项设置为 trace，这包括轨迹日志、调试日志、信息日志、警告日志和错误日志。 布尔值：true、false。 false
--debug_gcs（已弃用） 输出 Cloud Storage 请求和时间信息。此选项已被 --log-severity 选项取代。如需启用调试输出，请将 --log-severity 选项设置为 trace，这包括轨迹日志、调试日志、信息日志、警告日志和错误日志。 布尔值：true、false。 false
--debug_invariants 检测到内部不变违规行为时退出程序。 布尔值：true、false。 false
--debug_mutex 当互斥锁持续时间过长时，输出调试消息。 如果指定了此选项，日志的严重级别会自动设置为 trace，这包括轨迹日志、调试日志、信息日志、警告日志和错误日志。 布尔值：true、false。 false
--dir-mode 目录的权限位，以八进制表示。 介于 000 和 777（包括这两个数值）之间的整数。 755
--enable-nonexistent-type-cache 如果在 Cloud Storage 中找不到某个文件，则会创建一个类型为 NonexistentType 的类型缓存条目。如果文件是在 Cloud Storage 中创建的，但文件的 NonexistentType 条目已缓存，则在从类型缓存中移除 NonexistentType 条目之前，Cloud Storage FUSE 无法请求该文件。 布尔值：true、false。 false
--file-cache-cache-file-for-range-read 确定从非零偏移量完成首次读取时，是否应异步下载完整对象并将其存储在 Cloud Storage FUSE 缓存目录中。如果您打算执行多次随机读取或部分读取，则应将此选项设置为 true。

注意：如果您从偏移 0 开始执行部分读取，则 Cloud Storage FUSE 会异步下载并缓存整个对象。

 布尔值：true、false。 false
--file-cache-download-chunk-size-mb 指定每个 goroutine 将对象下载到文件缓存时向 Cloud Storage 发出的每个读取请求的大小（以 MiB 为单位）。 整数 50
--file-cache-enable-parallel-downloads

通过使用文件缓存目录作为预提取缓冲区，并使用多个工作器并行下载大型文件，从而加快大型文件的读取速度。如需详细了解并行下载并配置其支持的属性，请参阅使用并行下载提升读取性能。

如需使用并行下载功能，您必须先启用文件缓存。

 布尔值：true、false。 false
--file-cache-max-parallel-downloads 在任何给定时间，所有文件下载作业可同时生成的 goroutine 数上限。
  • 整数
  • -1：指定无限并行下载。
  • 0：停用并行下载。仅当未传递 --enable-parallel-downloads 或以 false 的形式传递 --enable-parallel-downloads 时才可使用。
  • >0：指定不设上限。Cloud Storage FUSE 会根据机器配置中指定的可生成的 goroutine 数量上限，在内部限制此值。
 机器上的 CPU 核心数量的两倍或 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 隐式包含文件夹和托管文件夹。 如需了解详情，请参阅 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 严重级别。
  • trace
  • debug
  • info
  • warning
  • error
  • off：停用所有日志记录。
 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-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。 ""
--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
--stackdriver-export-interval 以指定的时间间隔将指标导出到 Stackdriver。 时长，例如：1h5m50s（1 小时 5 分钟 50 秒）。0s 指定无导出。 0s
--stat-cache-capacity（已弃用） 指定统计信息缓存可以包含的条目数。此选项已被 --stat-cache-max-size-mb 选项取代。 整数 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 选项取代。 时长，例如：20s（20 秒）。 60s
--temp-dir 指定在上传到 Cloud Storage 之前用于暂存写入数据的临时目录的路径。 路径，例如：/mnt/ssd/example-user-gcsfuse-temp-dir。 /tmp
--token-url 指定不存在 --key-file 时用于获取访问令牌的网址。 网址。 ""
--type-cache-ttl (deprecated) 指定缓存目录 inode 中的名称与文件或目录之间的映射的时长（以秒为单位）。此选项已被 --metadata-cache-ttl-secs 选项取代。 时长（以秒为单位），例如：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