> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Google Cloud Storage

> 通过 S3 兼容互操作 Endpoint 配置 Google Cloud Storage Bucket 索引。

## 索引内容

Google Cloud Storage 连接器通过 `storage.googleapis.com` 的 S3 兼容互操作 Endpoint 索引一个 GCS Bucket 中的对象。**Path Prefix** 留空时索引整个 Bucket。非空值如果没有以斜杠结尾，会自动补上 `/`，因此 `reports` 会列出 `reports/`，而不是名称相似的 Key。

| 对象行为  | 索引效果                                                      |
| ----- | --------------------------------------------------------- |
| 文件夹标记 | 以 `/` 结尾的 Key 会被跳过。                                       |
| 文本与文档 | 下载的对象会进入 OpenCore 通用文件提取流程。没有提取出文本的对象可能只保留标题；提取失败的对象会被跳过。 |
| 表格    | 运行时文件暂存回调可用时，CSV、TSV 和 XLSX 对象会被暂存并作为表格 Section 索引。       |
| 图片    | 除非部署已启用图片处理，否则图片对象会被跳过。                                   |
| 大小    | 超过 Blob Storage 阈值的对象会被跳过。当前默认值为 20 MiB，除非部署覆盖该值。         |

## 前置条件

* 选择一个 GCS Bucket；需要缩小范围时，选择结束于已批准文件夹边界的 Path Prefix。
* 为能够列出 Bucket 并读取匹配对象的 Google 身份启用并创建 GCS 互操作 HMAC 凭据。
* 创建时安全保存 HMAC Key 的两个部分；之后无法从 Google Cloud 再次取回 Secret。
* 允许连接器 Worker 通过 HTTPS 访问 `storage.googleapis.com`。
* 不要为该连接器准备 Service Account JSON Key、Project ID 或 Region 字段；当前凭据和连接器表单不接受这些值。

## 凭据

| 方式                            | OpenCore 凭据值                                                                      | 说明                                                                                           |
| ----------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| GCS Interoperability HMAC Key | `access_key_id: <GCS_ACCESS_KEY_ID>`、`secret_access_key: <GCS_SECRET_ACCESS_KEY>` | 这是 GCS XML/S3 互操作 API 使用的 HMAC Access ID 和 Secret，不是 AWS Key Pair 或 Service Account JSON 文件。 |

Google Cloud Storage 与 S3 共享 OpenCore 的 Blob 索引实现，但两者不共享凭据合同。GCS 没有 S3 Authentication Method 选择器、Role ARN 或 AWS Region 字段。

## 在 OpenCore 中配置

1. 在 Google Cloud 中创建或启用已批准身份的 HMAC Interoperability Key，并安全记录两个值。
2. 在 OpenCore Admin 后台打开 **Connectors**，选择 **Google Cloud Storage**，然后创建 GCS 凭据。
3. 输入准确的 **Bucket Name**，不要包含 `gs://` 或对象路径。
4. 根据需要输入 **Path Prefix**。使用 `approved/reports` 形式的 Key Path；OpenCore 会将其规范化为 `approved/reports/`。
5. 对受限对象选择 **Private** 并分配 OpenCore 用户组。只有当所有账号都可搜索范围内的每个对象时才使用 **Public**。
6. 设置刷新和清理选项，创建连接器，然后运行首次索引尝试。

## 权限

HMAC 身份需要列出所配置 Bucket/Prefix 的权限，以及读取每个匹配对象的权限。OpenCore 使用这些凭据摄取内容，但不会同步 GCS IAM Policy、Bucket ACL 或 Object ACL。

索引完成后，搜索访问权由连接器的 OpenCore **Private** 用户组或 **Public** 模式决定。任何能访问连接器的用户都能搜索每个已索引对象，即使该用户没有 Google Cloud 访问权。要在 Google Cloud Console 中打开引用，还需要独立的 Google Cloud 授权。

## 验证

1. 验证连接器，并确认它能够列出所配置 Prefix 下的至少一个对象。
2. 运行索引尝试，分别搜索一个近期对象和一个嵌套对象中的文本。
3. 确认规范化 Prefix 之外的 Key 没有出现。
4. 确认超大对象以及关闭图片处理时的图片没有出现。
5. 使用已授权的 Google Cloud 浏览器会话打开引用，确认它指向预期 Bucket 和对象。
6. 测试每个已分配的 OpenCore 用户组，因为搜索时不会重新评估 GCS 权限。

## 故障排除

| 现象                      | 检查项                                                                                       |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| 凭据被拒绝                   | 使用有效的 GCS Interoperability HMAC Access ID 和 Secret，而不是 Service Account JSON Key 或 AWS 凭据。 |
| 验证时出现 `AccessDenied`    | 授予 HMAC 身份列出 Bucket 的权限，并确认 Bucket IAM Policy 或 ACL 没有阻止访问。                               |
| `SignatureDoesNotMatch` | 重新输入相互匹配的 HMAC Access ID 和 Secret；如果 Secret 已丢失，请轮换 HMAC Key。                             |
| `NoSuchBucket` 或 404    | 只输入准确的 Bucket Name，并确认它存在于 HMAC 身份可访问的 Project 中。                                         |
| Prefix 没有返回对象           | 注意 `reports` 会变为 `reports/`；检查 Key 拼写、大小写和该身份的 Prefix 访问权。                                |
| 缺少对象                    | 检查默认 20 MiB 阈值、文件提取日志、图片处理设置和对象 Read 权限。                                                  |
| 用户能搜索其无法在 GCS 打开的对象     | 源 ACL 不同步时这是预期行为。请用 OpenCore 用户组限制连接器，或拆分来源。                                              |

## 相关页面

* [连接器与索引](/opencore/knowledge/connectors)
* [索引设置](/opencore/knowledge/index-settings)