Gerenciamento Persistente de Dados: Escolhendo o Tipo de Volume Docker Correto

Os contêineres Docker são projetados para serem substituíveis. Os dados gravados na camada gravável do contêiner podem sobreviver a uma simples parada/inicialização, mas estão vinculados àquele contêiner. Remova ou recrie o contêiner e esses dados desaparecerão junto. Esse é um lugar ruim para arquivos de banco de dados, ativos enviados, filas ou qualquer coisa que você ficaria chateado em perder.

O Docker oferece três opções comuns de montagem: volumes nomeados, bind mounts e montagens tmpfs. Elas resolvem problemas diferentes. Um contêiner Postgres de produção, um contêiner de desenvolvimento Node.js local e um diretório temporário para segredos temporários não devem usar o mesmo padrão de armazenamento.

---

O Panorama dos Mecanismos de Armazenamento do Docker

O Docker pode usar drivers de volume para armazenamento remoto, mas a maioria das decisões do dia a dia se resume a esses três tipos de montagem gerenciados pelo Docker Engine ou pelo kernel do host.

1. Volumes Nomeados: O Padrão de Produção

Volumes Nomeados são o mecanismo preferido para armazenamento persistente de dados na maioria dos ambientes de produção. Eles são totalmente gerenciados pelo Docker Engine, abstraindo o caminho do sistema de arquivos do host subjacente do usuário.

Recursos e Vantagens

• Persistência: Os dados persistem mesmo se o contêiner que os criou for removido.
• Portabilidade: A definição do contêiner não depende de um caminho do host codificado, o que facilita a movimentação de implantações entre máquinas.
• Gerenciamento: Os dados são armazenados na área de volumes do Docker, geralmente em /var/lib/docker/volumes/ no Linux. Você os gerencia com docker volume ls, docker volume inspect e trabalhos de backup.
• Backup e Migração: Volumes nomeados são simples de fazer backup se você usar um contêiner auxiliar, snapshot do sistema de arquivos ou backup no nível de armazenamento. Para bancos de dados, prefira ferramentas de backup que reconheçam o banco de dados quando a consistência for importante.

Casos de Uso

• Bancos de dados, quando você também tem um processo real de backup e restauração.
• Estado do aplicativo e arquivos de configuração críticos.
• Dados que precisam ser compartilhados entre contêineres no mesmo host.

Exemplo Prático: Criando e Anexando um Volume Nomeado

# 1. Crie o volume
docker volume create db_storage

# 2. Execute um contêiner, montando o volume no caminho necessário
docker run -d \
  --name postgres_db \
  -e POSTGRES_PASSWORD=securepass \
  --mount source=db_storage,target=/var/lib/postgresql/data \
  postgres:16

# 3. Inspecione os detalhes do volume
docker volume inspect db_storage

2. Bind Mounts: Desenvolvimento Local e Interação com o Host

Bind mounts permitem mapear um arquivo ou diretório arbitrário do host para um contêiner. Ao contrário dos Volumes Nomeados, os Bind Mounts dependem inteiramente da estrutura exata de diretórios do host.

Recursos e Limitações

• Atualizações Instantâneas: O principal benefício é a sincronização em tempo real. As alterações feitas no host (por exemplo, atualizar o código no seu IDE) são refletidas instantaneamente dentro do contêiner em execução, tornando-os ideais para fluxos de trabalho de desenvolvimento.
• Não Portabilidade: Bind mounts dependem do host. Se o caminho do host especificado não existir em outra máquina, o Docker pode falhar ou criar um diretório dependendo da sintaxe e do contexto.
• Problemas de Permissão: Propriedade e permissões (UID/GID) geralmente causam atrito, especialmente ao executar contêineres como usuários não root. O usuário do contêiner deve ter permissões para ler/gravar no caminho do host.
• Risco de Segurança: Expor diretórios do host pode ser perigoso se o processo do contêiner for comprometido ou se a montagem for gravável por engano.

Casos de Uso

• Desenvolvimento Local: Montar código-fonte para depuração ao vivo ou recarga automática.
• Arquivos de Configuração: Injetar configuração ou credenciais específicas do host (por exemplo, /etc/timezone).
• Acessar Recursos do Host: Montar um diretório local para registro ou diagnóstico.

Exemplo Prático: Fluxo de Trabalho de Desenvolvimento

Montar o diretório de trabalho atual ($(pwd)) no caminho do código-fonte do aplicativo dentro do contêiner e configurá-lo como somente leitura para arquivos de configuração.

# Monte o diretório atual para desenvolvimento
docker run -it --rm \
  --name dev_server \
  --mount type=bind,source=$(pwd)/src,target=/app/src \
  --mount type=bind,source=$(pwd)/config/app.conf,target=/etc/app/app.conf,readonly \
  node:22

Dica: Sempre use a sintaxe --mount (type=bind, source=..., target=...) para clareza, especialmente ao misturar tipos de volume, embora a sintaxe mais curta -v (/host/path:/container/path) ainda seja comum para bind mounts simples.

3. Montagens Tmpfs: Armazenamento de Alta Velocidade e Não Persistente

As montagens tmpfs armazenam dados em armazenamento baseado em memória. Elas são rápidas para muitas cargas de trabalho temporárias, mas os dados não são persistidos em disco. Quando o contêiner para ou o sistema host reinicia, os dados desaparecem.

Recursos e Limitações

• Velocidade: Geralmente rápida porque os dados residem em armazenamento baseado em memória.
• Não Persistência: Os dados são completamente voláteis. Útil para dados altamente confidenciais que não devem permanecer no disco.
• Limitação de Recursos: Limitado pela memória disponível do host. Não é adequado para grandes conjuntos de dados.
• Escopo da Plataforma: tmpfs é um recurso do Linux. O Docker Desktop pode executar contêineres Linux dentro de uma VM, portanto, o comportamento não é o mesmo que um host Linux nativo.

Casos de Uso

• Arquivos de sessão temporários ou arquivos de cache que podem desaparecer com segurança.
• Mecanismos de cache (por exemplo, arquivos temporários do Redis).
• Operações sensíveis à segurança onde os artefatos devem ser destruídos imediatamente após a execução.

Exemplo Prático: Armazenando em Cache Arquivos Temporários

# Execute um contêiner usando tmpfs para o diretório /app/cache
docker run -d \
  --name fast_cache \
  --mount type=tmpfs,destination=/app/cache,tmpfs-size=512m \
  my_web_server:latest

Resumo de Comparação e Matriz de Decisão

Escolher o tipo de volume correto depende inteiramente da persistência, portabilidade e necessidades de acesso necessárias.

Recurso	Volumes Nomeados	Bind Mounts	Montagens Tmpfs
Persistência	Alta (Gerenciado pelo Docker)	Alta (Depende do FS do host)	Nenhuma (Volátil, apenas RAM)
Portabilidade	Excelente	Ruim (Dependente do caminho do host)	N/A (Apenas hosts Linux)
Desempenho	Geralmente bom, depende do armazenamento de suporte	Variável, depende do caminho do host e do compartilhamento do sistema de arquivos	Geralmente o mais rápido para E/S temporária
Localização dos Dados	Diretório interno do Docker	Diretório específico do host	Memória do host (RAM)
Gerenciamento	Ferramentas CLI do Docker (docker volume)	Gerenciado pelo SO do host	Automático
Caso de Uso Principal	Dados de produção, bancos de dados, armazenamento compartilhado	Desenvolvimento local, injeção de configuração	Cache, gerenciamento de sessão, dados temporários seguros

Melhores Práticas para Gerenciamento de Dados

Padronizando o Armazenamento Persistente

Para a maioria dos contêineres de produção de host único que precisam de persistência, os volumes nomeados são o padrão limpo. Eles evitam caminhos de host codificados e tornam as definições de contêiner mais fáceis de reutilizar. Em ambientes orquestrados, use o sistema de volume persistente da plataforma em vez de assumir que um volume Docker local é suficiente.

Lidando com Permissões de Arquivo

Ao usar Bind Mounts, incompatibilidades de permissão são uma dor de cabeça comum. Se o usuário dentro do contêiner tentar gravar em um caminho de volume que pertence a um usuário/grupo diferente no host, a operação falhará.

Faça com que o usuário dentro do contêiner corresponda à propriedade dos arquivos montados ou ajuste o diretório do host deliberadamente. Evite resolver todos os problemas de permissão com um contêiner root; funciona até criar artefatos de build de propriedade root em toda a máquina do desenvolvedor.

Use Montagens Somente Leitura para Segurança

Se você estiver montando arquivos de configuração, recursos estáticos ou credenciais que o contêiner não deve modificar, sempre especifique o volume como somente leitura. Isso evita a exclusão ou modificação acidental de arquivos críticos.

# Exemplo de uma montagem somente leitura
docker run -d \
  --mount type=bind,source=/etc/my_key.pem,target=/app/key.pem,readonly \
  my_app

Evitando Bind Mounts Raiz do Host

É fortemente recomendado evitar vincular diretórios raiz confidenciais ou grandes (por exemplo, -v /:/host). Essa prática cria vulnerabilidades de segurança significativas e pode tornar o gerenciamento de contêiner instável devido a efeitos colaterais indesejados.

Limpeza de Volume

O Docker não remove automaticamente volumes nomeados quando os contêineres são removidos. Volumes anônimos também podem se acumular quando os contêineres são recriados repetidamente. Inspecione antes de podar, especialmente em hosts compartilhados:

docker volume ls
docker system df -v

# Remova volumes locais não utilizados depois de verificar que eles não são necessários
docker volume prune

Backup e Restauração Devem Orientar a Escolha

O tipo de montagem é apenas metade da decisão. A outra metade é como você restaurará os dados em um dia ruim.

Para um volume nomeado que armazena arquivos comuns, um contêiner auxiliar pode criar um arquivo tar:

docker run --rm \
  --mount source=db_storage,target=/data,readonly \
  --mount type=bind,source=$(pwd),target=/backup \
  alpine:3.20 \
  tar -czf /backup/db_storage.tar.gz -C /data .

Esse padrão é bom para arquivos estáticos ou serviços parados. Não é suficiente para um banco de dados ativo, a menos que o banco de dados esteja em um estado consistente. Para Postgres, MySQL, MongoDB e sistemas semelhantes, use ferramentas de backup nativas do banco de dados ou snapshots de armazenamento coordenados com o banco de dados. Um tarball de um diretório de banco de dados em execução pode parecer um backup e falhar durante a restauração.

Restaurar um volume nomeado é a ideia inversa:

docker volume create db_storage_restored
docker run --rm \
  --mount source=db_storage_restored,target=/data \
  --mount type=bind,source=$(pwd),target=/backup,readonly \
  alpine:3.20 \
  tar -xzf /backup/db_storage.tar.gz -C /data

Teste isso antes de precisar. Uma estratégia de volume que nunca foi restaurada não é uma estratégia; é um palpite.

Exemplos de Compose para Projetos Reais

No Compose, volumes nomeados são simples e legíveis:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

Para desenvolvimento local, bind mounts geralmente são melhores porque você quer que as alterações de origem no host apareçam dentro do contêiner:

services:
  app:
    image: node:22
    working_dir: /app
    command: npm run dev
    volumes:
      - ./src:/app/src
      - ./package.json:/app/package.json:ro

Observe o sinalizador somente leitura em package.json. É um pequeno hábito, mas impede que um contêiner reescreva arquivos que ele só deve ler.

Para tmpfs no Compose:

services:
  worker:
    image: my-worker:latest
    tmpfs:
      - /run/secrets:size=64m

Use isso para dados temporários, não para qualquer coisa que você espera inspecionar após uma falha.

Modos de Falha Comuns

A falha de armazenamento Docker mais comum é montar o caminho errado. Se o aplicativo grava em /var/lib/mysql mas a imagem espera /var/lib/mysql/data, o contêiner ainda é executado e os dados ainda desaparecem quando você o recria. Sempre confirme a documentação da imagem e inspecione o contêiner em execução:

docker inspect my_container --format '{{json .Mounts}}'

Outra falha comum é confundir volumes anônimos com volumes nomeados. Se uma imagem declara um VOLUME e você não fornece um volume nomeado, o Docker pode criar um anônimo. Os dados persistem, mas o nome não é significativo, então as pessoas o perdem durante a limpeza ou migração.

Permissões são a próxima dor de cabeça. Se um diretório montado por bind é propriedade do UID 501 no macOS ou UID 1000 no Linux, mas o processo do contêiner é executado como UID 999, as gravações podem falhar. Volumes nomeados geralmente evitam confusão de caminho do host, mas a propriedade dentro do volume ainda importa. Inicialize a propriedade deliberadamente em vez de alterar permissões até que o erro desapareça.

Finalmente, lembre-se de que os volumes Docker locais são locais. Eles não seguem um contêiner para outro host por conta própria. No Swarm, Kubernetes, Nomad ou plataformas de contêiner em nuvem, o armazenamento persistente precisa de volumes cientes da plataforma, armazenamento remoto ou um serviço de banco de dados projetado para esse ambiente.

Rotule volumes importantes quando suas ferramentas suportarem e documente qual serviço possui cada um. A propriedade clara impede que scripts de limpeza excluam dados que apenas parecem não utilizados.

Uma Regra de Decisão Simples

Quando você não tiver certeza, pergunte quem possui os dados. Se o Docker os possui e o caminho do host não é significativo, use um volume nomeado. Se um humano ou ferramenta externa no host os possui, use um bind mount. Se ninguém deve possuí-los após a saída do contêiner, use tmpfs.

Essa regra cobre a maioria dos casos. Um diretório de banco de dados é de propriedade do contêiner, então um volume nomeado se encaixa. O código-fonte é de propriedade do desenvolvedor, então um bind mount se encaixa. Um diretório temporário de descriptografia para um trabalho deve desaparecer, então tmpfs se encaixa. Os casos confusos são uploads compartilhados, logs e relatórios gerados. Para esses, decida se a plataforma de contêiner, o host ou um serviço de armazenamento externo é o verdadeiro proprietário antes de escolher o tipo de montagem.

A versão curta é: use volumes nomeados para dados persistentes de propriedade do contêiner, bind mounts quando o caminho do host em si fizer parte do fluxo de trabalho e tmpfs para dados que devem ser rápidos e descartáveis. Em seguida, anote como cada volume importante é copiado e restaurado. Persistência sem um teste de restauração é apenas esperança com um ponto de montagem.