# 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/..#基本挂载配置)。

{% 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)提供。请参阅如何[将秘密添加为文件](https://documentation.alluxio.io/ee-ai-cn/ufs)。
{% 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 选项。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-cn/ufs/gcs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.