Docs/ Infraestrutura/ Armazenamento e Volumes

Armazenamento e Volumes

Armazenamento persistente para seus contêineres, com suporte para disco local, S3 e Cloudflare R2 como backends de armazenamento.

O que são Volumes

Por padrão, sistemas de arquivos de contêineres são efêmeros -- quaisquer dados escritos dentro de um contêiner são perdidos quando o contêiner reinicia ou é reimplantado. Volumes resolvem isso fornecendo armazenamento persistente que sobrevive a eventos do ciclo de vida do contêiner.

Casos de uso comuns para volumes incluem:

Diretórios de dados de bancos de dados (PostgreSQL, MySQL, MongoDB)
Arquivos enviados por usuários e mídia
Logs de aplicação que precisam persistir
Configuração compartilhada entre contêineres
Diretórios de cache que devem sobreviver a reinicializações

Note

O sh0 cria automaticamente volumes para serviços de banco de dados (PostgreSQL, MySQL, Redis, MongoDB). Você só precisa criar volumes manualmente para armazenamento personalizado de aplicação.

Criando Volumes Persistentes

Você pode criar volumes pelo painel ou pela API.

Via Painel:

Navegue até a aba Configurações → Armazenamento da sua aplicação.
Clique em Adicionar Volume.
Insira um nome de volume (ex.: uploads) e o caminho de montagem no contêiner.
Opcionalmente defina um limite de tamanho.
Clique em Criar.

Creating a new persistent volume in the dashboard

Via API:

Terminal

curl -X POST https://your-server:9000/api/apps/my-app/mounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "uploads",
    "mount_path": "/app/uploads",
    "size_limit_mb": 5120
  }'

Montando Volumes em Contêineres

Quando você cria um volume, especifica o caminho dentro do contêiner onde ele será montado. Os dados do volume são armazenados no sistema de arquivos do host e montados no contêiner no caminho especificado.

docker-compose.yml

services:
  web:
    image: my-app:latest
    volumes:
      - uploads:/app/uploads
      - logs:/var/log/app

volumes:
  uploads:
  logs:

Ao implantar via Docker Compose, o sh0 cria e gerencia automaticamente os volumes nomeados definidos no seu arquivo compose.

Volume mount configuration showing container path mapping

Warning

Evite montar volumes em caminhos que contêm código da aplicação (ex.: /app). Isso sobrescreverá seu código implantado com o que estiver no volume. Monte volumes em subdiretórios como /app/data ou /app/uploads.

Caminhos de Volume e Permissões

O sh0 armazena dados de volumes no host em:

Host Path

/var/lib/sh0/volumes/{stack_id}/{volume_name}

Permissões são definidas para corresponder ao usuário do contêiner. Se sua aplicação roda como usuário não-root (que o sh0 impõe por padrão), o diretório do volume pertence ao UID/GID desse usuário.

Tip

Se encontrar erros de permissão, verifique o UID da sua aplicação dentro do contêiner com id e garanta que o diretório do volume tenha a propriedade correspondente. Você pode corrigir permissões pelo terminal do sh0.

Provedores de Armazenamento

Além de volumes locais, o sh0 suporta provedores de armazenamento externo para backups e object storage.

Disco Local

O backend de armazenamento padrão. Volumes são armazenados diretamente no sistema de arquivos do servidor. Esta é a opção mais simples e oferece o melhor desempenho para a maioria das cargas de trabalho.

Amazon S3

Configure um bucket S3 para backups e armazenamento de arquivos grandes. Navegue até Configurações → Provedores de Armazenamento para adicionar suas credenciais S3.

Terminal

curl -X POST https://your-server:9000/api/storage-providers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-backups",
    "type": "s3",
    "bucket": "my-backups",
    "region": "us-east-1",
    "access_key_id": "AKIA...",
    "secret_access_key": "..."
  }'

S3 storage provider configuration form

Cloudflare R2

O Cloudflare R2 é um object store compatível com S3 com zero taxas de egress. O sh0 suporta R2 nativamente -- configure da mesma forma que S3, usando seu endpoint R2:

Terminal

curl -X POST https://your-server:9000/api/storage-providers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "r2-backups",
    "type": "s3",
    "bucket": "my-backups",
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "access_key_id": "...",
    "secret_access_key": "..."
  }'

Cloudflare R2 storage provider setup

Gerenciando Armazenamento

O painel de Armazenamento no dashboard mostra todos os volumes de uma stack, seus tamanhos e em quais contêineres estão montados. A partir daqui você pode:

Navegar arquivos: Use o gerenciador de arquivos integrado para visualizar o conteúdo dos volumes.
Baixar arquivos: Exportar arquivos individuais ou diretórios inteiros.
Redimensionar: Aumentar o limite de tamanho de um volume.
Excluir: Remover um volume e todos os seus dados (requer confirmação).
Backup: Acione um backup manual para um provedor de armazenamento configurado.

Storage management panel showing volumes and their usage

Danger

Excluir um volume destrói permanentemente todos os dados que ele contém. Esta ação não pode ser desfeita. Sempre crie um backup antes de excluir um volume.

Custom Domains

Scaling