Playbook de produção EmDash CMS no plano gratuito Cloudflare

Publicado em 2026-04-08 por Emdash Cms Everything

Resumo executivo

Você pode rodar o EmDash em produção no plano gratuito da Cloudflare para fluxos centrais de CMS.
O que precisa aceitar: execução de plugins em sandbox não está disponível, então worker_loaders deve ser removido da configuração.

Este guia prioriza estabilidade primeiro, não a maior superfície de recursos.

Limites de capacidade no plano gratuito

Disponível

• site core EmDash e fluxos de admin
• dados de conteúdo com D1
• armazenamento de mídia com R2 (dentro do uso gratuito)
• implantação e roteamento com Workers

Não disponível

• Workers dinâmicos para plugins em sandbox
• execução em runtime não confiável no estilo marketplace de plugins

Se o lançamento depende de execução sandbox de plugins de terceiros, o plano gratuito não é suficiente.

Checklist pré-implantação

Conclua todas as verificações antes de rodar comandos de deploy:

• Wrangler autenticado (wrangler login já concluído)
• projeto compila localmente sem suposições só de nuvem
• wrangler.jsonc tem bindings D1 e R2 alinhados com a config de runtime
• entrada worker_loaders removida para o plano gratuito
• escolha de gerenciador de pacotes consistente (npm ou pnpm, sem misturar)

Ordem de provisionamento de recursos

Provisione recursos nesta ordem exata para reduzir churn de bindings:

1. Criar banco D1
2. Criar ou habilitar R2 e então criar o bucket
3. Atualizar wrangler.jsonc com nomes e IDs exatos
4. Compilar e implantar o Worker

Motivo: o ID do D1 e os nomes de bucket viram a fonte da verdade para bindings de ambiente.

# Provisionar D1 primeiro
npx wrangler d1 create your-db-name

# Depois provisionar bucket R2
npx wrangler r2 bucket create your-media-bucket

Forma mínima de wrangler.jsonc no plano gratuito

O esqueleto a seguir é intencionalmente pequeno:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "your-site-name",
  "main": "./src/worker.ts",
  "compatibility_date": "2026-04-08",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "your-db-name",
      "database_id": "replace-with-d1-id"
    }
  ],
  "r2_buckets": [
    {
      "binding": "MEDIA",
      "bucket_name": "your-media-bucket"
    }
  ]
}

Sem seção worker_loaders no plano gratuito.

Fluxo de build e deploy

Execute os comandos a partir da raiz do projeto EmDash:

# escolha um gerenciador de pacotes e mantenha-o
npm run build
npm run deploy

Se o projeto for baseado em pnpm:

pnpm build
pnpm deploy

Evite misturar npm e pnpm na mesma sessão de deploy, a menos que os lockfiles estejam sincronizados de propósito.

Checklist de validação pós-deploy

Valide nesta ordem:

1. URL do frontend resolve e retorna o conteúdo esperado
2. URL de admin (/_emdash/admin) acessível
3. primeira configuração de admin concluída com sucesso
4. criar e publicar um item de teste
5. enviar um arquivo de mídia e confirmar recuperação

Um deploy não está completo até que caminhos de escrita de dados sejam verificados, não só o alcance das rotas.

Modos de falha frequentes e correções mais curtas

Falha: deploy ok, admin não inicializa

Causa provável: incompatibilidade de binding entre a integração de runtime e wrangler.jsonc.

Caminho de correção:

1. verificar se os nomes de binding (DB, MEDIA) são idênticos em todos os lugares
2. reimplantar após corrigir a config
3. tentar novamente a inicialização do admin

Falha: comando R2 bloqueado por prompt da conta

Causa provável: R2 ainda não habilitado no painel.

Caminho de correção:

1. habilitar R2 no painel da Cloudflare
2. aceitar termos de faturamento (o uso gratuito ainda se aplica)
3. repetir o comando de criação do bucket

Falha: erro de runtime relacionado a plugin no plano gratuito

Causa provável: configuração residual de sandbox.

Caminho de correção:

1. remover worker_loaders
2. desativar configuração de plugin específica de sandbox
3. reimplantar e testar de novo

Estratégia de rollback

Use política de rollback conservadora:

• manter o último commit de deploy bom conhecido marcado com tag
• se aparecer regressão em produção, reimplantar o commit tagueado anterior
• adiar mudanças de schema ou de plugin até o tráfego estabilizar

Na operação, rollback rápido vence hotfix profundo em janelas de incidente.

Quando sair do gratuito para pago

Faça upgrade só quando uma destas for verdade:

• você precisa de execução sandbox de plugin não confiável
• tráfego ou armazenamento ultrapassam regularmente os limites gratuitos
• governança exige isolamento de runtime de plugin mais forte

Não faça upgrade por redação ambígua em telas de faturamento. Faça upgrade só por requisitos concretos de capacidade.