OpenCore文档与知识连接器

Google Cloud Storage

以 Markdown 格式查看

索引内容

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 Keyaccess_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 用户组限制连接器，或拆分来源。

相关页面