> 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.

# Amazon S3

> 使用 Prefix 范围、三种凭据模式和明确访问边界配置 Amazon S3 Bucket 索引。

## 索引内容

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 Secret | `authentication_method: access_key`、`aws_access_key_id: <AWS_ACCESS_KEY_ID>`、`aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>` | 使用所提供 Key Pair 创建 boto3 Session。                                                   |
| IAM Role              | `authentication_method: iam_role`、`aws_role_arn: <AWS_ROLE_ARN>`                                                              | Worker 使用其 AWS 环境调用 STS `AssumeRole`，然后刷新临时凭据。                                     |
| Assume Role           | `authentication_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 域名。                |

## 相关页面

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