# 谷歌云 GCS

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

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 模块基于 Google Cloud API 实现，接受 [Google 应用凭证](https://cloud.google.com/docs/authentication/getting-started)。\
在创建应用凭证时，可以通过定义细粒度的权限来限制对特定存储桶的访问。

## 基本设置

使用 [挂载表操作](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/ufs/pages/vItTjDEwYA3ygh6WezO1#挂载表操作) 添加新的挂载点，指定创建挂载点的Alluxio 路径，并将 GCS 路径指定为 UFS URI。 在挂载操作中，还可以同时指定凭证和配置选项，具体方法请参阅[配置挂载点](https://documentation.alluxio.io/ee-ai-cn/ai-3.6/ufs/pages/vItTjDEwYA3ygh6WezO1#对不同挂载点使用不同的配置)的说明。

以下是通过 Operator 创建挂载点的 `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
```

不使用 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 凭证，则可能不需要该属性，但还是建议明确设置这一属性。

在 Kubernetes 环境中，应将凭证文件作为[secret](https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-files-from-a-pod)提供。\
请参阅如何[以文件形式添加 Secret](/ee-ai-cn/ai-3.6/start/install/install-alluxio-on-kubernetes.md)。

## 进阶设置

### 自定义目录后缀

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

### 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/ai-3.6/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.