S3 协议存储

对象存储配置不对，会直接影响上传、CMS 封面、AI 结果文件访问。

这页只讲可执行步骤，目标是最快稳定上线。

推荐方案（优先）

除非你团队已经深度使用 AWS，否则优先上 Cloudflare R2。

• 接口兼容 S3，接入快
• 常见 CDN 架构下流量成本更可控
• 和 Bunship 当前上传链路直接匹配

Bunship 最少需要的变量

只要这 6 个变量正确，上传链路就能跑通：

• S3_ENDPOINT
• S3_REGION
• S3_ACCESS_KEY
• S3_SECRET_KEY
• S3_BUCKET
• NEXT_PUBLIC_S3_URL_BASE

快速接入（Cloudflare R2）

1. 创建 Bucket

例如：bunship-prod。

2. 创建 API Token

给该 bucket 开通读写权限，拿到 Access Key / Secret Key。

3. 准备 Endpoint 和公网访问域名

• Endpoint 格式：https://<ACCOUNT_ID>.r2.cloudflarestorage.com
• 公网访问前缀：
  • 你自己的 CDN/自定义域名，或
  • R2 的公开域名（已开启时）

4. 填写环境变量

S3_ENDPOINT="https://<ACCOUNT_ID>.r2.cloudflarestorage.com"
S3_REGION="auto"
S3_ACCESS_KEY="<R2_ACCESS_KEY_ID>"
S3_SECRET_KEY="<R2_SECRET_ACCESS_KEY>"
S3_BUCKET="bunship-prod"
NEXT_PUBLIC_S3_URL_BASE="https://cdn.你的域名"

5. 重启 web 与 api 服务

修改变量后必须重启，让上传客户端重新加载配置。

生产验收（必须通过）

1. 用户侧上传一张图片。
2. 后台 CMS 上传/生成一张封面。
3. 触发一次 AI 生成并打开返回文件 URL。

这 3 步都通过，存储链路基本就稳定了。

常见问题

1. 403 / 签名错误： endpoint、region、密钥不是同一账号体系。
2. 上传成功但打不开： NEXT_PUBLIC_S3_URL_BASE 不对，或 Bucket/CDN 没放通。
3. 本地正常，线上异常： web 和 api 的环境变量不一致。
4. 成本上涨过快： 缓存策略不完整 + 大文件过多。

什么时候改用 AWS S3

如果你已经有：

• 成熟 AWS 网络和 IAM 策略
• 强制 AWS 合规要求
• 统一 AWS 成本和日志体系

那就直接用 S3，不必绕一层。

Next Steps