Para restaurar um volume nomeado do Docker Compose no macOS, pare os serviços que gravam nele, identifique o nome exato do volume do Docker e extraia o arquivo de backup para esse volume com um contêiner temporário. O Docker Desktop mantém os volumes Linux dentro de sua VM Linux; portanto, use a CLI do Docker para acessá-los em vez de tentar editar os arquivos internos do Docker no Finder. O guia de volumes do Docker explica o método de restauração baseado em contêiner, e a visão geral de rede do Docker Desktop descreve a VM Linux usada no Mac.

Antes de restaurar: verifique o arquivo e o projeto Compose

Certifique-se de que o Docker Desktop esteja em execução, abra o Terminal e navegue até o diretório que contém o seu arquivo do Compose. Localize o arquivo de backup no Finder ou confirme seu nome no Terminal. Os exemplos abaixo presumem que ele se chame backup.tar em uma pasta chamada backup-files; ajuste esses valores para corresponder aos seus arquivos.

Inspecione o conteúdo do arquivo compactado antes de extraí-lo. Isso ajuda a determinar se os arquivos estão armazenados diretamente na raiz do arquivo ou sob um diretório pai, como data/.

tar -tf "$HOME/backup-files/backup.tar" | head -30

O comando head limita a listagem aos primeiros 30 caminhos; ele não altera o arquivo compactado. Observe se os caminhos começam com um prefixo de diretório. Você precisará extrair o nível correto para o diretório de dados da aplicação. O exemplo documentado do Docker usa --strip 1 porque o arquivo compactado contém um diretório de nível superior; não use essa opção automaticamente se o seu arquivo não tiver esse prefixo. O exemplo de restauração do Docker mostra como o caminho de extração afeta a disposição restaurada.

Identifique o nome exato do volume

Uma chave de volume do Compose, como db-data, pode não ser o nome completo do volume do Docker. O Compose geralmente adiciona o nome do projeto como prefixo, mas um volume configurado com name: ou external: true pode usar outro nome. A referência de volumes do Compose explica essas opções de nomenclatura.

Liste os volumes e inspecione a configuração do Compose para determinar qual deles o seu serviço usa:

docker volume ls
docker compose config

Na configuração renderizada do Compose, localize o mapeamento de volume do serviço e o nome do volume resolvido. Se precisar inspecionar um candidato, execute docker volume inspect VOLUME_NAME, substituindo VOLUME_NAME pelo nome real. Confirme se ele pertence ao projeto e serviço pretendidos antes de prosseguir; restaurar no volume errado pode sobrescrever dados não relacionados.

Pare os gravadores e restaure o backup

Pare os serviços do Compose antes de restaurar para que a aplicação não modifique arquivos durante a extração. Executar docker compose down para e remove os contêineres e redes do projeto; por padrão, ele mantém os volumes nomeados. Evite adicionar -v ou --volumes, o que remove os volumes nomeados gerenciados pelo Compose. A referência do compose down do Docker detalha esse comportamento.

docker compose down

Defina uma variável de shell com o nome exato do volume confirmado e extraia o arquivo compactado usando um contêiner temporário. Este exemplo usa a imagem oficial alpine, monta a pasta de backup como somente leitura e monta o volume de destino em /restore. Substitua myproject_db-data se o seu nome real for diferente. A imagem deve estar disponível localmente ou o Docker deve ser capaz de baixá-la via pull.

VOLUME_NAME='myproject_db-data'
BACKUP_DIR="$HOME/backup-files"

docker run --rm \
  --mount "type=volume,source=$VOLUME_NAME,target=/restore" \
  --mount "type=bind,source=$BACKUP_DIR,target=/backup,readonly" \
  alpine sh -c 'cd /restore && tar -xf /backup/backup.tar --strip-components=1'

Este comando pressupõe que o arquivo compactado possui um nível de diretório delimitador, por exemplo data/file.db. Se a listagem do arquivo compactado mostrou arquivos diretamente em sua raiz, remova --strip-components=1. Se os caminhos tiverem um prefixo comum diferente, escolha o número de componentes a remover para que os arquivos esperados pela aplicação fiquem diretamente em /restore. A sintaxe --mount anexa explicitamente um volume nomeado e um diretório do host; o Docker documenta essas opções de montagem e o padrão de restauração em seu guia de volumes.

A extração substitui os arquivos com caminhos correspondentes, mas não remove arquivos não relacionados que já estejam no volume. Se você precisar de um espelhamento exato do backup, uma extração no estilo mesclagem não é suficiente: primeiro faça um backup separado do volume atual e, em seguida, use um procedimento de limpeza planejado após confirmar o arquivo compactado e o destino. Não execute um comando genérico de exclusão em um volume que você não tenha identificado.

Inicie o projeto e verifique o resultado

Inicie os serviços do Compose novamente:

docker compose up -d

O Compose reutiliza um volume existente declarado no projeto, criando um caso ele não exista. A referência de volumes do Compose documenta esse comportamento. Verifique os logs do serviço e, quando aplicável, use as verificações de integridade ou de recuperação de banco de dados da própria aplicação. Confirme se os registros ou arquivos esperados estão presentes antes de considerar a restauração como concluída.

Se o serviço relatar um diretório de dados vazio, confira novamente o nome do volume, o caminho do diretório do host e a estrutura de diretórios do arquivo compactado. Além disso, verifique se o arquivo de backup é compatível com a versão da aplicação e se o backup foi realizado em um estado a partir do qual a aplicação possa se recuperar. Uma extração bem-sucedida com tar apenas confirma que os arquivos foram descompactados; ela não garante que os dados da aplicação sejam válidos.

Fontes