Armazenamento persistente

Por padrão, o sistema de arquivos de uma instância é efêmero: arquivos gravados pela aplicação desaparecem quando a instância reinicia, recebe uma nova versão ou é substituída. O armazenamento persistente mantém um diretório escolhido por você entre reinícios e publicações.

Quando usar

Use armazenamento persistente quando a aplicação precisa:

• manter uploads de usuários;
• guardar arquivos gerados, como PDFs, relatórios ou exportações;
• preservar dados de aplicações prontas, como n8n, Metabase ou WordPress;
• manter arquivos de trabalho entre etapas de um processamento.

Não use quando os dados podem ser recriados a qualquer momento (cache local, arquivos temporários de build) ou quando um banco de dados gerenciado é a ferramenta mais adequada. Dados estruturados, consultas e transações devem ficar no banco, não em arquivos.

Como configurar

O armazenamento é definido na criação do projeto HTTP, no passo Configurar armazenamento:

1. Escolha Sim em Armazenamento persistente.
2. Defina a capacidade, entre 1 GB e 250 GB.
3. Informe o diretório para persistir: o caminho absoluto, dentro da aplicação, onde os arquivos serão gravados. Exemplos: /data, /app/uploads, /var/www/html/wp-content.

Importante: o diretório persistido não pode ser alterado depois da criação. Confirme na documentação da sua aplicação ou imagem qual caminho guarda os dados.

Alguns planos incluem uma franquia de armazenamento; a capacidade acima dela é cobrada conforme o resumo exibido antes da confirmação.

Durabilidade

Os dados do armazenamento persistente são replicados em três cópias. Se um servidor da Zenifra falhar, os arquivos continuam disponíveis para o projeto.

Replicação não substitui backup: um arquivo apagado ou corrompido pela aplicação é apagado ou corrompido em todas as cópias. Mantenha cópias externas dos dados críticos.

Alterar a capacidade

O aumento pode ser feito em Editar projeto ou pela API de armazenamento, com a permissão project.storage.update. A API retorna STORAGE_SIZE_CANNOT_DECREASE para reduções e STORAGE_UPDATE_NOT_ALLOWED_FOR_CONTRACT quando o modelo de pagamento não permite a mudança.

Acompanhar o uso

Em planos com métricas de armazenamento, o console mostra o espaço usado na página do projeto. Pela API, use GET /project/:id/storage/usage com project.metrics.read. Acompanhe o crescimento e aumente a capacidade antes de chegar ao limite: uma aplicação sem espaço em disco costuma falhar ao gravar arquivos ou ao iniciar.

Ambientes de preview

Previews recebem um armazenamento novo e vazio. Os arquivos do projeto principal não são copiados. Veja Ambientes de Preview.

Próximos passos

• Variáveis de ambiente
• Configuração do projeto
• Criar um projeto HTTP pelo console
• Checklist de produção

FAQ

Posso adicionar armazenamento persistente depois de criar o projeto?

O diretório e a ativação do armazenamento são definidos na criação. Se o projeto foi criado sem armazenamento, crie um novo projeto com a configuração desejada e migre a aplicação.

Várias instâncias compartilham os mesmos arquivos?

Trate o diretório persistido como um disco local da aplicação. Para dados que precisam ser lidos e escritos de forma consistente por várias instâncias ao mesmo tempo, prefira um banco de dados ou um serviço gerenciado.

O que acontece com os arquivos quando excluo o projeto?

A exclusão do projeto remove permanentemente o armazenamento e os arquivos. Faça backup antes de excluir.