S3 连接器把 bucket 里的对象同步进一个已连接文件夹。它用某个 IAM 用户的 access key 对登录，也能配合 S3 兼容的存储使用，只要后者可从公网访问。

本页讲 Web UI。要在纯 REST API 上完成同样的连接、同步文件夹，以及在其上建索引或跑批量任务，见用 API 配置连接器。

为 S3 连接器创建 IAM 用户

给 LlamaCloud 建一个 IAM 用户，并授予它对你要同步的 bucket 的读权限。它需要两个动作：

• 在 bucket 上的 s3:ListBucket，用来查看里面有什么
• 在对象上的 s3:GetObject，用来下载它们

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "LlamaCloudList",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::your-bucket-name"
    },
    {
      "Sid": "LlamaCloudRead",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

如果只想同步某个前缀，可以把这两条语句都收窄到它：给 s3:ListBucket 加上 s3:prefix 条件，并把 GetObject 的资源改成 arn:aws:s3:::your-bucket-name/your-prefix/*。连接器在列举时总会带上这个前缀，因此该条件是有效的。

一组密钥可以喂给任意多个 bucket、任意地域里的文件夹。没有需要填写的地域项；连接器会在你从某个 bucket 创建文件夹时自行找到它所在的地域。

然后为该用户创建一把 access key。AWS 只显示一次 secret，请在关闭页面前复制好。

添加 S3 连接

在 Files → Connections 上点击 Add connection，选择 S3，填写：

字段	必填	该填什么
Access key ID	是	该 IAM 用户的 access key，例如 AKIAIOSFODNN7EXAMPLE
Secret access key	是	创建该密钥时显示的 secret
Endpoint URL	否	用 AWS 就留空。S3 兼容存储填它的基础 URL，例如 https://s3-compatible.example.com

点击 Connect。LlamaCloud 会先拿这把 key 向 AWS 校验再保存：

• AWS S3： 调用 sts:GetCallerIdentity（每个 IAM 用户都能调），并把该用户的 ARN 显示为 Connections 标签上的账号。key 写错会在这里失败；key 有效但读不了你的 bucket，则要到创建文件夹时才失败。
• S3 兼容存储： 调用 ListBuckets，因此这把 key 需要在该存储上有列举 bucket 的权限。账号一栏显示的是 access key ID。

用 S3 兼容存储配合 S3 连接器

把 Endpoint URL 设为该存储的基础 URL，并使用它自己的 access key 对。MinIO 与 Cloudflare R2 都可以这样接。

该 endpoint 必须是能解析到公网地址的 http:// 或 https:// URL。部署在内网或 VPN 后面的 MinIO 无法被访问，连接会被拒绝并提示 “S3 endpoint must resolve to a public address.”

从 S3 连接创建文件夹

在 Files → New folder → Connected folder 里选择你的 S3 连接并填写：

• Bucket（必填），例如 acme-documents
• Prefix（可选），例如 invoices/2024/。只有 key 以它开头的对象会被同步。留空即同步整个 bucket。

你也可以把一个 s3://bucket/prefix/ URI 直接粘进 bucket 输入框，系统会替你拆开。

在文件夹创建之前，连接器会用这把 key 列举一次 bucket。bucket 不存在时你会看到“not found”，key 没有被允许列举时看到的是“access denied”。

S3 连接器的同步方式

每次同步都会把 bucket 与前缀下的内容完整列一遍，并与文件夹里已有的做比对。新对象加入，ETag 变化的对象重新下载，已删除的对象从文件夹移除。零字节的“文件夹标记”对象（key 以 / 结尾）会被跳过。

由于每次同步都是一次完整列举，对象数极多的 bucket 即使毫无变化，同步也更久。把文件夹收窄到某个前缀会有帮助。

S3 连接器的故障排查

提示	该检查什么
”AWS STS rejected this access key pair”	key ID 或 secret 有误，或者这把 key 已被停用。
”s3 bucket ’…’ not found”	bucket 名拼错，或者 bucket 已被删除。
”s3 denied access to bucket ’…’”	IAM 策略缺少该 bucket 上的 s3:ListBucket，或者 s3:prefix 条件与你填的前缀不匹配。
文件夹能同步但文件导入失败	策略缺少 s3:GetObject，或者对象资源未覆盖该前缀。