Cloudflare R2 存储配置指南

本文档介绍如何配置 Cloudflare R2 对象存储服务，用于存储用户生成的图片和视频文件。

什么是 Cloudflare R2

Cloudflare R2 是 Cloudflare 提供的 S3 兼容对象存储服务，特点：

零出口费用：前 100GB/月出站流量免费
S3 兼容：可使用 AWS SDK 直接接入
** generous 免费额度**：前 10GB 存储免费
全球 CDN：集成 Cloudflare CDN，访问速度快

注册 Cloudflare 账号

1. 创建账号

访问 https://dash.cloudflare.com/sign-up 注册。

2. 启用 R2

登录 Cloudflare Dashboard
在左侧菜单中找到 "R2" 或搜索 "R2"
点击 "Open R2" 启用服务

创建存储桶 (Bucket)

1. 创建 Bucket

在 R2 页面点击 "Create bucket"
输入 Bucket 名称（如 vibany-storage）
选择地区（建议选择 "Automatic" 或离用户最近的区域）
点击 "Create bucket"

2. 配置公开访问

默认情况下 Bucket 是私有的，需要配置公开访问：

进入 Bucket 设置
找到 "Public access" 或 "域名访问" 选项
启用 "R2.dev subdomain"
记录生成的公开访问 URL（如 https://vibany-storage.r2.dev）

注意：R2.dev 子域名适合开发测试。生产环境建议使用自定义域名。

创建 API Token

1. 进入 API Token 管理

在 R2 页面点击 "Manage R2 API Tokens"
点击 "Create API Token"

2. 配置 Token 权限

Token name: vibany-app-token
Permissions:
  - Object Read & Write: Allow
  - Bucket Read: Allow

Bucket:
  - Specific buckets only: 选择你的 bucket

3. 保存凭证

创建后会显示：

Access Key ID（如 xxxxx）
Secret Access Key（如 yyyyy）

重要：Secret Access Key 只显示一次，务必保存好！

4. 获取 Account ID

在 R2 页面或 Cloudflare Dashboard 首页可以找到 Account ID。

配置环境变量

在 .env.local 文件中添加：

# Cloudflare R2 存储配置
R2_ACCOUNT_ID=your_account_id
R2_ACCESS_KEY_ID=your_access_key_id
R2_SECRET_ACCESS_KEY=your_secret_access_key
R2_BUCKET_NAME=your_bucket_name
R2_PUBLIC_URL_PREFIX=https://your-bucket-name.r2.dev

存储路径规范

Vibany 使用以下存储路径结构：

bucket/
├── images/              # 生成的图片
│   └── {userId}/
│       └── {historyId}/
│           └── image.jpg
├── temp/                # 临时上传文件
│   └── {timestamp}_{filename}
├── videos/              # 生成的视频
│   └── {userId}/
│       └── {videoId}/
│           ├── video.mp4
│           └── thumbnail.webp
└── backup/              # 备份图片
    └── {userId}/
        └── {historyId}/
            └── image.jpg

CORS 配置

为了允许浏览器直接上传文件，需要配置 CORS：

1. 进入 CORS 设置

在 Bucket 页面点击 "Settings"
找到 "CORS Policy" 或 "跨域访问"

2. 添加 CORS 规则

[
  {
    "AllowedOrigins": ["https://yourdomain.com"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedHeaders": ["*"],
    "MaxAgeSeconds": 3600
  }
]

如果使用多个域名，添加多个 origin：

{
  "AllowedOrigins": [
    "https://yourdomain.com",
    "https://www.yourdomain.com",
    "http://localhost:3000"
  ]
}

自定义域名（可选）

生产环境建议使用自定义域名：

1. 添加自定义域名

在 R2 Bucket 设置中找到 "Custom domains"
点击 "Connect domain"
输入你的域名（如 cdn.yourdomain.com）
按提示添加 DNS 记录

2. 配置 SSL

Cloudflare 自动提供 SSL 证书，无需额外配置。

3. 更新环境变量

R2_PUBLIC_URL_PREFIX=https://cdn.yourdomain.com

图片处理

R2 支持通过 Cloudflare Images 进行图片处理：

启用 Images 服务

在 Cloudflare Dashboard 中找到 "Images"
启用服务并绑定到你的 R2 Bucket

使用图片变换 URL

# 原图
https://cdn.yourdomain.com/image.jpg

# 缩略图 (200px 宽度)
https://cdn.yourdomain.com/cdn-cgi/image/width=200/image.jpg

# 自适应格式
https://cdn.yourdomain.com/cdn-cgi/image/format=auto/image.jpg

故障排除

403 Forbidden

原因：

CORS 配置不正确
API Token 权限不足
Bucket 未启用公开访问

解决方案：

检查 CORS 配置是否包含当前域名
确认 API Token 有读写权限
启用 Bucket 的公开访问

图片无法显示

检查清单：

# 1. 检查公开 URL 是否正确
echo $R2_PUBLIC_URL_PREFIX

# 2. 检查文件是否存在（使用 AWS CLI）
aws s3 ls s3://your-bucket/images/ --endpoint-url=https://your-account.r2.cloudflarestorage.com

# 3. 检查图片是否损坏

上传失败

常见原因：

API Key 错误
Bucket 名称错误
文件大小超过限制