Cloudflare Container perdeu arquivos: como usar snapshots

Resposta rápida

Se os arquivos de um Cloudflare Container desapareceram depois de sleep, restart ou troca de instância, isso pode ser o comportamento esperado: todo o disco é efêmero por padrão e uma nova inicialização usa um filesystem limpo criado a partir da imagem. Para recuperar um estado anterior, a aplicação precisa criar explicitamente um snapshot antes da parada e restaurá-lo no próximo start.

Snapshots estão em beta pública e funcionam somente em aplicações com scheduling_policy definido como durable_object. Eles preservam o filesystem completo em um ponto no tempo, mas não salvam memória nem processos em execução. Para dados que mudam continuamente, como registros de negócio, filas e arquivos enviados pelo usuário, prefira Durable Object Storage, R2 ou outro armazenamento durável em vez de tratar snapshot como banco de dados ou backup permanente.

O que mudou em 30 de setembro

A Cloudflare lançou em 30 de setembro de 2026 as APIs de snapshot e restauração para Containers. O método snapshotContainer() captura o filesystem de uma instância em execução e devolve um handle que pode ser guardado no storage do Durable Object. Depois, esse handle é passado a ctx.container.start() para reconstruir o disco em outro start ou até em outro Durable Object.

O recurso chegou junto com a política de agendamento durable_object, que permite escolher imagem, tamanho da instância e conectividade no código de cada Durable Object. Esse desenho atende sandboxes, computadores de agentes e sessões isoladas que precisam de configuração e estado por instância, sem obrigar toda a aplicação a usar a mesma imagem e o mesmo tamanho.

Por que o Container volta sem os arquivos

Uma instância pode parar por timeout de inatividade, signal(), destroy(), saída do processo ou substituição durante uma atualização. Na classe Container, o sleepAfter padrão é de dez minutos e a implementação padrão encerra o processo quando esse período expira. Quando a instância volta, o disco começa novamente a partir da imagem, salvo se o start receber um snapshot válido.

O problema pode parecer intermitente porque o mesmo filesystem continua disponível enquanto aquela instância está viva. O desaparecimento costuma aparecer só depois de scale to zero, falha, manutenção ou um novo posicionamento. A propriedade ctx.container.running também não prova que a aplicação está pronta: ela muda para true antes de a porta aceitar tráfego.

• Confirme nos logs se houve timeout, saída do processo, signal, destroy ou nova inicialização.
• Registre um arquivo de teste e o identificador da sessão antes de deixar a instância dormir.
• No retorno, diferencie disco limpo de falha de montagem, permissão ou diretório de trabalho incorreto.
• Não aumente o timeout apenas para mascarar a ausência de persistência; isso mantém compute ativo e pode aumentar custo.

Pré-requisitos antes de criar o snapshot

A aplicação precisa usar a Durable Object Container API e a política durable_object. A política é imutável: uma aplicação criada com a política default não pode ser convertida no mesmo registro. A migração exige criar uma nova aplicação de Container, atualizar bindings e substituir as instâncias de forma controlada. Excluir a aplicação antiga também exclui suas instâncias.

Containers estão disponíveis no plano Workers Paid. No Wrangler, configure scheduling_policy como durable_object e declare as imagens permitidas. O código seleciona uma imagem de ctx.container.images ao iniciar uma sessão nova. Para restaurar, ele fornece o snapshot no lugar da imagem; os dois campos não podem ser enviados juntos.

• Mapeie cada Durable Object para uma sessão ou ambiente que realmente precisa de disco próprio.
• Planeje a migração sem apagar a aplicação antiga antes de validar bindings e restauração.
• Use imagens fixadas por digest ou as referências imutáveis preparadas pelo Wrangler.
• Mantenha enableInternet desativado quando o workload não precisa de saída para a internet.

Como criar e guardar um snapshot

Antes da captura, interrompa novas escritas e faça o aplicativo descarregar buffers para o disco. Em seguida, chame this.ctx.container.snapshotContainer({ name: 'before-sleep' }). O método devolve um objeto de handle; salve esse objeto em this.ctx.storage com uma chave estável associada à sessão. O nome ajuda na operação, mas não substitui a referência retornada.

A captura representa o filesystem inteiro naquele instante. Ela não é incremental nem mutável. Se o agente ou a aplicação alterar arquivos depois, crie outro snapshot para preservar o novo estado. Guarde também metadados como horário, versão lógica da imagem e finalidade da captura para impedir que o código restaure silenciosamente uma versão incompatível.

• Bloqueie ou drene novas gravações durante a captura.
• Execute snapshotContainer() somente com a instância em execução.
• Salve o handle no Durable Object Storage, não apenas em memória ou em uma variável global.
• Registre a imagem, a sessão e a data sem gravar segredos nos logs.
• Confirme que o snapshot ficou abaixo do limite de 20 GB.

Como restaurar sem iniciar uma sessão vazia

Leia o handle salvo e passe containerSnapshot para this.ctx.container.start({ containerSnapshot, enableInternet: false }). Não informe image na mesma chamada, porque o snapshot já identifica o filesystem e a combinação dos dois campos gera erro. Se não houver handle válido, decida explicitamente se a aplicação deve iniciar uma sessão nova ou falhar de forma segura.

start() retorna depois de validar os parâmetros, antes de o processo ficar pronto. Faça uma verificação de porta ou endpoint de saúde e use monitor() para capturar falhas posteriores. Só libere tráfego ou execute comandos depois que o serviço responder. Em seguida, confirme arquivos, permissões e versão da aplicação dentro do filesystem restaurado.

• Carregue o handle associado à sessão correta.
• Interrompa se o handle estiver ausente quando a continuidade for obrigatória.
• Inicie com containerSnapshot e a política de rede necessária.
• Espere readiness; running igual a true ainda não significa serviço disponível.
• Valide arquivos críticos e gere um novo snapshot após qualquer alteração que precise sobreviver.

O que o snapshot não preserva

O snapshot salva o filesystem completo, mas não captura RAM, processos, conexões de rede nem o ponto exato de execução de um job. Depois da restauração, o entrypoint inicia normalmente. Filas em memória, locks, sockets e tarefas que não registraram checkpoint precisam de outra estratégia de recuperação.

O snapshot fica vinculado à versão da imagem em que foi criado e não é portátil para uma imagem diferente. Depois de atualizar a imagem, crie novas capturas em Containers que já executam essa versão. O handle tem retenção implícita de 30 dias; cada restauração renova esse prazo, e ainda não existe TTL personalizado. Isso torna snapshots inadequados como arquivo permanente ou única cópia de dados importantes.

Snapshot, Durable Object Storage ou R2

Use snapshot para retomar rapidamente um ambiente de agente, sandbox de desenvolvimento, dependências instaladas ou arquivos temporários que formam um conjunto coerente. Use Durable Object Storage para estado pequeno e transacional ligado à coordenação da sessão. Use R2 ou outro object storage para uploads, artefatos e arquivos que precisam de retenção independente do ciclo da instância.

A Cloudflare também documenta montagem por FUSE para persistir em R2 ou backends compatíveis, com a ressalva de que o desempenho não deve ser comparado ao de um SSD local. Para bancos dentro do Container, trate consistência separadamente: pausar escritas e capturar disco reduz risco, mas recuperação, cópias externas e testes de restauração continuam necessários.

Por que criar ou restaurar pode falhar

O erro mais comum é tentar snapshot na política default. Outros casos incluem enviar image e containerSnapshot juntos, restaurar um handle expirado, usar um snapshot ligado a outra imagem, ultrapassar 20 GB ou iniciar o Container e enviar tráfego antes da prontidão. Uma restauração aparentemente bem-sucedida também pode mostrar arquivos antigos se o último snapshot foi criado antes das gravações finais.

Se várias sessões falham ao mesmo tempo, confira o Cloudflare Status e os logs do Worker e do Container antes de alterar imagens ou apagar handles. Se apenas uma sessão falha, compare identificador do Durable Object, chave usada no storage, imagem, data da captura e sequência dos eventos. Não inclua handles, tokens, arquivos privados ou conteúdo sensível em tickets públicos.

Limites e próxima ação útil

Este guia foi verificado em 30 de setembro de 2026. Snapshots estão em beta pública, aceitam até 20 GB e expiram 30 dias após a criação ou a restauração mais recente. A política durable_object não aceita max_instances; as instâncias em execução consomem os limites da conta. O produto exige Workers Paid e a cobrança de CPU, memória, disco, Workers e Durable Objects continua conforme o uso.

Faça primeiro um teste descartável: crie uma sessão, grave um arquivo identificável, capture o snapshot, pare a instância e restaure pelo handle guardado. Valide readiness e conteúdo, espere um novo ciclo de sleep e repita. Só depois aplique o fluxo a agentes ou jobs reais, adicionando retenção externa para tudo que não pode depender de uma beta ou de um TTL de 30 dias.

Fontes consultadas

Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.

• Snapshot and restore Container filesystemCloudflare Changelog
• Use snapshotsCloudflare Docs
• Scheduling PoliciesCloudflare Docs
• Lifecycle of a ContainerCloudflare Docs
• Durable Object Container APICloudflare Docs
• Limits and Instance TypesCloudflare Docs
• PricingCloudflare Docs
• Cloudflare StatusCloudflare