# Cloudflare R2: arquivos, custo e cache para produtos reais
> Use Cloudflare R2 para arquivos, capas e materiais sem novo deploy: compare com banco e KV, entenda preço, cache, segurança e metadata.
**Autores:** Mauro Mequelussi
**Publicado:** 2026-07-25T12:00:00.000Z
**Atualizado:** 2026-07-25T12:00:57.062940988Z
**Tags:** cloudflare, arquivos, cache, r2, storage
---
Cloudflare R2 é object storage compatível com S3 para arquivos: imagens, PDFs, vídeos temporários, backups e materiais. Ele não substitui o banco de dados do produto; ele guarda bytes e metadados de objeto. A aplicação continua responsável por saber quem pode acessar um arquivo, a qual entidade ele pertence e quando ele deve expirar.

Para um produto criado com vibe coding, R2 resolve uma falha recorrente: salvar arquivos em `public/` e depender de novo deploy para trocar uma capa. Com R2, o arquivo tem uma chave versionada, pode ser entregue por domínio próprio e continua rastreável pelo registro `file` no banco.

## R2, banco e CDN: cada um tem uma função

| Camada | Responsabilidade |
| --- | --- |
| R2 | bytes do objeto, content type, cache e metadata do objeto |
| SurrealDB | registro `file`, relação com artigo/curso/usuário e regra de domínio |
| Worker/API | autorização, validação, upload, URL pública ou assinada |
| CDN/custom domain | entrega e cache perto do leitor |

Essa divisão impede que uma URL solta vire o único registro de um arquivo. No blog, por exemplo, a capa aponta para R2, mas o `file_id`, a chave e a relação `cover` continuam conciliados. Se alguém olhar o objeto diretamente no bucket, os metadados personalizados ajudam a localizar o registro canônico.

## Quando R2 faz sentido?

Use R2 para conteúdo binário e coleções que crescem: capas, thumbnails, anexos, PDFs, vídeos para processamento e exportações. Use o banco para atributos consultáveis e permissão. Use KV para cache pequeno e read-heavy. Essa distinção evita tentar carregar uma imagem inteira em uma chave KV ou consultar arquivos por categoria percorrendo um bucket.

::callout{type="info" title="Um bucket público não significa uma API pública"}
Capas de blog podem ser públicas. Comprovantes, materiais pagos e documentos de clientes devem passar por autorização e URL assinada ou proxy autenticado.
::

## Preço: o que entra na conta

Na tabela atual, R2 Standard cobra US$ 0,015 por GB-mês, US$ 4,50 por milhão de operações Classe A (como escrita/listagem) e US$ 0,36 por milhão de operações Classe B (como leitura). O plano inclui 10 GB-mês, 1 milhão de Classe A e 10 milhões de Classe B por mês; o egress para Internet é gratuito. A classe Infrequent Access reduz storage, mas adiciona recuperação e exige permanência mínima de 30 dias.

Para capas e arquivos acessados com frequência, Standard costuma ser a escolha clara. Não escolha Infrequent Access para economizar centavos em uma imagem que o navegador consulta todo dia: a recuperação e a duração mínima mudam a conta. Para material arquivado e pouco lido, faça uma simulação com acesso esperado.

## Chaves, cache e versionamento

Uma boa chave explica o domínio e não muda depois de publicada:

```text
content/blog/cloudflare-r2-arquivos-custo/cover-v1.webp
materials/course:abc/01J.../aula-01.pdf
financial/transaction:abc/01J.../comprovante.pdf
```

Ao trocar uma capa, crie uma nova chave e atualize a referência no banco. Isso permite cache longo, como `public, max-age=31536000, immutable`, sem o leitor receber uma imagem antiga. Sobrescrever sempre a mesma key parece mais simples, mas cria depuração difícil em CDN e navegadores.

## Upload seguro em cinco passos

1. O navegador envia o arquivo para uma rota autenticada ou recebe uma URL de upload limitada.
2. A API valida MIME type, tamanho e escopo do usuário.
3. O Worker gera a key; o cliente não escolhe caminho livremente.
4. A aplicação grava R2, cria/atualiza `file` e reconcilia `customMetadata` com o ID do banco.
5. A relação de domínio define se o arquivo é capa, anexo ou material privado.

::read-more{slug="cloudflare-queues-vs-workflows" label="Continuar: processe uploads e eventos sem travar a requisição" placement="mid_content"}
## Prós e contras

**Prós:** API S3, integração direta com Workers, egress gratuito, consistência forte para escrita/delete e cache por custom domain. **Contras:** ele não fornece consulta relacional, permissão de negócio nem transformação automática de imagem por si só. Para imagens responsivas, combine R2 com Cloudflare Images; para processamento depois de upload, use Queue.

## Checklist de produção

- [ ] bucket e prefixo refletem o domínio do arquivo;
- [ ] privado e público não compartilham regra de acesso por acidente;
- [ ] `Content-Type` e `Cache-Control` são definidos;
- [ ] key é única/versionada;
- [ ] `file` e metadata de R2 têm reconciliação;
- [ ] lifecycle remove arquivos temporários;
- [ ] upload de cliente não recebe credencial administrativa.

## Perguntas frequentes

### R2 é um CDN?

R2 é storage. Um custom domain e a CDN da Cloudflare entregam objetos publicamente; ainda assim, você deve definir cache, visibilidade e invalidação.

### Posso acessar R2 com SDK S3?

Sim. R2 é compatível com a API S3. Dentro de Workers, o binding é normalmente mais simples e evita distribuir credenciais de API.

### R2 substitui banco de dados?

Não. Guarde o arquivo no R2 e a relação, dono, status e permissão no banco.

### Fontes e leitura recomendada

- [Cloudflare R2](https://developers.cloudflare.com/r2/)
- [Preços do R2](https://developers.cloudflare.com/r2/pricing/)
- [API R2 em Workers](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/)