Cloudflare R2介绍#

Cloudflare R2 是一款兼容 S3 API 的对象存储服务，最大特点是 无出口流量费，非常适合存放图片、视频、静态资源、文件下载等。只要你绑了卡就能使用，而且量大管饱，反观阿里oss只能试用3个月而且量小不管饱😭。

本文将从 注册账号 → 创建 Bucket → 获取 Key →创建桶 来一步步实现

. Bucket 的设置与管理（R2 存储桶配置详解）#

创建完一个 Bucket（存储桶）之后，R2 还提供许多实用的配置，让你可以控制权限、访问、生命周期、跨域、绑定域名等功能。

这部分的内容非常关键，特别是你要把 R2 用作：

• 图床
• 静态资源托管
• 网站图片存储
• 后端服务文件上传
• 用户上传系统

下面是所有你必须知道的 bucket 配置。

5.1. Bucket 权限设置（Public / Private）#

R2 的桶权限只有两种：

1
https://<account-id>.r2.cloudflarestorage.com/<bucket>/<key>

5.2. CORS 设置（跨域资源共享）#

如果你要从浏览器读取 R2 的文件、上传文件、调用 API，就必须配置 CORS。

推荐最通用的配置：

5.3. 自定义域名绑定（强烈推荐）#

默认域名：

1
https://<account-id>.r2.cloudflarestorage.com/

不方便记，也不利于 SEO，因此你可以通过 Cloudflare Worker 将你的域名映射到 R2：

例如：

1
https://img.xxx.com/logo.png

绑定步骤：

1. 创建 Worker 并关联 R2 Bucket
2. 加 Route，将 Worker 绑定到你的域名
3. 设置缓存（可选）

这也是使用 R2 最专业的做法。

5.4. 生命周期规则（LifeCycle Rule）#

类似于 OSS 的生命周期，有以下用途：

• 自动删除过期文件（比如临时文件 7 天后清理）
• 控制存储成本
• 清理生成的缓存文件
• 删除上传失败的对象

示例规则：

1
删除 30 天前上传的所有 .tmp 文件

你可以通过：

1
R2 → Lifecycle → Create Rule

来创建。

5.5. 存储桶加密（默认开启）#

R2 自动对所有对象进行服务器端加密（Server-Side Encryption）。

你不需要额外设置，但可以在：

1
Security → Object Encryption

查看加密方式（Cloudflare 托管密钥）。

5.6. 防止对象覆盖（Object Lock）#

启用后：

• 相同的 key 无法被覆盖
• 必须先删除才能上传同名文件
• 适用于日志、备份、不允许覆盖的业务

很多云厂商收费，R2 免费。

5.7.. Workers 集成（R2 的最强能力）#

你可以让 Worker 和 R2 结合来做：

• 私有桶访问控制
• 生成临时访问链接
• 对文件进行裁剪 / 压缩 / 处理
• 防盗链
• 下载限速
• 累计下载次数等业务逻辑

示例 Worker：

1
export default {
2
  async fetch(request, env) {
3
    const object = await env.MY_BUCKET.get("logo.png");
4
    return new Response(object.body, {
5
      headers: { "Content-Type": object.httpMetadata?.contentType }
6
    });
7
  }
8
};

这能让 R2 变成“带业务逻辑的对象存储”。

5.8. 设置文件的 HTTP Metadata（非常重要）#

很多文件需要正确的 Content-Type，否则访问会出问题。

常用类型：

在上传时（Java SDK）可以设置：

1
PutObjectRequest put = PutObjectRequest.builder()
2
        .bucket("my-bucket")
3
        .key("logo.png")
4
        .contentType("image/png")
5
        .build();

否则 Worker 返回时会是 application/octet-stream。

5.9. 对象版本管理（Versioning）#

开启后：

• 覆盖同名对象时会自动生成版本号
• 可以回滚到旧版本
• 类似 Git 的文件管理方式

适合敏感文件、文档、历史备份。

6.1. 配置 R2 访问密钥（application.yml）#

R2 会给你：

• Account ID
• Access Key
• Secret Key
• Bucket 名称

把这些写进 Spring Boot 的 application.yml：

1
cloudflare:
2
  r2:
3
    account-id: xxxxxxxxxxxxxxxxxxxxxxxx
4
    access-key: your_access_key_here
5
    secret-key: your_secret_key_here
6
    bucket-name: my-bucket

Spring Boot 会自动把它们注入到配置类里。

6.2. 引入 AWS S3 依赖#

因为 R2 采用 S3 协议，所以 Java 直接使用 AWS 官方的 S3 SDK：

1
<dependency>
2
    <groupId>software.amazon.awssdk</groupId>
3
    <artifactId>s3</artifactId>
4
    <version>2.25.20</version>
5
</dependency>

这个依赖提供：

• 上传文件
• 下载文件
• 删除文件
• 生成访问 URL

全部通用，不需要额外库。

6.3. 创建一个 R2Client（核心）#

连接 R2 的关键就是：

把 AWS 的 S3 endpoint，换成 Cloudflare 的 R2 endpoint。

格式是：

1
https://<account-id>.r2.cloudflarestorage.com

所以我们写一个配置类：

1
@Bean
2
public S3Client r2Client() {
3
    return S3Client.builder()
4
            .region(Region.US_EAST_1) // 固定
5
            .endpointOverride(URI.create("https://" + accountId + ".r2.cloudflarestorage.com"))
6
            .credentialsProvider(StaticCredentialsProvider.create(creds))
7
            .build();
8
}

这样，S3Client 就不再访问 AWS，而是访问 Cloudflare R2。

6.4. 上传文件的实现逻辑（最简单版本）#

上传文件其实就三步：

1. 前端上传文件 → Spring 接收 MultipartFile
2. 把文件流交给 r2Client
3. 指定 bucket 和 key 即可上传

1
public String upload(String key, InputStream inputStream) {
2
    r2Client.putObject(
3
        PutObjectRequest.builder()
4
            .bucket(bucketName)
5
            .key(key)
6
            .build(),
7
        RequestBody.fromInputStream(inputStream, inputStream.available())
8
    );
9
    return key;
10
}

R2 就会自动保存这个对象。

6.5. Controller 接口（让用户能上传）#

为了让前端能上传文件，我们写了一个简单的接口：

1
@PostMapping("/upload")
2
public String upload(@RequestParam("file") MultipartFile file)

这个接口做的事情：

• 接收 file（前端上传的文件）
• 生成一个 key（也就是对象在 R2 的路径）
• 调用 service 上传
• 返回 key 给前端

这就完成了整个文件上传流程。