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

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

 路径，例如：/tmp/gcsfuse-cache-path。 空值表示此选项处于停用状态。此 gcsfuse 选项在默认情况下处于停用状态。 ""
指定用于与 Cloud Storage 后端进行通信的协议。
  • http1 表示 HTTP/1.1
  • http2 表示 HTTP/2
  • grpc 表示 gRPC。如需将 gRPC 与 Cloud Storage FUSE 搭配使用，我们建议使用 Cloud Storage FUSE 2.10.0 版或更高版本。
 http1

以指定的时间间隔将指标导出到 Cloud Monitoring。

 表示以秒为单位的值的整数，例如：10（10 秒）。0 指定禁止导出。 0
指定要用于配置 Cloud Storage FUSE 行为的配置文件的路径。 路径，例如：/etc/gcsfuse.yaml。 ""
指定用于提取数据的备用自定义端点。 自定义端点必须支持与 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。 ""
启用 与 FUSE 相关的调试输出。此选项已被 --log-severity gcsfuse 选项取代。如需启用调试输出，请将 --log-severity gcsfuse 选项设置为 trace，这包括轨迹日志、调试日志、信息日志、警告日志和错误日志。 布尔值：true、false。 false
输出 Cloud Storage 请求和时间信息。 此 gcsfuse 选项已被 --log-severity gcsfuse 选项取代。如需启用调试输出，请将 --log-severity gcsfuse 选项设置为 trace，这包括轨迹日志、调试日志、信息日志、警告日志和错误日志。 布尔值：true、false。 false
检测到内部不变违规行为时退出程序。 布尔值：true、false。 false
当互斥锁持续时间过长时，输出调试消息。如果指定了此 gcsfuse 选项，则日志的严重级别会自动设置为 trace，这包括轨迹日志、调试日志、信息日志、警告日志和错误日志。 布尔值：true、false。 false
目录的权限位，以八进制表示。 介于 000 和 777 之间的整数（含边界值）。 755
指定将 Cloud Storage 对象的部分内容异步预提取到内存缓冲区中，从而可以从缓冲区进行后续读取操作，而无需进行网络调用。 布尔值：true、false。 false
如果在 Cloud Storage 中找不到某个文件，则会创建一个类型为 NonexistentType 的类型缓存条目。如果文件是在 Cloud Storage 中创建的，但文件的 NonexistentType 条目已缓存，则在从类型缓存中移除 NonexistentType 条目之前，Cloud Storage FUSE 无法请求该文件。 布尔值：true、false。 false
控制写入路径流程，以便在写入数据时将其直接上传到 Cloud Storage，而不是在本地完全暂存写入内容，然后在执行 close() 或 fsync() 时上传。如需详细了解流式写入，请参阅 Cloud Storage FUSE GitHub 文档中的 Cloud Storage FUSE 语义。 布尔值：true、false。 true

用于指定文件缓存可以使用的大小上限（以 MiB 为单位），并使您能够限制文件缓存可以在其装载的目录中使用的总容量。
  • 整数
  • -1：指定在您为 cache-dir 指定的目录中使用缓存的全部可用容量。仅当传递 cache-dir 时，此值为默认值。
  • 0：停用文件缓存。
 -1
确定从非零偏移量完成首次读取时，是否应异步下载完整对象并将其存储在 Cloud Storage FUSE 缓存目录中。如果您打算执行多次随机读取或部分读取，则应将此 gcsfuse 选项设置为 true。 布尔值：true、false。 false
指定每个 goroutine 将对象下载到文件缓存时向 Cloud Storage 发出的每个读取请求的大小（以 MiB 为单位）。 整数 200

通过使用文件缓存目录作为预提取缓冲区，并使用多个工作器并行下载文件的多个部分，从而加快大型文件的读取速度。

启用文件缓存时，系统会自动启用并行下载。 如需详细了解文件缓存，请参阅 Cloud Storage FUSE 中的文件缓存。

如需详细了解并行下载以及如何配置支持的属性，请参阅并行下载。

 布尔值：true、false。 true
在任何给定时间，所有文件下载作业可同时生成的 goroutine 数上限。
  • 整数
  • -1：指定无限并行下载。
  • 0：停用并行下载。仅当 --enable-parallel-downloads 未传递或以 false 的形式传递时才可使用。
 机器上的 CPU 核心数的两倍或 16（以较高者为准）。
每个文件的并发下载请求数。 整数 16
指定文件的权限位，以八进制表示。 介于 000 和 777 之间的整数（含边界值）。 644
在前台运行 gcsfuse 命令。 布尔值：true、false。 false
指定所有 inode 的群组标识符 (GID) 所有者。
  • 表示 GID 的整数。
  • -1：使用调用方的 GID。
 -1
显示有关 Cloud Storage FUSE 的帮助。 无 无
显示您已安装的 Cloud Storage FUSE 版本。 无 无
指定 Cloud Storage FUSE HTTP 客户端在超时之前等待多长时间才能收到来自服务器的响应。 时长，例如：1h10m10s 表示 1 小时 10 分钟 10 秒。0s 指定不超时。 0s
指示 Cloud Storage FUSE 忽略系统中断信号，例如由 Control+C 触发的 SIGINT。这样可以防止信号终止进行中的操作。 布尔值：true、false。 true
隐式包含文件夹和托管文件夹。 如需了解详情，请参阅 Cloud Storage FUSE GitHub 文档中的文件和目录。 布尔值：true、false。 false

启用列表缓存，并定义缓存列表条目的存留时间 (TTL)（以秒为单位）。列表缓存保留在页面缓存的内存中，由内核根据可用内存进行控制。
  • 表示秒数的整数，例如：10（10 秒）。
  • 0：停用列表缓存。
  • -1：跳过条目到期时间，在列表响应可用时始终从缓存返回列表响应。
 0
指定用于对发送到 Cloud Storage 的请求进行身份验证的凭据 JSON 密钥文件的绝对路径。默认情况下，Cloud Storage FUSE 使用应用默认凭据对请求进行身份验证。 路径，例如：/home/example_user/gcloud-key.json。 如果未设置此选项，系统将使用应用默认凭证。
指定供 Cloud Storage FUSE 可从 Cloud Storage 中读取数据的带宽限制（根据 30 秒的时间段计量得出）。 浮点数。-1 指定无限制。 -1
指定每秒执行的操作数限制（根据 30 秒的时间段计量得出）。 浮点数。-1 指定无限制。 -1
指定用于存储可由 Fluentd 解析的日志的文件。 路径，例如：/tmp/user-example-bucket-gcsfuse-logs.txt。 如果 Cloud Storage FUSE 在前台运行，则为 stdout；如果 Cloud Storage FUSE 在后台运行，则为 syslog
指定日志文件的格式。
  • text
  • json
 json
要保留的轮替日志文件数上限，不包括日志写入的活跃文件。
  • 整数
  • 0：保留所有轮替的日志文件
 10
指定是否使用 gzip 压缩轮替的日志文件。 布尔值：true、false。 true
日志文件在轮替之前可以达到的大小上限，以兆字节 (MB) 为单位。 整数。最小值为 1。 512

您希望 Cloud Storage FUSE 生成日志时所对应的严重级别。严重级别按照从最低严重级别到最高严重级别的顺序排列。例如，如果指定 warning，则 Cloud Storage FUSE 会针对警告和错误生成日志。通常，我们建议使用 info 严重级别。
  • off：停用所有日志记录。
  • error：包含有关严重问题的消息，这些问题会阻止 Cloud Storage FUSE 完成操作，或表明存在失败情况，例如装载失败、权限错误和严重的输入/输出 (I/O) 错误。
  • warning：包含指示潜在问题的消息，这些问题虽然不严重，但如果不解决，可能会导致其他问题。潜在问题包括非致命连接问题、弃用警告、可能导致性能略微下降的资源争用，以及针对暂时性故障的重试。此严重级别还包括 error 严重级别中提供的信息。
  • info：包含常规日志记录信息，例如启动和关闭消息，或有关成功装载操作、进度更新和配置设置的信息。此严重程度级别还包括有关 warning 和 error 严重程度级别的信息。