Para restaurar un volumen con nombre de Docker Compose en macOS, detenga los servicios que escriben en él, identifique el nombre exacto del volumen de Docker y extraiga el archivo de copia de seguridad en dicho volumen con un contenedor temporal. Docker Desktop mantiene los volúmenes de Linux dentro de su máquina virtual Linux, por lo que debe usar la CLI de Docker para acceder a ellos en lugar de intentar editar los archivos internos de Docker en Finder. La guía de volúmenes de Docker explica el método de restauración basado en contenedores, y la descripción general de redes de Docker Desktop describe la máquina virtual Linux utilizada en Mac.

Antes de restaurar: compruebe el archivo comprimido y el proyecto de Compose

Asegúrese de que Docker Desktop esté en ejecución, luego abra Terminal y cambie al directorio que contiene su archivo de Compose. Localice el archivo comprimido en Finder o confirme su nombre en Terminal. Los siguientes ejemplos asumen que se llama backup.tar y está en una carpeta llamada backup-files; ajuste estos valores para que coincidan con sus archivos.

Inspeccione el contenido del archivo comprimido antes de extraerlo. Esto le ayuda a determinar si los archivos están almacenados directamente en la raíz del archivo o bajo un directorio principal como data/.

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

El comando head limita la lista a las primeras 30 rutas; no altera el archivo. Fíjese en si las rutas comienzan con el prefijo de un directorio. Necesitará extraer el nivel correcto en el directorio de datos de la aplicación. El ejemplo documentado por Docker usa --strip 1 porque su archivo contiene un directorio de nivel superior; no utilice esa opción automáticamente si su archivo no tiene tal prefijo. El ejemplo de restauración de Docker muestra cómo influye la ruta de extracción en la estructura restaurada.

Identifique el nombre exacto del volumen

Una clave de volumen en Compose como db-data podría no ser el nombre completo del volumen en Docker. Compose suele anteponerle el nombre del proyecto, pero un volumen configurado con name: o external: true puede tener otro nombre. La referencia de volúmenes de Compose explica estas opciones de nomenclatura.

Liste los volúmenes e inspeccione la configuración de Compose para determinar cuál utiliza su servicio:

docker volume ls
docker compose config

En la configuración resultante de Compose, busque el mapeo de volumen del servicio y el nombre de volumen resuelto. Si necesita inspeccionar un candidato, ejecute docker volume inspect VOLUME_NAME, sustituyendo VOLUME_NAME por el nombre real. Confirme que pertenece al proyecto y servicio deseados antes de proceder; restaurar en el volumen incorrecto puede sobrescribir datos no relacionados.

Detenga los procesos de escritura y restaure la copia de seguridad

Detenga los servicios de Compose antes de restaurar para que la aplicación no modifique archivos durante la extracción. Al ejecutar docker compose down se detienen y eliminan los contenedores y las redes del proyecto; por defecto, se conservan los volúmenes con nombre. Evite añadir -v o --volumes, ya que esto elimina los volúmenes con nombre gestionados por Compose. La referencia de compose down de Docker detalla este comportamiento.

docker compose down

Asigne a una variable de entorno de shell el nombre exacto del volumen que confirmó y, a continuación, extraiga el archivo usando un contenedor temporal. Este ejemplo utiliza la imagen oficial alpine, monta la carpeta de copia de seguridad en modo de solo lectura y monta el volumen de destino en /restore. Sustituya myproject_db-data si su nombre real difiere. La imagen debe estar disponible localmente o Docker debe poder descargarla.

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 asume que el archivo comprimido incluye un nivel de directorio contenedor, por ejemplo data/file.db. Si al listar el archivo los ficheros aparecían directamente en su raíz, elimine --strip-components=1. Si las rutas tienen un prefijo común distinto, elija la cantidad de componentes que debe descartar para que los archivos requeridos por la aplicación queden directamente bajo /restore. La sintaxis --mount monta explícitamente un volumen con nombre y un directorio del host; Docker documenta estas opciones de montaje y el patrón de restauración en su guía de volúmenes.

La extracción reemplaza los archivos con rutas coincidentes, pero no elimina otros archivos no relacionados que ya estén presentes en el volumen. Si necesita una réplica exacta de la copia de seguridad, no basta con una extracción combinada: primero haga una copia de seguridad independiente del volumen actual y, a continuación, realice una limpieza controlada tras confirmar el archivo y el destino. No ejecute un comando general de eliminación en un volumen que no haya identificado plenamente.

Inicie el proyecto y compruebe el resultado

Inicie de nuevo los servicios de Compose:

docker compose up -d

Compose reutiliza los volúmenes existentes declarados en el proyecto, o bien los crea si no existen. La referencia de volúmenes de Compose documenta este comportamiento. Revise los registros del servicio y, según corresponda, utilice las comprobaciones de integridad o de recuperación de base de datos propias de la aplicación. Confirme que los registros o archivos esperados están presentes antes de dar por finalizada la restauración.

Si el servicio reporta un directorio de datos vacío, vuelva a comprobar el nombre del volumen, la ruta del directorio del host y la estructura de directorios del archivo comprimido. Asimismo, verifique que el archivo sea compatible con la versión de la aplicación y que la copia de seguridad se haya tomado en un estado a partir del cual la aplicación pueda recuperarse. Una extracción correcta con tar solo confirma que los archivos se descomprimieron; no garantiza que los datos de la aplicación sean válidos.

Fuentes