OpenCore文档与知识连接器

Amazon S3

以 Markdown 格式查看

索引内容

S3 连接器会索引一个 Bucket 中 Key 位于所配置 Prefix 下的对象。Prefix 留空时索引整个 Bucket。非空值如果没有以斜杠结尾，会自动补上 /，因此 reports 会将列表范围限定为 reports/，而不是 reports-old.pdf 等 Key。

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

前置条件

  • 选择一个 S3 Bucket；需要缩小范围时，选择结束于已批准文件夹边界的 Key Prefix。
  • 提供能够按该 Prefix 列出 Bucket 并读取匹配对象的 IAM Principal。
  • 使用 IAM Role 时，允许连接器 Worker 的 AWS 身份调用 STS 并代入所配置的 Role ARN。
  • 使用 Assume Role 时，让连接器 Worker 能够通过 AWS Credential Chain 获取 Instance 或 Workload Role。
  • Bucket 位于 GovCloud 等非默认 Partition 时，提供其 AWS Region；否则使用正常的 AWS Region 解析。

凭据

方式OpenCore 凭据值说明
Access Key and Secretauthentication_method: access_key、aws_access_key_id: <AWS_ACCESS_KEY_ID>、aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>使用所提供 Key Pair 创建 boto3 Session。
IAM Roleauthentication_method: iam_role、aws_role_arn: <AWS_ROLE_ARN>Worker 使用其 AWS 环境调用 STS AssumeRole，然后刷新临时凭据。
Assume Roleauthentication_method: assume_role尽管 UI 使用该标签，此模式不提供 Role ARN；boto3 会直接使用 Worker 现有的 Instance 或 Workload Credential。

这些模式仅属于 S3。不要把 S3 Authentication 或 Region 字段复制到 Google Cloud Storage 凭据中。

在 OpenCore 中配置

  1. 在 Admin 后台打开 Connectors，选择 S3，然后选择与 Worker AWS 身份匹配的凭据模式。
  2. 输入准确的 Bucket Name。不要包含 s3:// 或对象路径。
  3. 根据需要输入 Prefix。使用 approved/reports 形式的 Key Path；OpenCore 会将其规范化为 approved/reports/。
  4. Bucket 位于非默认 Partition 或必须显式解析 Region 时，输入 AWS Region。
  5. 对受限对象选择 Private 并分配 OpenCore 用户组。只有当所有账号都可搜索范围内的每个对象时才使用 Public。
  6. 设置刷新和清理选项，创建连接器，然后运行首次索引尝试。

权限

连接器需要针对所配置 Prefix 的 Bucket List 权限，以及对每个待索引对象的 Read 权限。Region 探测还会尝试 Bucket Head 请求，使引用链接能够指向正确的 AWS Console；iam_role 模式还需要 STS AssumeRole 权限。

S3 Bucket Policy、Object ACL、IAM 身份和逐对象授权不会同步到 OpenCore。对象完成索引后，访问权由连接器的 OpenCore Private 用户组或 Public 模式决定。用户还需要独立的 AWS Console 权限才能打开 S3 引用链接。

验证

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

故障排除

现象检查项
InvalidAccessKeyId 或 InvalidToken检查凭据和所配置的 Region/Partition，尤其是 GovCloud。
验证时出现 AccessDenied授予 Bucket List 权限，并确认 Bucket Policy 允许所选 Principal。
SignatureDoesNotMatch检查 Key Pair、Region、时钟和 Endpoint Partition。
NoSuchBucket 或 404只输入准确的 Bucket Name，并确认 Worker 使用正确的 AWS Partition。
Prefix 没有返回对象注意 reports 会变为 reports/；检查 Key 拼写、大小写和 Principal 的 Prefix Condition。
缺少对象检查默认 20 MiB 阈值、文件提取日志、图片处理设置和对象 Read 权限。
引用打开了错误的 AWS Console设置显式 Region 并允许 Bucket Head 探测；GovCloud 使用独立的 Console 域名。

相关页面