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.
Sem armazenamento persistente, cada instância usa um disco temporário com o tamanho incluído no plano, mais 1 GB reservado para arquivos temporários e logs. Ele não precisa ser configurado e acompanha o plano quando você troca de plano. Tudo o que a aplicação grava fora do armazenamento persistente, inclusive em /tmp, fica nesse disco, e não na memória da instância. Quando uma instância ultrapassa esse limite, a plataforma a substitui por uma nova: ela aparece em Instâncias como substituída, com o motivo, e, se os alertas por e-mail estiverem ligados, você recebe um aviso. Reduza os arquivos temporários, mude para um plano com mais disco ou guarde os arquivos no armazenamento persistente.
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:
- Escolha Sim em A aplicação precisa guardar arquivos?. Com Não, o Console só mostra o disco temporário incluído no plano.
- Defina a capacidade, entre 1 GB e 250 GB.
- 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. O preço do GB vem do catálogo de armazenamento: no pagamento por hora, a cobrança é proporcional ao tempo (preço mensal ÷ 720 por hora); no contrato mensal, o preço mensal por GB é cobrado na criação; no contrato anual, 12 vezes esse valor.
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
| Modelo de pagamento | O que é possível |
|---|---|
| Por hora | Aumentar a capacidade a qualquer momento. Reduzir não é permitido. |
| Mensal ou anual | A capacidade fica fixa durante o período contratado. |
| Plano Free (legado) | A capacidade não pode ser alterada. |
Isso vale para o armazenamento persistente; o disco temporário segue o plano. O aumento pode ser feito com o projeto em execução ou parado. Se a organização tiver pagamentos pendentes, o aumento fica bloqueado até a regularização.
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 e STORAGE_UPDATE_NOT_ALLOWED_FOR_FREE_PLAN no plano Free.
Acompanhar o uso
Em todos os planos, 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?
Sim. O diretório persistido é o mesmo para todas as instâncias do projeto. Ainda assim, 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.
Última atualização em
Variáveis de ambiente
Defina variáveis de ambiente e segredos em projetos da Zenifra no console, CLI ou API: até 50 por projeto, reinício ao salvar, uso no build e boas práticas.
Rede e controle de acesso
Escolha projeto HTTP público ou privado na Zenifra, entenda o subdomínio *.clients.zenifra.com e restrinja o acesso por IP com whitelist e blacklist em CIDR.