AWS S3

AWS S3 通过存储桶名称、所在 region，以及一组 IAM Access Key ID 和 Secret Access Key 连接到 Storage UI。

1. 创建存储桶

打开 S3 控制台，选择 创建存储桶。
输入全局唯一的存储桶名称。
选择一个 AWS 区域（Region），并记下它的代码（如 us-east-1）。Storage UI 需要准确的 region。
保持「阻止公共访问」开启；Storage UI 使用签名凭据访问，不依赖公开访问。
创建存储桶。

2. 创建访问密钥

Storage UI 以一个 IAM 身份进行认证。建议单独创建一个 IAM 用户，以便把权限限定到这个存储桶。

打开 IAM 控制台，创建一个用户（编程访问）。
附加一条仅授予该存储桶访问权限的策略：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::my-bucket"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::my-bucket/*"
    }
  ]
}

为该用户创建 访问密钥（access key），并保存这两个值：

Access Key ID
Secret Access Key

Secret Access Key 只会显示一次。请妥善保存，且切勿通过 NEXT_PUBLIC_* 变量暴露。

如需只读访问，从策略中去掉 s3:PutObject 和 s3:DeleteObject，并设置 STORAGE_1_READ_ONLY=true（见下）。

3. 配置 Storage UI

本地开发时把连接加入 .env.local，或在部署平台的环境变量设置中配置：

STORAGE_1_PROVIDER=s3
STORAGE_1_NAME=AWS S3
STORAGE_1_BUCKET=my-bucket
STORAGE_1_REGION=us-east-1
STORAGE_1_ACCESS_KEY_ID=your-access-key-id
STORAGE_1_SECRET_ACCESS_KEY=your-secret-access-key

把 my-bucket 和 us-east-1 替换为你的存储桶名称和 region。务必填写真实 region：不填时连接会回退到 auto，而 AWS 不接受该值。

4. 配置 CORS

Storage UI 通过预签名 URL 在浏览器中直接上传和预览文件，因此存储桶必须允许你的应用来源（origin）。在存储桶的 权限 -> 跨源资源共享（CORS） 中添加：

[
  {
    "AllowedOrigins": ["https://storage.example.com"],
    "AllowedMethods": ["GET", "PUT", "POST", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3000
  }
]

把 https://storage.example.com 替换为 Storage UI 实际运行的来源（本地开发为 http://localhost:3000）。不配置时，列出存储桶仍然可用，但上传和文件预览会因 CORS 报错而失败。

5. 可选设置

当密钥只有读取权限，或不希望用户修改对象时，开启只读模式：

STORAGE_1_READ_ONLY=true

如果存储桶通过公开域名或 CloudFront 分发提供访问，配置其公开访问地址：

STORAGE_1_PUBLIC_BASE_URL=https://files.example.com

6. 重启 Storage UI

修改 .env.local 后重启开发服务器：

bun run dev

对于托管部署，保存环境变量后重新部署。AWS S3 连接随后会出现在侧边栏中。

常见问题

存储桶没有出现

确认存储桶名称、region、Access Key ID 和 Secret Access Key 都配置在同一个 STORAGE_n_* 编号下。

访问被拒绝

检查 IAM 策略是否允许对存储桶执行 s3:ListBucket、对对象执行 s3:GetObject。上传和删除还需要 s3:PutObject 和 s3:DeleteObject。

上传或预览因 CORS 报错

把 Storage UI 运行的来源加入存储桶的 CORS 配置（第 4 步）。方法中必须包含 GET 和 PUT。

region 无效

AWS S3 必须填写真实 region。确保 STORAGE_n_REGION 与存储桶所在 region 完全一致；auto 和空值都会被 AWS 拒绝。