Backups e recuperação

Use um backup JSON quando precisar de uma cópia offline de dados de conteúdo selecionados. O EmDash não pode importar esse arquivo. Um plano de recuperação precisa de um backup bruto do banco de dados ou recuperação point-in-time e uma cópia separada dos binários de mídia.

Para copiar o conteúdo, as configurações e a mídia de um site para um novo site EmDash, inclusive em outro banco de dados, use um pacote de site em vez disso.

Se o site armazena configurações de plugin criptografadas, mantenha a lista completa de rotação de EMDASH_ENCRYPTION_KEY em um backup separado do gerenciador de segredos. A chave nunca é armazenada no banco de dados, no D1 Time Travel, em um dump SQL ou em uma exportação JSON.

O que há em um backup

Um backup JSON inclui:

• Todas as entradas de conteúdo, incluindo rascunhos, posts agendados e itens na lixeira
• Definições de coleção e de campos que formam o modelo de conteúdo
• Definições de taxonomia, termos e os termos atribuídos a cada entrada
• Menus e itens de menu, seções, áreas de widgets e widgets, registros SEO, histórico de revisões, metadados de mídia e histórico de migrações do banco de dados
• Configurações do site como título, slogan, URL, locale, logo, preferências de exibição, perfis sociais e padrões de SEO. Vêm do grupo de configurações site: e das configurações emdash:site_title, emdash:site_tagline e emdash:locale.

Omite todas as outras tabelas do banco de dados, incluindo:

• Contas de usuário, sessões, passkeys, dados OAuth, tokens de API e outros dados de autenticação
• Armazenamento e configurações de plugins, incluindo segredos de plugins
• Comentários e reações, redirecionamentos e logs 404, bylines, relações e referências de conteúdo, logs de auditoria, limites de taxa e estado de tarefas agendadas
• Pastas de mídia, registros de onde a mídia é usada, uploads incompletos ou em andamento, e os arquivos de mídia em si
• Outras opções do site, incluindo a URL de implantação registrada na configuração (emdash:site_url), o segredo de assinatura de preview e a programação de backups

Os backups são arquivos JSON no mesmo formato de snapshot usado pelo sistema de preview do EmDash, versionados com a versão EmDash que os criou.

Download com um clique

Em Settings → Backups no admin, o botão Download backup gera um backup novo e o baixa como arquivo JSON. Exige a função de administrador.

O download serve para inspeção ou ferramentas personalizadas. Antes de importações em massa, mudanças de esquema ou atualizações importantes, crie um backup restaurável do banco de dados com uma das opções abaixo. Para mover o site para outro site EmDash, exporte um pacote de site em Settings → Transfer.

Backups automáticos para o armazenamento

Se o seu site tem um backend de armazenamento configurado (R2 no Cloudflare, S3 ou armazenamento local), você pode ativar backups automáticos diários:

Os arquivos são armazenados sob o prefixo backups/ no seu bucket como emdash-backup-<timestamp>-<random>.json. A lista Stored Backups no admin permite baixar ou excluir arquivos individuais, e Back up now cria um sob demanda.

Os backups automáticos aproveitam o tick de manutenção agendada (o mesmo mecanismo que alimenta a publicação agendada) — no Cloudflare é o gatilho cron do Worker, no Node o agendador integrado. Se sua implantação não tem gatilho cron configurado, use Back up now ou o botão de download em vez disso.

Fazer backup e restaurar objetos de mídia

Buckets R2 e compatíveis com S3 precisam de um backup em nível de objeto além do banco de dados. O exemplo AWS CLI a seguir copia cada objeto, incluindo os arquivos backups/ do EmDash, para um diretório de backup local. Para AWS S3, omita --endpoint-url.

aws s3 sync s3://emdash-media ./emdash-media-backup \
  --endpoint-url https://<account-id>.r2.cloudflarestorage.com

Use credenciais de bucket somente leitura para jobs de backup de rotina. Armazene o backup fora da conta de produção ou domínio de falha, e registre o backup do banco de dados ou o ponto Time Travel criado ao mesmo tempo.

Restaure em um bucket de recuperação vazio em vez de sobrescrever a produção enquanto ela atende solicitações:

aws s3 sync ./emdash-media-backup s3://emdash-media-recovery \
  --endpoint-url https://<account-id>.r2.cloudflarestorage.com

Dê ao job de restauração acesso de gravação apenas ao bucket de recuperação. Aponte uma implantação não produtiva para esse bucket, abra várias URLs de mídia conhecidas e faça upload e exclusão de um arquivo descartável. Mude o binding ou a configuração do bucket de produção somente depois que o banco de dados e o conjunto de mídia restaurados passarem juntos nas verificações.

Recuperar um banco de dados D1 com Time Travel

Antes de uma operação arriscada, peça ao Time Travel o bookmark atual e registre-o com a implantação ou o registro da mudança:

npx wrangler d1 time-travel info my-database

Se a recuperação for necessária, pare as gravações no site e inspecione o ponto de restauração disponível antes de executar o comando de restauração destrutivo:

npx wrangler d1 time-travel restore my-database --timestamp=2026-07-08T13:00:00Z

O Time Travel restaura o banco de dados inteiro, incluindo conteúdo, usuários, configurações, dados de plugins e registros de migração. Não restaura objetos de mídia R2 nem EMDASH_ENCRYPTION_KEY. Antes de testar integrações de plugins, restaure cada chave de criptografia referenciada pelas configurações de plugin recuperadas. Após o comando concluir, implante a versão do aplicativo que corresponde ao banco de dados restaurado, reabra o tráfego e verifique login, leituras de conteúdo, mudanças de esquema, uma configuração de plugin criptografada e uma gravação.

Veja a documentação do D1 Time Travel para detalhes.

Criar um dump D1 offsite

Para um dump SQL completo do banco de dados bruto (incluindo tabelas de usuários e auth), use o Wrangler:

npx wrangler d1 export my-database --remote --output=backup.sql

Mantenha o arquivo SQL com a versão correspondente do aplicativo, o backup de mídia criado ao mesmo tempo e uma cópia armazenada separadamente da lista de rotação de EMDASH_ENCRYPTION_KEY. Teste a recuperação importando o dump em um banco D1 vazio recém-provisionado, restaurando as chaves de runtime, atualizando um binding não produtivo para esse banco e verificando o site.

Importe no banco de recuperação vazio com o seguinte comando:

npx wrangler d1 execute my-recovery-database --remote --file=backup.sql

Backup e recuperação SQLite

Para um backup SQLite offline, pare todo processo que escreve o banco de dados e copie o arquivo do banco junto com quaisquer arquivos -wal e -shm ao lado. O arquivo -wal pode conter mudanças confirmadas que ainda não estão no arquivo principal. Para um backup online consistente, use o comando de backup do SQLite:

sqlite3 emdash.db ".backup backup.db"

Faça backup separadamente do diretório local de uploads ou do bucket compatível com S3 e da lista de rotação de EMDASH_ENCRYPTION_KEY. Para recuperar, pare todo processo do servidor, retenha uma cópia do banco danificado, substitua-o pelo backup verificado, restaure as chaves de runtime e quaisquer objetos de mídia necessários, e inicie a versão correspondente do aplicativo. Verifique login, conteúdo público, uma configuração de plugin criptografada, uma edição e uma leitura de mídia antes de reabrir o tráfego.

Exportações JSON não podem restaurar um site

O EmDash não tem ação de admin, endpoint de API nem comando CLI para restauração JSON. Use D1 Time Travel, um dump SQL D1 bruto ou uma cópia do banco SQLite conforme descrito acima.

Para reconstruir o conteúdo de um site em um site EmDash novo e vazio, exporte um pacote de site do site original enquanto ele ainda estiver disponível e importe-o no novo site. Um pacote de site não restaura usuários, tokens de API, dados de plugins nem segredos, portanto não substitui um backup do banco de dados para recuperação de desastres.