Cloudflare R2

Armazenamento de objetos compatível com S3, sem taxas de saída (egress), construído na rede global da Cloudflare.

Quando Usar

• Armazenar uploads de usuários, arquivos de mídia, backups ou ativos estáticos.
• Substituir AWS S3 para eliminar custos de saída para cargas de trabalho com muitas leituras.
• Servir arquivos na borda (edge) via Workers ou acesso público ao bucket.
• Construir armazenamento multi-cloud que evita o aprisionamento tecnológico (vendor lock-in) (compatível com API S3).
• Armazenar artefatos de modelos de Machine Learning, dados de treinamento ou resultados de inferência.

Pré-requisitos

• Conta Cloudflare com R2 ativado (dashboard > R2 > assinar).
• Wrangler CLI v3+ instalado: npm install -g wrangler.
• Autenticado via wrangler login ou CLOUDFLARE_API_TOKEN.
• Para acesso à API S3: Token de API R2 criado em R2 > Gerenciar Tokens de API R2.

Gerenciamento de Buckets com Wrangler

Criar e Listar Buckets

# Create a new bucket
npx wrangler r2 bucket create app-assets

# Create a bucket in a specific region (hint for data locality)
npx wrangler r2 bucket create eu-uploads --location=eu

# List all buckets
npx wrangler r2 bucket list

# Delete an empty bucket
npx wrangler r2 bucket delete old-bucket

Operações de Objetos

# Upload a single file
npx wrangler r2 object put app-assets/images/logo.png --file=./logo.png

# Upload with content type
npx wrangler r2 object put app-assets/data/report.json \
  --file=./report.json \
  --content-type="application/json"

# Download an object
npx wrangler r2 object get app-assets/images/logo.png --file=./downloaded-logo.png

# Delete an object
npx wrangler r2 object delete app-assets/images/old-logo.png

# Get object metadata
npx wrangler r2 object head app-assets/images/logo.png

Acesso Compatível com API S3

R2 suporta a API S3, então ferramentas existentes (AWS CLI, boto3, s3cmd) funcionam imediatamente.

Gerar Tokens de API R2

1. Vá para R2 > Gerenciar Tokens de API R2 > Criar token de API.
2. Selecione permissões: Leitura e Escrita de Objetos, ou Apenas Leitura de Objetos.
3. Escopo para buckets específicos, se possível.
4. Salve o ID da Chave de Acesso (Access Key ID) e a Chave de Acesso Secreta (Secret Access Key).

Configuração do AWS CLI

# Configure a named profile for R2
aws configure --profile r2
# Access Key ID: <your-r2-access-key>
# Secret Access Key: <your-r2-secret-key>
# Region: auto
# Output: json

# Use the R2 endpoint
export R2_ENDPOINT="https://<ACCOUNT_ID>.r2.cloudflarestorage.com"

# List buckets
aws s3 ls --endpoint-url=$R2_ENDPOINT --profile=r2

# Sync a directory
aws s3 sync ./dist s3://app-assets/static/ \
  --endpoint-url=$R2_ENDPOINT \
  --profile=r2

# Copy a file
aws s3 cp ./backup.tar.gz s3://app-assets/backups/backup-$(date +%Y%m%d).tar.gz \
  --endpoint-url=$R2_ENDPOINT \
  --profile=r2

# List objects with prefix
aws s3 ls s3://app-assets/images/ \
  --endpoint-url=$R2_ENDPOINT \
  --profile=r2

# Remove objects by prefix
aws s3 rm s3://app-assets/tmp/ --recursive \
  --endpoint-url=$R2_ENDPOINT \
  --profile=r2

Cliente Python boto3

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
    aws_access_key_id="<R2_ACCESS_KEY>",
    aws_secret_access_key="<R2_SECRET_KEY>",
    region_name="auto",
)

# Upload file
s3.upload_file("./report.pdf", "app-assets", "reports/report.pdf")

# Generate presigned URL (valid for 1 hour)
url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "app-assets", "Key": "reports/report.pdf"},
    ExpiresIn=3600,
)
print(url)

# List objects
response = s3.list_objects_v2(Bucket="app-assets", Prefix="images/", MaxKeys=100)
for obj in response.get("Contents", []):
    print(f"{obj['Key']} - {obj['Size']} bytes")

Vinculações (Bindings) de Worker

Vincule buckets R2 a Workers ou Pages Functions para acesso do lado do servidor sem tokens de API.

Configuração do Wrangler

# wrangler.toml
name = "asset-worker"
main = "src/index.ts"
compatibility_date = "2024-09-01"

[[r2_buckets]]
binding = "ASSETS"
bucket_name = "app-assets"

[[r2_buckets]]
binding = "UPLOADS"
bucket_name = "user-uploads"

Worker com Operações R2

// src/index.ts
interface Env {
  ASSETS: R2Bucket;
  UPLOADS: R2Bucket;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    // GET — servir arquivo do R2
    if (request.method === "GET") {
      const key = url.pathname.slice(1); // remove a barra inicial /
      const object = await env.ASSETS.get(key);

      if (!object) {
        return new Response("Não encontrado", { status: 404 });
      }


…