> For the complete documentation index, see [llms.txt](https://documentation.alluxio.io/ee-ai-cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.alluxio.io/ee-ai-cn/ufs/gcs.md).

# Google GCS

本指南介绍了如何将 Alluxio 配置为使用 [Google Cloud Storage (GCS)](https://cloud.google.com/storage/) 作为底层存储系统。

Google Cloud Storage (GCS) 是 Google Cloud Platform (GCP) 提供的可扩展且持久的对象存储服务。它允许用户存储和检索各种类型的数据，包括非结构化和结构化数据。

有关 GCS 的更多信息，请阅读其[文档](https://cloud.google.com/storage/docs)。

## 先决条件

在开始之前，请确保您已具备下列所需信息：

| `<GCS_BUCKET>`    | [在您的 Google Cloud 帐户中创建一个新存储桶](https://cloud.google.com/storage/docs/creating-buckets) 或使用现有存储桶 |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `<GCS_DIRECTORY>` | 您希望在存储桶中使用的目录，可以通过创建新目录或使用现有目录来实现                                                               |

默认的 GCS UFS 模块（GCS 版本 2）是基于 Google Cloud API 实现的，该 API 接受 [Google 应用程序凭据](https://cloud.google.com/docs/authentication/getting-started)。在创建应用程序凭据时可以定义细粒度的权限，以限制对特定存储桶的访问。

## 基本设置

通用挂载机制和 `UnderFileSystem` CR 字段参考，请参阅[底层存储](https://documentation.alluxio.io/ee-ai-cn/ufs/pages/QHxxAwAliFxrTQ5jOZw7#基本挂载配置)。

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
使用 operator 创建 GCS 挂载点的 `ufs.yaml` 示例：

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: alluxio-gs
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: gs://<GS_BUCKET>/<PATH>
  mountPath: /gs
  mountOptions:
    fs.gcs.credential.path: /path/to/<google_application_credentials>.json
```

凭据文件应作为[秘密](https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-files-from-a-pod)提供。请参阅如何[将秘密添加为文件](/ee-ai-cn/ufs.md)。
{% endtab %}

{% tab title="Docker / 裸机" %}
如果不使用 operator，使用 GCS v2 将 `gs://<GCS_BUCKET>/<GCS_DIRECTORY>` 挂载到 `/gs` 的示例命令：

```shell
bin/alluxio mount add --path /gs/ --ufs-uri gs://<GCS_BUCKET>/<GCS_DIRECTORY> \
  --option fs.gcs.credential.path=/path/to/<google_application_credentials>.json
```

此属性键 `fs.gcs.credential.path` 提供 Google 应用程序凭据 json 文件的路径。请注意，Google 应用程序凭据 json 文件应放置在所有 Alluxio 节点中的相同路径下。如果运行 Alluxio 进程的节点已包含 GCS 凭据，则可能不需要此属性，但始终建议显式设置此属性。
{% endtab %}
{% endtabs %}

## 高级设置

### 自定义目录后缀

目录在 GCS 中表示为以指定后缀命名的零字节对象。可以使用配置参数 `alluxio.underfs.gcs.directory.suffix` 更新目录后缀。

### GCS 分块上传

Alluxio 以并行方式分块上传大文件以提升吞吐量。由于 GCS Java 客户端库未提供原生分块上传 API，各分块将作为临时对象上传，并通过 [GCS 对象合并](https://cloud.google.com/storage/docs/composing-objects)合并为最终对象。最终对象通过服务端原子重命名操作创建，并发读取方不会看到写入中途的数据。临时对象会在上传成功或中止后删除。

分块上传默认启用。小于一个分区大小（最小 5 MiB）的文件始终通过单次上传处理，不受此配置影响。

可通过以下参数调整分块上传行为。

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
在 `AlluxioCluster` spec 中配置：

```yaml
# 在 alluxio-cluster.yaml 中
properties:
  # 启用线程池异步并行上传各分块，提升吞吐量。（默认值：false）
  alluxio.underfs.object.store.multipart.upload.async: "true"
  # 每个分块的大小，最小为 5 MiB。（默认值：16MB）
  alluxio.underfs.gcs.multipart.upload.partition.size: "64MB"
  # 每个 GCSUnderFileSystem 实例的并发分块上传线程数。（默认值：20）
  alluxio.underfs.gcs.multipart.upload.threads: "40"
  # 所有流实例共享的分块缓冲池容量。0 表示不限制。（默认值：64）
  alluxio.underfs.gcs.multipart.upload.buffer.number: "128"
```

{% endtab %}

{% tab title="Docker / 裸机" %}
在 `conf/alluxio-site.properties` 中配置：

```properties
# 启用线程池异步并行上传各分块，提升吞吐量。（默认值：false）
alluxio.underfs.object.store.multipart.upload.async=true

# 每个分块的大小，最小为 5 MiB。（默认值：16MB）
alluxio.underfs.gcs.multipart.upload.partition.size=64MB

# 每个 GCSUnderFileSystem 实例的并发分块上传线程数。（默认值：20）
alluxio.underfs.gcs.multipart.upload.threads=40

# 所有流实例共享的分块缓冲池容量。0 表示不限制。（默认值：64）
alluxio.underfs.gcs.multipart.upload.buffer.number=128
```

{% endtab %}
{% endtabs %}

如果 Alluxio worker 在中止和清理操作执行前崩溃，存储桶中可能残留键名包含 `__mpu_` 的临时对象。可通过键前缀手动清理，或使用匹配 `*__mpu_*` 键名的 [GCS 对象生命周期规则](https://cloud.google.com/storage/docs/lifecycle)自动清理。

## GCS 访问控制

如果启用了 Alluxio 安全性，Alluxio 将强制执行从底层对象存储继承的访问控制。

Alluxio 配置中指定的 GCS 凭据表示一个 GCS 用户。GCS 服务后端检查用户对存储桶和对象的权限以进行访问控制。如果给定的 GCS 用户没有对指定存储桶的访问权限，将引发权限被拒绝错误。启用 Alluxio 安全性后，当元数据首次加载到 Alluxio 命名空间时，Alluxio 会将存储桶 ACL 加载到 Alluxio。

### 从 GCS ACL 到 Alluxio 权限的映射

Alluxio 检查 GCS 存储桶的读/写 ACL 以确定所有者对 Alluxio 文件的权限模式。例如，如果 GCS 用户对底层存储桶具有只读访问权限，则挂载的目录和文件将具有 `0500` 模式。如果 GCS 用户对底层存储桶具有完全访问权限，则挂载的目录和文件将具有 `0700` 模式。

### 通过代理访问 GCS

如果 Alluxio 集群位于公司代理或防火墙之后，Alluxio GCS 集成可能无法使用默认设置访问互联网。

在启动 Alluxio Coordinator和 worker 之前，将以下 java 选项添加到 `conf/alluxio-env.sh`。

```sh
ALLUXIO_COORDINATOR_JAVA_OPTS+=" -Dhttps.proxyHost=<proxy_host> -Dhttps.proxyPort=<proxy_port> -Dhttp.proxyHost=<proxy_host> -Dhttp.proxyPort=<proxy_port> -Dhttp.nonProxyHosts=<non_proxy_host>"
ALLUXIO_WORKER_JAVA_OPTS+=" -Dhttps.proxyHost=<proxy_host> -Dhttps.proxyPort=<proxy_port> -Dhttp.proxyHost=<proxy_host> -Dhttp.proxyPort=<proxy_port> -Dhttp.nonProxyHosts=<non_proxy_host>"
```

`http.nonProxyHosts` 的一个示例值为 `localhost|127.*|[::1]|192.168.0.0/16`。

如果代理需要用户名和密码，请添加 `http.proxyUser`、`https.proxyUser`、`http.proxyPassword` 和 `https.proxyPassword` java 选项。