A resposta curta
No Pro, um volume persistente é um path absoluto de mount em um serviço. O app tem que escrever lá. Faça um novo deploy e leia de novo um registro de teste. É assim que você confere se os dados sobrevivem ao redeploy.
O filesystem do contêiner não é esse path. Um deploy, um restart ou um reagendamento pode trocar o contêiner, e os arquivos que só viviam nele vão junto. Um backup para um destino compatível com S3 que você controla é uma terceira coisa: uma cópia, não o disco em uso.
Um volume não é um backup. Fazer redeploy não restaura dados.
A página do produto é arquivos persistentes. A referência é Persistent storage and backups. O passo a passo é Configure persistent storage and backups, e o desenho do app está em Deploy an application with persistent files.
Filesystem do contêiner e volume persistente
Os contêineres da aplicação são substituíveis. Trate como temporários os arquivos escritos só no filesystem do contêiner.
| Filesystem do contêiner | Volume persistente | |
|---|---|---|
| Duração | Temporário. Um deploy, um restart ou um reagendamento pode trocar o contêiner. | Um path durável para um serviço, quando o app escreve no mount. |
| Escopo | Aquele contêiner. | Um serviço, um path absoluto dentro do contêiner. |
| Réplicas | Não é um disco compartilhado. | Um serviço com volume roda uma réplica. |
| Recuperação | Um redeploy não traz esses arquivos de volta. | Não é um backup. Reset, Detach e apagar o serviço apagam os dados. |
No Free, um app ocioso dorme, e a memória e os arquivos temporários são descartados quando ele dorme. O Free não inclui volumes persistentes. As duas coisas estão em preços.
Um arquivo que sumiu depois de um redeploy não é a mesma falha que um crash. Se o deployment parou, leia a etapa em Depurar um deploy com falha. Um rollback da aplicação promove um deployment anterior. Ele não restaura um banco, um volume nem um efeito externo.
Escolha o que fica no volume
Deixe dependências instaladas e código compilado na imagem. Coloque uploads ou dados da aplicação num path dedicado, como /data.
Não monte por cima do diretório da aplicação. Um mount pode esconder arquivos que faziam parte da imagem.
Se vários serviços ou réplicas precisam dos mesmos arquivos, use object storage externo ou um banco. Um volume da Unbroker fica anexado a um serviço, e um serviço com volume roda uma réplica. Não é um filesystem compartilhado. O mesmo corte é o que separa os volumes de um Compose em Docker Compose em produção.
Num template de banco, mantenha o volume montado no diretório de dados que o motor espera. Mover o mount sem mover e validar os dados pode fazer o motor parecer vazio mesmo com os arquivos em outro lugar.
Deixe o path dos dados configurável
Aponte o processo para o mount com uma variável de ambiente. O guia de arquivos persistentes usa DATA_DIR numa ilustração em Node.js:
const directory = process.env.DATA_DIR;
if (!directory) throw new Error("DATA_DIR is required");
O resto dessa ilustração cria o diretório, escreve settings.json passando por um arquivo temporário e renomeia para o lugar final. É um arquivo de settings de um único escritor, não um banco concorrente. Serialize as escritas no app. O nome fixo do temporário não serve para escritores simultâneos. O snippet completo está em Deploy an application with persistent files.
Para registros que precisam de transações ou updates concorrentes, use PostgreSQL ou outro banco. Essa escolha é a última seção desta nota.
Um serviço Node começa em Deploy de Node.js. Um contêiner começa em Deploy de Docker.
Monte, faça deploy e confira
O passo a passo do guia usa o mount /data e DATA_DIR=/data. Confirme que o usuário de runtime consegue ler e escrever nesse diretório.
Os comandos de volume documentados são:
ubctl apps volumes ls
ubctl apps volumes attach svc_123 --path /app/data --size 10
ubctl apps volumes resize svc_123 --size 20
svc_123, /app/data, 10 e 20 são os exemplos da CLI de volumes. Use o path absoluto onde o app escreve. O /data do guia e o /app/data da CLI são dois exemplos desse path, não dois mounts. Volumes podem crescer e não podem encolher. Reset e detach não estão nessa CLI. Essas ações ficam em Storage, nas configurações do serviço.
Depois prove o mount:
- Faça deploy e crie um registro de teste inofensivo pela aplicação. Anote o valor.
- Faça deploy de novo do mesmo serviço e leia o registro outra vez.
- Confirme que o código novo aparece e que o dado de teste continua lá.
Isso pega um app que ainda escreve num diretório relativo, fora do mount. Teste também o app quando o filesystem está quase cheio, ou quando uma escrita falha.
Um comando post-deploy roda numa cópia avulsa da imagem nova e não monta o volume persistente, então não grava nesse disco. Esse limite está na CLI de deployments.
Ações do volume e o custo de cada uma
Abra a aba Settings do serviço. A seção Storage lista o volume. Cada ação vale na hora. Nenhuma espera o próximo deploy. O custo desta seção são os dados. A fatura é a seção seguinte.
| Ação | Efeito |
|---|---|
| Grow | Aumenta o tamanho, até 50 GB. O volume cresce online e não reinicia o serviço. A cobrança de storage passa para o tamanho novo na hora. Não dá para encolher. |
| Reset data | Apaga tudo que está no volume e reinicia o serviço num volume vazio. O volume mantém o tamanho e o path de mount. Um banco reinicia recém-inicializado, com as credenciais atuais. |
| Detach volume | Apaga o volume e os dados, e mantém o serviço. O serviço para e depois faz deploy da imagem atual sem storage persistente. Os backups agendados dele são desligados. |
| Apagar o serviço | Apaga o volume anexado e os dados dele. |
Bancos precisam do volume, então oferecem Reset data e não Detach.
Reset e Detach não podem ser desfeitos. Os dois pedem que você digite o nome do serviço. Os dois esperam terminar qualquer deployment, backup ou restore em andamento. Não use isso para investigar um problema de startup sem um plano de recuperação. O comportamento atual está em Persistent storage and backups.
Backups são outro sistema
O Cloud Apps pode enviar backups do volume para um destino compatível com S3 que você controla. Um agendamento define quando os backups rodam e quantos ficam retidos. Um restore pede o nome do serviço antes de rodar. O volume continua não sendo um backup.
A CLI de storage documenta este exemplo. Troque os valores de exemplo. Mantenha as credenciais do destino fora do repositório.
export UBCTL_S3_ACCESS_KEY="..."
export UBCTL_S3_SECRET_KEY="..."
ubctl apps backups destinations create \
--name primary \
--endpoint https://s3.example.com \
--region us-east-1 \
--bucket app-backups \
--prefix unbroker
ubctl apps backups destinations ls
ubctl apps backups schedule svc_123 --destination dst_123 --cron "0 3 * * *" --retain 7
ubctl apps backups run svc_123
ubctl apps backups ls svc_123
ubctl apps backups restore svc_123 backup_123 --confirm orders-db
0 3 * * *, --retain 7 e --confirm orders-db são esse exemplo, não um agendamento padrão nem um nome padrão. --confirm é o nome do serviço.
Confira se um backup agendado termina e se o destino tem os arquivos de recuperação que você espera. Num banco, siga os requisitos de backup do motor e teste o banco restaurado, não só se os arquivos existem. Quando der, ensaie o restore num destino isolado: registros, permissões e a subida da aplicação. Um health check verde não diz o ponto de recuperação nem quanto tempo um restore leva. Anote os dois.
As cobranças do destino ficam fora da tarifa de volume da Unbroker. Conte o volume provisionado e essas cobranças antes de o disco encher. Um desenho que deixa a pasta do usuário num volume e o Postgres ao lado está em Self-host do n8n.
Notas de cobrança
Volumes persistentes exigem Pro. A tabela de planos lista como indisponíveis no Free e disponíveis no Pro. O Pro custa $25 por mês, com $25 de crédito de uso. O crédito reinicia a cada ciclo e não acumula. Se o uso elegível fica abaixo do crédito, a cobrança mensal continua sendo o preço do plano. Os valores atuais estão em preços e em Plans.
O storage é cobrado pelos bytes provisionados, não pelos bytes que os arquivos ocupam. A página de preços lista o storage a $0.2 por GB decimal provisionado ao mês. A documentação de billing escreve essa tarifa como $0.20 por GB decimal provisionado, num mês de 720 horas. Os tamanhos da plataforma costumam ser expressos em GiB binários, então um volume de 10 GiB equivale a 10.73741824 GB decimais e custa aproximadamente $2.15 por 720 horas nessa tarifa. A página de preços mostra o mesmo exemplo como 10.74 GB decimais e cerca de $2.15 por um mês de 720 horas. Intervalos parciais são rateados. A tarifa, o valor de 10 GiB sem arredondar e esse rateio estão em Billing and usage.
O tamanho do volume conta mesmo quando o app guarda poucos dados. Ele pode crescer e não pode encolher, então escolha o tamanho inicial e o plano de crescimento contra o comportamento do storage e preços. Aumentar o volume passa a cobrança de storage para o tamanho novo na hora.
Quando usar um banco gerenciado
Um volume serve para arquivos de um único escritor em um serviço. Não serve para updates concorrentes, transações, ou vários serviços lendo e escrevendo os mesmos registros.
Para isso use PostgreSQL ou outro banco. Na Unbroker as duas formas são diferentes. Um cluster gerenciado de Postgres ou MySQL é operado pelo provedor e exige Pro. Um nó de banco no Apps é uma imagem de banco e um volume persistente que você opera, inclusive a recuperação desse volume. Bancos gerenciados não estão no Free. A lista de planos está em Postgres gerenciado. Como operar o servidor que você escolheu está em Postgres em produção.
Checklist
- No Pro, decida quais arquivos precisam sobreviver a um contêiner novo. Deixe código e dependências na imagem.
- Escolha um path absoluto, como
/data. Não monte por cima do diretório da aplicação. - Aponte o app para esse path. Na ilustração de Node, defina
DATA_DIRe escreva só embaixo dele. - Anexe o volume nesse path. Confirme que o usuário de runtime consegue escrever lá.
- Crie um registro de teste, faça deploy de novo e leia outra vez. Confirme que o código novo está live e que o registro ficou.
- Deixe o tamanho num ponto de onde você possa crescer. Não dá para encolher. O teto é 50 GB.
- Trate Reset, Detach e apagar o serviço como apagar os dados. Bancos oferecem Reset, não Detach.
- Envie backups para um destino compatível com S3 que você controla. Restaure uma vez num destino isolado antes de colocar lá dados que você não consegue recriar.
- Se mais de um serviço ou réplica precisa compartilhar os dados, use um banco ou object storage externo em vez deste volume.
Perguntas frequentes
Por que meus arquivos somem depois de um redeploy?
Eles estavam no filesystem do contêiner. Os contêineres da aplicação são substituíveis, e um deploy, um restart ou um reagendamento pode trocar esse contêiner. Arquivos escritos só ali devem ser tratados como temporários. Um volume persistente é outro path. Se o app nunca escreveu no mount, o volume pode ficar vazio quando o contêiner antigo já se foi. Isso está em Persistent storage and backups.
Um volume persistente sobrevive a um redeploy?
Sim, quando o app escreve no path absoluto montado. Crie um registro de teste, faça o deploy de novo e leia outra vez. O código novo pode estar live e o registro continuar lá. Um redeploy não restaura arquivos que nunca estiveram no volume, e não desfaz Reset, Detach nem apagar o serviço.
Um volume é um backup?
Não. Um volume é o disco em uso de um serviço. Um backup é uma cópia separada num destino compatível com S3 que você controla. A página de storage diz que um volume persistente não é, por si, um backup, e que você configure e teste os backups antes de colocar nele dados que não dá para recriar.
Posso diminuir um volume?
Não. Um volume pode crescer, até 50 GB, e não pode encolher. O Grow acontece online, sem reiniciar o serviço, e a cobrança de storage passa para o tamanho novo na hora. Escolha o tamanho inicial com esse limite em vista.
Serviços com volume suportam várias réplicas?
Não. Um volume pertence a um serviço, e um serviço com volume roda uma réplica. Não é um filesystem compartilhado para várias réplicas ou vários serviços. Se mais de um escritor precisa dos mesmos dados, use um banco ou object storage externo.
O Free inclui volumes persistentes?
Não. A tabela de planos lista volumes persistentes como indisponíveis no Free e disponíveis no Pro. O Pro custa $25 por mês, com $25 de crédito de uso. Veja preços e Plans.
O que acontece se eu apagar o serviço?
Apagar o serviço apaga o volume anexado e os dados dele. Reset e Detach também apagam os dados do volume. Nenhum dos dois pode ser desfeito. Os dois pedem que você digite o nome do serviço, e os dois esperam terminar qualquer deployment, backup ou restore em andamento.
Quanto custa o storage?
A página de preços lista o storage a $0.2 por GB decimal provisionado ao mês, pelo tamanho que você provisiona, não pelo quanto o disco está cheio. A documentação de billing escreve essa tarifa como $0.20 por GB decimal provisionado, num mês de 720 horas. Um volume de 10 GiB equivale a 10.73741824 GB decimais e custa aproximadamente $2.15 por 720 horas. A página de preços mostra esse exemplo como 10.74 GB decimais e cerca de $2.15. Intervalos parciais são rateados.