跳到主要内容

IGeekFan.R2.NET

Cloudflare R2 对象存储的 .NET 客户端，基于 AWS S3 SDK（R2 兼容 S3 API），提供文件上传/下载/删除/管理等能力。

NuGet 包​

dotnet add package IGeekFan.R2.NET

依赖​

  • AWSSDK.S3 3.7.400 — S3 兼容 API
  • AWSSDK.Extensions.NETCore.Setup 3.7.301 — AWS SDK DI 集成
  • Microsoft.Extensions.Http / Logging / Options 10.x

快速开始​

1. 配置 appsettings.json​

{
  "CloudflareR2": {
    "ApiBaseUri": "https://<account-id>.r2.cloudflarestorage.com",
    "AccessKeyId": "<your-access-key-id>",
    "Secret": "<your-secret-access-key>",
    "Host": "https://your-domain.com",
    "Bucket": "your-default-bucket",
    "AccountId": "<your-account-id>",
    "PrefixPath": "",
    "PresignedUrlExpiryInMinutes": 15
  }
}
配置项必填说明
AccessKeyId✅R2 API Token 的 Access Key ID
Secret✅R2 API Token 的 Secret Access Key
ApiBaseUri✅Cloudflare R2 S3 兼容端点
Bucket-默认 Bucket 名称
Host-公开访问域名（用于拼接文件 URL）
AccountId-Cloudflare Account ID
PrefixPath-文件路径前缀
PresignedUrlExpiryInMinutes-预签名 URL 过期分钟数（默认 15）

2. 注册服务​

using IGeekFan.R2.NET;
using IGeekFan.R2.NET.Configuration;

builder.Services.Configure<CloudflareR2Options>(
    builder.Configuration.GetSection(CloudflareR2Options.SettingsName));

// 方式一：工厂模式（推荐，支持多 Bucket）
builder.Services.AddSingleton<ICloudflareR2ClientFactory, CloudflareR2ClientFactory>();

// 方式二：直接注入客户端
builder.Services.AddSingleton<ICloudflareR2Client>(sp =>
    new CloudflareR2Client(
        "your-bucket",
        sp.GetRequiredService<IOptions<CloudflareR2Options>>(),
        sp.GetRequiredService<ILogger<CloudflareR2Client>>(),
        sp.GetRequiredService<IHttpClientFactory>()));

3. 使用​

public class FileService
{
    private readonly ICloudflareR2ClientFactory _factory;

    public FileService(ICloudflareR2ClientFactory factory) => _factory = factory;

    public async Task<string> UploadAsync(Stream file, string fileName)
    {
        ICloudflareR2Client client = _factory.GetClient("my-bucket");
        string url = await client.UploadBlobAsync(file, fileName, CancellationToken.None);
        return url; // 返回不含签名的公开 URL
    }

    public async Task<Stream> DownloadAsync(string fileName)
    {
        ICloudflareR2Client client = _factory.GetClient("my-bucket");
        return await client.GetBlobAsync(fileName, CancellationToken.None);
    }
}

API 参考​

ICloudflareR2Client​

方法说明
UploadBlobAsync(Stream, string, CancellationToken)上传文件流，返回上传 URL
GetBlobAsync(string, CancellationToken)下载文件流
DeleteBlobAsync(string, CancellationToken)删除文件
ListBucketsAsync(CancellationToken)列出所有 Bucket
ListObjectsAsync(string, CancellationToken)列出 Bucket 中所有对象
GetBucketInfoAsync(string, CancellationToken)获取 Bucket 位置信息
GetObjectMetadataAsync(string, string, CancellationToken)获取对象元数据
CopyObjectAsync(string, string, string, string, CancellationToken)复制对象
MoveObjectAsync(string, string, string, string, CancellationToken)移动对象（复制 + 删除源）
CreateBucketAsync(string, CancellationToken)创建 Bucket
DeleteBucketAsync(string, CancellationToken)删除 Bucket

ICloudflareR2ClientFactory​

public interface ICloudflareR2ClientFactory
{
    ICloudflareR2Client GetClient(string bucketName);
}

工作原理​

  1. 预签名 URL：所有操作通过 AWS S3 SDK 生成预签名 URL
  2. 签名版本：强制使用 AWS Signature V4
  3. HTTP 传输：通过 IHttpClientFactory 发送 PUT/GET/DELETE 请求
  4. 上传：生成 PUT 预签名 URL → HttpClient 上传 Stream
  5. 下载：生成 GET 预签名 URL → HttpClient 下载为 Stream
  6. 删除：生成 DELETE 预签名 URL → HttpClient 发送请求

Cloudflare R2 配置指南​

获取 API Token​

  1. 登录 Cloudflare Dashboard → R2 → Manage R2 API Tokens
  2. 创建 API Token，选择 Admin Read & Write 权限
  3. 记录 Access Key ID 和 Secret Access Key

S3 兼容端点格式​

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

其中 <account-id> 在 Cloudflare Dashboard 首页获取。

与 FreeKit 集成​

在 FreeKit Pro Modules 中，R2.NET 作为可选的对象存储后端：

{
  "CloudflareR2": {
    "ApiBaseUri": "https://xxx.r2.cloudflarestorage.com",
    "AccessKeyId": "...",
    "Secret": "...",
    "Host": "https://cdn.example.com",
    "Bucket": "freekit-files"
  }
}