为工作器池配置 Cloud Storage 卷装载

本页面介绍如何使用 Cloud Run 卷装载将 Cloud Storage 存储桶作为存储卷进行装载。

在 Cloud Run 中将存储桶作为卷进行装载会将存储桶内容以文件的形式呈现在容器文件系统中。将存储桶作为卷装载后，您可以使用编程语言的文件系统操作和库（而不是使用 Google API 客户端库）来访问该存储桶，就像访问本地文件系统上的目录一样。

您可以将卷装载为只读卷，还可以为卷指定装载选项。

内存要求

Cloud Storage 卷装载使用 Cloud Run 容器内存执行以下活动：

对于所有 Cloud Storage FUSE 缓存，Cloud Run 默认使用存留时间 (TTL) 为 60 秒的统计信息缓存设置。统计信息缓存的默认大小上限为 32 MB，类型缓存的默认大小上限为 4 MB。
读取时，Cloud Storage FUSE 除了使用统计信息和类型缓存外，还会额外占用内存，例如，每个所读取的文件会使用 1 MiB 的数组，goroutine 也会使用内存。
写入 Cloud Storage 时，整个文件会先暂存到 Cloud Run 内存中，然后文件才会写入 Cloud Storage。

限制

由于 Cloud Run 使用 Cloud Storage FUSE 进行此卷装载，因此在将 Cloud Storage 存储桶作为卷进行装载时，有一些注意事项：

Cloud Storage FUSE 不会为对同一文件的多次写入提供并发控制（文件锁定）。如果多次写入操作尝试替换某个文件，则最后一次写入的内容会生效，而先前写入的所有内容都会丢失。
Cloud Storage FUSE 不是完全符合 POSIX 标准的文件系统。如需了解详情，请参阅 Cloud Storage FUSE 文档。

不允许的路径

Cloud Run 不允许您将卷装载到 /dev、/proc 或 /sys，以及它们的子目录。

准备工作

您需要一个 Cloud Storage 存储桶来作为卷进行装载。

如需实现对 Cloud Storage 的最佳读/写性能，请参阅优化 Cloud Storage FUSE 网络带宽性能。

所需的角色

如需获得配置 Cloud Storage 卷装载所需的权限，请让您的管理员为您授予以下 IAM 角色：

Cloud Run 工作器池的 Cloud Run Developer (roles/run.developer) 角色
服务身份的 Service Account User (roles/iam.serviceAccountUser) 角色

如需获得服务身份访问文件和 Cloud Storage 存储桶所需的权限，请让您的管理员为服务身份授予以下 IAM 角色：

Storage Admin (roles/storage.admin)

如需详细了解 Cloud Storage 角色和权限，请参阅适用于 Cloud Storage 的 IAM。

如需查看与 Cloud Run 关联的 IAM 角色和权限的列表，请参阅 Cloud Run IAM 角色和 Cloud Run IAM 权限。如果您的 Cloud Run 工作器池与Google Cloud API（例如 Cloud 客户端库）进行交互，请参阅服务身份配置指南。如需详细了解如何授予角色，请参阅部署权限和管理访问权限。

装载 Cloud Storage 卷

您可以在不同的装载路径中装载多个存储桶。您还可以跨容器使用相同或不同的装载路径将卷装载到多个容器。

如果您使用多个容器，请先指定卷，然后为每个容器指定卷装载。

您可以在创建新的工作器池或部署新的修订版本时使用 Google Cloud CLI 为 Cloud Run 工作器池配置 Cloud Storage 卷：

gcloud

如需添加卷并装载，请运行以下命令：
```
gcloud beta run worker-pools update WORKER_POOL \
  --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
  --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH
```
您需要进行如下替换：
- 将 WORKER_POOL 替换为工作器池的名称。
- 将 MOUNT_PATH 替换为您用于装载卷的相对路径，例如 /mnt/my-volume。
- 将 VOLUME_NAME 替换为您要用于卷的任何名称。VOLUME_NAME 值用于将卷映射到卷装载。
- 将 BUCKET_NAME 替换为 Cloud Storage 存储桶的名称。

如需将卷装载为只读卷，请运行以下命令：

gcloud beta run worker-pools update WORKER_POOL \
   --add-volume=name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,readonly=true

如果您使用多个容器，请先指定卷，然后为每个容器指定卷装载：

gcloud beta run worker-pools update WORKER_POOL \
   --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
   --container=CONTAINER_1 \
   --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH \
   --container=CONTAINER_2 \
   --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH2

查看工作器池的环境变量配置

在 Google Cloud 控制台中，前往 Cloud Run：

转到 Cloud Run
点击工作器池以显示已部署的工作器池列表。
点击要检查的工作器池，以显示其详细信息窗格。
点击容器标签页以显示工作器池容器配置。

读取和写入卷

如果您使用 Cloud Run 卷装载功能，则可以使用编程语言中用于在本地文件系统上读写文件的相同库来访问已装载的卷。

如果您使用的是期望数据存储在本地文件系统中并使用常规文件系统操作来访问数据的现有容器，此方法会特别有用。

以下代码段假定一个 mountPath 设置为 /mnt/my-volume 的卷装载。

Nodejs

使用文件系统模块创建新文件或附加到卷 /mnt/my-volume 中的现有文件：

var fs = require('fs');
fs.appendFileSync('/mnt/my-volume/sample-logfile.txt', 'Hello logs!', { flag: 'a+' });

Python

写入保存在卷 /mnt/my-volume 中的文件：

f = open("/mnt/my-volume/sample-logfile.txt", "a")

Go

使用 os 软件包创建一个保存在卷 /mnt/my-volume 中的新文件：

f, err := os.Create("/mnt/my-volume/sample-logfile.txt")

Java

使用 Java.io.File 类在卷 /mnt/my-volume 中创建日志文件：

import java.io.File;
File f = new File("/mnt/my-volume/sample-logfile.txt");

使用装载选项进行卷配置

您可以视情况使用装载选项来配置卷装载的各种属性。借助可用的装载选项，您可以配置缓存设置、装载特定目录、启用调试日志记录以及执行其他行为。

指定装载选项

您可以使用 Google Cloud CLI、YAML 或 Terraform 指定装载选项。在 Google Cloud CLI 中，装载选项以英文分号 (;) 分隔；在 YAML 中，以英文逗号分隔，如下方标签页所示：

gcloud

如需添加卷并使用装载选项进行装载，请运行以下命令：

gcloud beta run worker-pools update WORKER_POOL \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="OPTION_1=VALUE_1;OPTION_N=VALUE_N" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

您需要进行如下替换：

将 WORKER_POOL 替换为工作器池的名称。
将 VOLUME_NAME 替换为您要用于卷的任何名称。VOLUME_NAME 值用于将卷映射到卷装载。
将 BUCKET_NAME 替换为 Cloud Storage 存储桶的名称。
将 OPTION_1 替换为第一个装载选项。请注意，您可以根据需要指定任意数量的装载选项，并使用英文分号分隔每个装载选项和值对。
将 VALUE_1 替换为第一个装载选项所需的设置。
将 OPTION_N 替换为下一个装载选项。
将 VALUE_N 替换为下一个装载选项的设置。
将 MOUNT_PATH 替换为您用于装载卷的相对路径，例如 /cache。

常用的装载选项

装载选项通常用于以下目的：

配置缓存设置
仅装载 Cloud Storage 存储桶中的特定目录
配置卷的所有权（uid、gid）
关闭隐式目录
指定调试日志记录级别。

配置缓存设置

您可以通过设置与缓存相关的装载选项来更改卷的缓存设置。下表列出了各项设置以及默认的 Cloud Run 值：

缓存设置	说明	默认值
`metadata-cache-ttl-secs`	缓存元数据条目的存留时间 (TTL)（以秒为单位）。例如 `metadata-cache-ttl-secs=120s`。如需使用最新的文件，请指定值 `0`。如需始终使用缓存版本，请指定值 `-1`。如需了解详情，请参阅配置缓存失效。	60
`stat-cache-max-size-mb`	统计信息缓存可以使用的大小上限（以兆比字节 [MiB] 为单位）。统计信息缓存始终完全保留在内存中，这会影响内存消耗。如果您的工作负载最多涉及 20,000 个文件，请指定值 `32`。如果您的工作负载使用的文件数超过 20,000 个，则每增加 6,000 个文件，需将大小值增加 `10`，其中统计信息缓存平均为每个文件使用 1,500 MiB。如需让统计信息缓存根据需要动态使用内存，请指定值 `-1`。如需停用统计信息缓存，请指定值 `0`。	32
`type-cache-max-size-mb`	类型缓存可以使用的每个目录的大小上限（以 MiB 为单位）。类型缓存始终完全保留在内存中，这会影响内存消耗。如果您要装载的存储桶的单个目录中的文件数上限不超过 20,000，请指定值 `4`。如果您要装载的单个目录中的文件数上限超过 20,000，则每增加 5,000 个文件，应将值增加 `1`，平均每个文件大约使用 200 个字节。如需让类型缓存根据需要动态使用内存，请指定值 `-1`。如需停用类型缓存，请指定值 `0`。	4

以下 Google Cloud CLI 命令会将 metadata-cache-ttl-secs 设置为 120 秒，并将统计信息和类型缓存容量分别增加到 52 和 7 MiB：

gcloud beta run worker-pools update WORKER_POOL \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="metadata-cache-ttl-secs=120;stat-cache-max-size-mb=52;type-cache-max-size-mb=7" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

您需要进行如下替换：

将 WORKER_POOL 替换为工作器池的名称。
将 VOLUME_NAME 替换为您要用于卷的任何名称。VOLUME_NAME 值用于将卷映射到卷装载。
将 BUCKET_NAME 替换为 Cloud Storage 存储桶的名称。
将 MOUNT_PATH 替换为您用于装载卷的相对路径，例如 /cache。

启用调试日志记录

默认情况下，Cloud Storage FUSE 会记录严重级别为 Info 或更高级别的事件。您可以使用以下任一日志严重级别（按从低到高的顺序列出）更改日志记录设置：

trace
debug
info
warning
error
如需关闭所有日志记录，请指定值 off。

当您指定严重级别后，Cloud Storage FUSE 会为严重级别等于或高于所指定级别的事件生成日志。例如，如果指定 warning 级别，Cloud Storage FUSE 会针对警告和错误生成日志。

将日志严重级别设置为高于 info 的级别可能会影响性能并生成大量日志记录数据，因此我们建议您仅在需要时才执行此操作。

以下命令行会开启调试日志记录：

gcloud beta run worker-pools update WORKER_POOL \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="log-severity=debug" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

您需要进行如下替换：

将 WORKER_POOL 替换为工作器池的名称。
将 VOLUME_NAME 替换为您要用于卷的任何名称。VOLUME_NAME 值用于将卷映射到卷装载。
将 BUCKET_NAME 替换为 Cloud Storage 存储桶的名称。
将 MOUNT_PATH 替换为您用于装载卷的相对路径，例如 /cache。

停用隐式目录

为了让 Cloud Storage 看起来更像标准文件系统，Cloud Run 在装载 Cloud Storage 存储桶时默认启用隐式目录。您可以使用 implicit-dirs 装载选项关闭隐式目录。停用隐式目录可以提高性能和降低费用，但会影响兼容性。

借助隐式目录功能，Cloud Run 可以识别文件名模仿目录结构（例如 /mydir/myfile.txt）的现有 Cloud Storage 文件。如果您停用隐式目录，Cloud Run 将无法列出或读取此类文件。

关闭隐式目录可减少对 Cloud Storage 的请求数量，这可能会提高应用性能并节省费用。如需了解详情，请参阅 Cloud Storage FUSE 文件和目录文档。

以下命令行会停用隐式目录：

gcloud beta run worker-pools update WORKER_POOL \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="implicit-dirs=false" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

您需要进行如下替换：

将 WORKER_POOL 替换为工作器池的名称。
将 VOLUME_NAME 替换为您要用于卷的任何名称。VOLUME_NAME 值用于将卷映射到卷装载。
将 BUCKET_NAME 替换为 Cloud Storage 存储桶的名称。
将 MOUNT_PATH 替换为您用于装载卷的相对路径，例如 /cache。

装载 Cloud Storage 存储桶内的特定目录

默认情况下，Cloud Run 会装载整个 Cloud Storage 存储桶，这会让 Cloud Run 工作器池有权访问存储桶的所有内容。在某些情况下，您可能只想装载特定目录。例如，如果存储桶包含大量文件，则装载特定目录可以提高性能。

您还可以出于隔离目的实现此功能，以便让不同的工作器池有权访问存储桶中的不同目录。

以下命令行会指定要装载的目录：

gcloud beta run worker-pools update WORKER_POOL \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="only-dir=images" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

您需要进行如下替换：

将 WORKER_POOL 替换为工作器池的名称。
将 VOLUME_NAME 替换为您要用于卷的任何名称。VOLUME_NAME 值用于将卷映射到卷装载。
将 BUCKET_NAME 替换为 Cloud Storage 存储桶的名称。
将 MOUNT_PATH 替换为您用于装载卷的相对路径，例如 /cache。

设置卷 `UID` 和 `GID`

使用 uid 和 gid 装载选项可更改卷的用户标识符和群组标识符。如果您想将文件的所有权设置为与一个或多个运行中容器的身份相匹配的特定用户或群组，则此做法非常有用。默认情况下，卷归根用户所有。

以下命令行会设置 uid 和 gid：

gcloud beta run worker-pools update WORKER_POOL \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="uid=UID;gid=GID" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

您需要进行如下替换：

将 WORKER_POOL 替换为工作器池的名称。
将 VOLUME_NAME 替换为您要用于卷的任何名称。VOLUME_NAME 值用于将卷映射到卷装载。
将 BUCKET_NAME 替换为 Cloud Storage 存储桶的名称。
- 将 MOUNT_PATH 替换为您用于装载卷的相对路径，例如 /cache。

设置其他装载选项

以下是 Cloud Run 支持的所有装载选项的完整列表。

implicit-dirs
only-dir
rename-dir-limit

调试

debug_fuse_errors
debug_fuse
debug_gcs
debug-invariants
debug_mutex

缓存

stat-cache-capacity
stat-cache-ttl
type-cache-ttl
enable-nonexistent-type-cache

权限

uid
gid
file-mode
dir-mode

其他

billing-project
client-protocol
experimental-enable-json-read
experimental-opentelemetry-collector-address
http-client-timeout
limit-bytes-per-sec
limit-ops-per-sec
max-conns-per-host
max-idle-conns-per-host
max-retry-sleep
-o
retry-multiplier
sequential-read-size-mb
stackdriver-export-interval

如需查看受支持的装载选项的完整文档，请参阅 Cloud Storage FUSE 命令行装载选项。

优化 Cloud Storage FUSE 网络带宽性能

如需提高读写性能，请使用直接 VPC 将 Cloud Run 工作器池连接到 VPC 网络，并通过 VPC 网络路由所有出站流量。您可以使用以下方案之一来执行此操作：

启用专用 Google 访问通道，并确保将 vpc-egress 参数设置为 all-traffic。
使用“网络最佳实践”页面介绍的方案之一（在发送到 Google API 的内部流量部分中）。

容器启动时间和 Cloud Storage FUSE 装载

使用 Cloud Storage FUSE 可能会略微增加 Cloud Run 容器的冷启动时间，因为 Cloud Run 会在启动容器之前开始装载卷。只有在 Cloud Storage FUSE 成功装载后，容器才会启动。

请注意，只有在与 Cloud Storage 建立连接后，Cloud Storage FUSE 才会成功装载卷。任何网络延迟都可能会影响容器的启动时间。相应地，如果连接尝试失败，Cloud Storage FUSE 将无法装载，并且 Cloud Run 工作器池将无法启动。此外，如果 Cloud Storage FUSE 的装载时间超过 30 秒，Cloud Run 工作器池将无法启动，因为 Cloud Run 执行所有装载的总超时为 30 秒。

Cloud Storage FUSE 性能特征

如果您定义了两个卷，每个卷都指向不同的存储桶，系统将启动两个 Cloud Storage FUSE 进程。装载和进程并行进行。

使用 Cloud Storage FUSE 的操作会受到网络带宽的影响，因为 Cloud Storage FUSE 使用 Cloud Storage API 与 Cloud Storage 进行通信。如果网络带宽较低，某些操作（例如列出存储桶的内容）可能会变慢。同样，读取大型文件也可能需要一段时间，因为这也受网络带宽的限制。

当您写入存储桶时，Cloud Storage FUSE 会在内存中完全暂存对象。这意味着，写入大文件受容器实例可用内存量的限制（容器内存上限为 32 GiB）。

只有在您执行 close 或 fsync 操作时，写入内容才会 flush 到存储桶：完整对象随后会上传到存储桶。将对象完全重新上传到存储桶的唯一例外是文件附加了内容且文件大小为 2 MiB 或更大。

如需了解详情，请参阅以下资源：

清除并移除卷和卷装载

您可以清除所有卷和卷装载，也可以移除个别卷和卷装载。

清除所有卷和卷装载

如需从单容器工作器池中清除所有卷和卷装载，请运行以下命令：

gcloud beta run worker-pools update WORKER_POOL \
    --clear-volumes
    --clear-volume-mounts

如果您有多个容器，请遵循边车 CLI 惯例来清除卷和卷装载：

gcloud beta run worker-pools update WORKER_POOL \
    --container=container1 \
    --clear-volumes
    -–clear-volume-mounts \
    --container=container2 \
    --clear-volumes \
    -–clear-volume-mounts

移除个别卷和卷装载

如需移除某个卷，您还必须移除使用该卷的所有卷装载。

如需移除个别卷或卷装载，请使用 remove-volume 和 remove-volume-mount 标志：

gcloud beta run worker-pools update WORKER_POOL \
    --remove-volume VOLUME_NAME \
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH

为工作器池配置 Cloud Storage 卷装载 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

内存要求

限制

不允许的路径

准备工作

所需的角色

装载 Cloud Storage 卷

gcloud

查看工作器池的环境变量配置

读取和写入卷

Nodejs

Python

Go

Java

使用装载选项进行卷配置

指定装载选项

gcloud

常用的装载选项

配置缓存设置

启用调试日志记录

停用隐式目录

装载 Cloud Storage 存储桶内的特定目录

设置卷 UID 和 GID

设置其他装载选项

优化 Cloud Storage FUSE 网络带宽性能

容器启动时间和 Cloud Storage FUSE 装载

Cloud Storage FUSE 性能特征

清除并移除卷和卷装载

清除所有卷和卷装载

移除个别卷和卷装载

为工作器池配置 Cloud Storage 卷装载

设置卷 `UID` 和 `GID`