Proxmox BS: Restaurar archivos desde copia de VM
Introducción
Este tutorial explica cómo usar Proxmox Backup Server para realizar una restauración a nivel de archivo desde una copia de seguridad de una VM sin desplegar la máquina virtual completa. Aprenderá a recuperar archivos individuales mediante el explorador de archivos de copias de seguridad de Proxmox en la interfaz web de Proxmox VE y a realizar la recuperación de archivos de Proxmox desde la línea de comandos con proxmox-backup-client. Este flujo de trabajo es útil cuando necesita restaurar archivos individuales contenidos en las copias de seguridad de Proxmox sin realizar una restauración completa de la VM.
Público objetivo: Administradores de sistemas de nivel intermedio
Tiempo estimado: 20-40 minutos
Objetivo final: Al terminar este tutorial, podrá restaurar archivos concretos desde una copia de seguridad de una VM en Proxmox Backup Server sin restaurar la VM completa.
Requisitos previos
Antes de empezar, asegúrese de contar con lo siguiente:
- Un host de Proxmox VE en funcionamiento con un almacenamiento de Proxmox Backup Server configurado.
- Proxmox Backup Server 3.x o 4.x con un datastore existente.
- Una copia de seguridad de VM completada y almacenada en el datastore de PBS.
- Acceso a la interfaz web de Proxmox VE con permisos para explorar copias de seguridad y restaurar archivos.
- Acceso al shell del host de Proxmox VE para el método CLI.
- El comando proxmox-backup-client disponible en el host de Proxmox VE.
- Acceso al shell como root para el método de mapeo por CLI, ya que el mapeo de dispositivos loop y el montaje de sistemas de archivos requieren privilegios elevados.
- El archivo de clave de cifrado si la copia de seguridad de la VM utiliza cifrado del lado del cliente.
- Conocimientos básicos de sistemas de archivos de Linux, puntos de montaje y almacenamiento de copias de seguridad de Proxmox VE.
La interfaz web de Proxmox VE es el método recomendado para la mayoría de las tareas de recuperación de archivos individuales. El método CLI resulta útil cuando necesita acceso por shell, automatización o recuperación desde un nodo donde la interfaz web no es práctica.
Paso 1: Comprenda las opciones de restauración a nivel de archivo
Proxmox Backup Server almacena las copias de seguridad de máquinas virtuales de Proxmox VE como copias de imágenes de disco a nivel de bloque. Esto significa que una copia de seguridad de VM suele contener archivos como drive-scsi0.img.fidx, qemu-server.conf.blob y client.log.blob, y no un árbol de directorios normal.
Para los flujos de recuperación granular de archivos en Proxmox VE, dispone de dos opciones prácticas:
- Usar la interfaz web de Proxmox VE para explorar el snapshot de la copia de seguridad y descargar archivos.
- Usar proxmox-backup-client map para mapear una imagen de disco de VM de la copia de seguridad a un dispositivo loop local y, después, montar el sistema de archivos del invitado en modo de solo lectura.
El botón File Restore de Proxmox VE abre un explorador de archivos para el contenido de la copia de seguridad. El comando proxmox-backup-client map mapea una imagen de unidad de la copia de seguridad de una VM a un dispositivo loopback local y debe ir seguido de unmap una vez finalizada la recuperación.
No monte el sistema de archivos de una VM recuperada en modo lectura-escritura a menos que comprenda por completo el riesgo. Para la recuperación de archivos, monte el sistema de archivos en modo de solo lectura y copie los archivos fuera.
Paso 2: Restaure archivos individuales mediante la interfaz web de Proxmox VE
Use este método cuando quiera recuperar archivos concretos de la forma más sencilla, sin desplegar la VM completa.
Abra la vista de copias de seguridad
- Inicie sesión en la interfaz web de Proxmox VE.
- En el árbol de navegación de la izquierda, seleccione la VM.
- Abra la pestaña Backup.
- Seleccione el almacenamiento de Proxmox Backup Server en el selector de almacenamiento si su entorno tiene varios almacenamientos de copias de seguridad.
Debería ver una lista de los snapshots de copia de seguridad disponibles para la VM seleccionada.
Abra el explorador de archivos de copias de seguridad de Proxmox
- Seleccione el snapshot de la copia de seguridad que contiene el archivo que necesita.
- Haga clic en File Restore.
- Espere a que Proxmox VE abra el explorador de archivos de la copia de seguridad.
- Expanda el disco de la VM que contiene el sistema operativo invitado o el volumen de datos.
Ahora está explorando snapshots de copias de seguridad a través de la interfaz de Proxmox VE. Esta vista respalda el flujo de restauración de archivos de Proxmox Backup Server y le permite recuperar datos seleccionados sin realizar una restauración completa de la VM.
Descargue el archivo necesario
- Navegue hasta el directorio que contiene el archivo.
- Seleccione el archivo.
- Haga clic en Download.
- Guarde el archivo en su estación de trabajo.
Debería recibir el archivo seleccionado a través del navegador. Con esto concluye una restauración a nivel de archivo desde el navegador a partir de la copia de seguridad de la VM.
Si la VM tiene varios discos, revise cada disco en el explorador de archivos hasta encontrar el sistema de archivos correcto. Por ejemplo, el disco del sistema operativo puede ser drive-scsi0, mientras que los datos de la aplicación pueden estar en drive-scsi1.
Paso 3: Prepare el entorno CLI
Use este método cuando restaure datos de copias de seguridad del datastore de PBS desde la línea de comandos.
Defina las variables de recuperación
Ejecute los siguientes comandos en el host de Proxmox VE. Sustituya los marcadores de posición por valores de su entorno.
export PBS_REPOSITORY="<PBS_USER>@<PBS_REALM>@<PBS_SERVER>:<DATASTORE>" export PBS_SNAPSHOT="vm/<VM_ID>/<SNAPSHOT_TIMESTAMP>" export PBS_ARCHIVE="drive-scsi0.img" export RESTORE_MOUNT="/mnt/pbs-file-restore" export RESTORE_TARGET="/root/restored-from-pbs" export PBS_PASSWORD="<PBS_USER_PASSWORD>" export PBS_FINGERPRINT="<PBS_SERVER_FINGERPRINT>"
Valores de ejemplo:
export PBS_REPOSITORY="root@[email protected]:backup" export PBS_SNAPSHOT="vm/101/2026-06-04T01:30:00Z" export PBS_ARCHIVE="drive-scsi0.img" export RESTORE_MOUNT="/mnt/pbs-file-restore" export RESTORE_TARGET="/root/restored-from-pbs" export PBS_PASSWORD="12345678" export PBS_FINGERPRINT="b1:89:bd:c9:b1:f8:33..."
Las variables definen el repositorio de PBS, el snapshot de la copia de seguridad de la VM, el archivo de disco que se va a mapear, el punto de montaje temporal y el destino local de la recuperación. Establezca las variables de entorno PBS_PASSWORD y PBS_FINGERPRINT. Obtenga la huella (fingerprint) del certificado en Proxmox Backup Server ejecutando proxmox-backup-manager cert info.
Durante la primera conexión, el comando login solicita de forma interactiva que confirme la huella del certificado e introduzca la contraseña. Sin estas variables, los comandos automatizados fallan con certificate validation failed cuando falta la huella o con no password input mechanism available cuando no se proporciona una contraseña.
Inicie sesión en Proxmox Backup Server
Ejecute el comando de inicio de sesión:
proxmox-backup-client login --repository "$PBS_REPOSITORY"
Salida esperada:
Password:
Introduzca la contraseña del usuario de PBS. Si la autenticación se realiza correctamente, el cliente almacena un ticket temporal.
Si utiliza un token de API, establezca PBS_PASSWORD solo para la sesión de shell actual y elimínela con unset después de la recuperación. No almacene secretos de tokens en el historial del shell ni en scripts, a menos que proteja los permisos del archivo.
Paso 4: Identifique el snapshot de la copia de seguridad de la VM y el archivo de disco
Liste los grupos de copias de seguridad del repositorio de PBS:
proxmox-backup-client list --repository "$PBS_REPOSITORY"
Ejemplo de salida: tabla de copias de seguridad.
Liste los snapshots del grupo de la VM:
proxmox-backup-client snapshot list vm/<VM_ID> \ --repository "$PBS_REPOSITORY"
Ejemplo de salida: tabla de snapshots.
Liste los archivos del snapshot seleccionado:
proxmox-backup-client snapshot files "$PBS_SNAPSHOT" \ --repository "$PBS_REPOSITORY"
Ejemplo de salida:
client.log.blob drive-scsi0.img.fidx index.json.blob qemu-server.conf.blob
Al mapear un archivo de disco de VM, use el nombre del archivo sin el sufijo .fidx. Por ejemplo, use drive-scsi0.img, no drive-scsi0.img.fidx.
Paso 5: Mapee el disco de la copia de seguridad de la VM a un dispositivo loop
Cree los directorios de restauración:
mkdir -p "$RESTORE_MOUNT" "$RESTORE_TARGET"
Mapee la imagen de disco de la VM desde PBS:
proxmox-backup-client map "$PBS_SNAPSHOT" "$PBS_ARCHIVE" \ --repository "$PBS_REPOSITORY"
Ejemplo de salida:
/dev/loop0
Guarde el dispositivo loop devuelto en una variable:
export LOOP_DEVICE="/dev/loop0"
El comando map mapea una imagen de unidad de la copia de seguridad de una VM a un dispositivo loopback local.
Use este método CLI únicamente con copias de seguridad de confianza. Un sistema de archivos montado puede contener rutas maliciosas, archivos especiales o metadatos inesperados.
Paso 6: Inspeccione el disco mapeado
Liste las particiones y los sistemas de archivos:
lsblk -f "$LOOP_DEVICE"
Ejemplo de salida:
NAME FSTYPE LABEL UUID MOUNTPOINTS loop0 ├─loop0p1 vfat 1111-2222 └─loop0p2 ext4 aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
Si las particiones no aparecen, pida al kernel que lea la tabla de particiones:
partx -a "$LOOP_DEVICE"
A continuación, vuelva a comprobarlo:
lsblk -f "$LOOP_DEVICE"
Ahora debería ver dispositivos de partición como /dev/loop0p1 y /dev/loop0p2.
Los invitados Linux suelen usar ext4, XFS o Logical Volume Manager. Los invitados Windows suelen usar NTFS. La interfaz web suele ser más sencilla para recuperar archivos de Windows porque gestiona por usted una mayor parte del flujo de trabajo del explorador de archivos.
Paso 7: Monte el sistema de archivos del invitado en modo de solo lectura
Seleccione la partición que contiene los archivos que necesita. En este ejemplo, el sistema de archivos raíz de Linux es /dev/loop0p2.
Móntela en modo de solo lectura:
mount -o ro /dev/loop0p2 "$RESTORE_MOUNT"
Salida esperada: el comando no debería mostrar ninguna salida cuando el montaje se realiza correctamente.
Compruebe el sistema de archivos montado:
ls "$RESTORE_MOUNT"
Ejemplo de salida:
bin boot etc home root usr var
Ahora está utilizando la línea de comandos para restaurar archivos individuales de las copias de seguridad de Proxmox sin restaurar la máquina virtual completa.
Monte un volumen LVM si el invitado usa LVM
Si lsblk -f muestra LVM2_member, busque grupos de volúmenes:
vgscan --mknodes
Ejemplo de salida:
Found volume group "ubuntu-vg" using metadata type lvm2
Active el grupo de volúmenes:
vgchange -ay ubuntu-vg
Liste los volúmenes lógicos:
lvs
Ejemplo de salida:
LV VG Attr LSize ubuntu-lv ubuntu-vg -wi-a----- 50.00g
La salida de lvs muestra todos los volúmenes lógicos detectados en el host de Proxmox VE, no solo el grupo de volúmenes del invitado, como ubuntu-vg. También puede incluir los volúmenes propios del hipervisor del grupo de volúmenes pve, como root, swap, data y los volúmenes lógicos utilizados por los discos de las máquinas virtuales.
Monte el volumen lógico en modo de solo lectura:
mount -o ro /dev/ubuntu-vg/ubuntu-lv "$RESTORE_MOUNT"
Ahora debería poder explorar el sistema de archivos restaurado del invitado en $RESTORE_MOUNT.
Paso 8: Copie archivos concretos fuera de la copia de seguridad
Cree un directorio local para los archivos recuperados:
mkdir -p "$RESTORE_TARGET"
Copie un archivo:
cp -a "$RESTORE_MOUNT/etc/hostname" "$RESTORE_TARGET/"
Salida esperada: el comando no debería mostrar ninguna salida cuando el archivo se copia correctamente.
Copie un directorio:
rsync -a "$RESTORE_MOUNT/var/www/html/" \ "$RESTORE_TARGET/html/"
Salida esperada: el comando no debería mostrar ninguna salida cuando el directorio se copia correctamente.
Verifique los archivos copiados:
find "$RESTORE_TARGET" -maxdepth 3 -type f
Ejemplo de salida:
/root/restored-from-pbs/hostname /root/restored-from-pbs/html/index.html
Use rsync -a en lugar de un simple cp cuando quiera conservar permisos, propietarios, marcas de tiempo y enlaces simbólicos en la copia recuperada.
Paso 9: Restaure archivos de una copia de seguridad de PBS basada en archivos con pxar
Este paso es opcional para la restauración a nivel de archivo de una VM, pero resulta útil cuando el snapshot de la copia de seguridad contiene un archivo de ficheros como root.pxar.
Liste los archivos del snapshot:
proxmox-backup-client snapshot files "$PBS_SNAPSHOT" \ --repository "$PBS_REPOSITORY"
Ejemplo de salida:
catalog.pcat1.didx root.pxar.didx
Abra el shell de restauración interactivo:
proxmox-backup-client catalog shell "$PBS_SNAPSHOT" root.pxar \ --repository "$PBS_REPOSITORY"
Dentro del shell, liste los directorios:
pxar:/ > ls
Ejemplo de salida:
etc home root var
Seleccione un archivo:
pxar:/ > select /etc/hostname
Restaure los archivos seleccionados:
pxar:/ > restore-selected /root/restored-from-pxar
Salga del shell:
pxar:/ > exit
Use el método pxar para copias de seguridad basadas en archivos. Use el método map para copias de seguridad de imágenes de VM.
Paso 10: Limpie la sesión de restauración CLI
Desmonte el sistema de archivos del invitado:
umount "$RESTORE_MOUNT"
Si activó un grupo de volúmenes LVM, desactívelo después de desmontar:
vgchange -an ubuntu-vg
Elimine los mapeos de particiones si los creó con partx:
partx -d "$LOOP_DEVICE"
Desmapee el dispositivo loop de PBS:
proxmox-backup-client unmap "$LOOP_DEVICE"
Salida esperada: el comando no debería mostrar ninguna salida cuando el dispositivo loop se desmapea correctamente.
Elimine los directorios de montaje temporales si ya no los necesita:
rmdir "$RESTORE_MOUNT"
Elimine las variables de entorno sensibles:
unset PBS_PASSWORD unset PBS_REPOSITORY unset PBS_SNAPSHOT unset PBS_ARCHIVE unset LOOP_DEVICE
Ha limpiado el entorno local de recuperación.
Verificación
Verifique que los archivos restaurados existen:
ls -la "$RESTORE_TARGET"
Ejemplo de salida:
total 12 drwxr-xr-x 3 root root 4096 Jun 4 02:10 . drwx------ 10 root root 4096 Jun 4 02:10 .. -rw-r--r-- 1 root root 12 Jun 4 01:00 hostname
Compare el contenido de los archivos cuando proceda:
cat "$RESTORE_TARGET/hostname"
Ejemplo de salida:
app-vm-01
Confirme que la copia restaurada se encuentra fuera del sistema de archivos montado de la copia de seguridad:
realpath "$RESTORE_TARGET"
Ejemplo de salida:
/root/restored-from-pbs
Compruebe que no quedan mapeos loop de PBS después de la limpieza:
losetup -a | grep pbs-loopdev || true
Salida esperada: si el comando no muestra ninguna salida, no quedan mapeos loop de proxmox-backup.
Reversión de los cambios
Este tutorial no modifica la copia de seguridad original de la VM ni el datastore de PBS. El método de la interfaz web solo descarga archivos a su estación de trabajo. El método CLI crea mapeos loop temporales, puntos de montaje y copias locales de los archivos recuperados.
Esta sección ofrece una alternativa al Paso 10 para salir del procedimiento antes de tiempo. No la ejecute después de completar el Paso 10.
Para revertir el entorno de recuperación CLI, ejecute:
umount "$RESTORE_MOUNT" proxmox-backup-client unmap "$LOOP_DEVICE" rm -rf "$RESTORE_TARGET" rmdir "$RESTORE_MOUNT"
El comando rm -rf "$RESTORE_TARGET" elimina la copia recuperada del host de Proxmox VE. No lo ejecute si aún necesita los archivos restaurados.
Si activó un grupo de volúmenes LVM del invitado, desactívelo:
vgchange -an ubuntu-vg
Si añadió mapeos de particiones manualmente, elimínelos:
partx -d "$LOOP_DEVICE"
Solución de problemas
Falta el botón File Restore
Confirme que ha seleccionado un snapshot de copia de seguridad en un almacenamiento PBS y no en un almacenamiento local de ISO o imágenes. Confirme también que su cuenta tiene privilegios suficientes para explorar el contenido de las copias de seguridad.
El explorador de archivos web no puede leer el sistema de archivos
Es posible que el sistema de archivos del invitado no sea compatible, esté cifrado dentro de la VM, esté dañado o se encuentre dentro de LVM, RAID u otra capa de almacenamiento. Pruebe el método CLI para poder inspeccionar las particiones manualmente con lsblk, blkid, vgscan y herramientas específicas del sistema de archivos.
proxmox-backup-client map falla con errores de autenticación
Compruebe la cadena del repositorio y las credenciales:
echo "$PBS_REPOSITORY" proxmox-backup-client login --repository "$PBS_REPOSITORY"
Formato esperado del repositorio:
<PBS_USER>@<PBS_REALM>@<PBS_SERVER>:<DATASTORE>
Si utiliza un namespace, añada --ns a los comandos proxmox-backup-client correspondientes.
La copia de seguridad está cifrada
Proporcione el archivo de clave al mapear la copia de seguridad:
proxmox-backup-client map "$PBS_SNAPSHOT" "$PBS_ARCHIVE" \ --repository "$PBS_REPOSITORY" \ --keyfile <PATH_TO_ENCRYPTION_KEY>
Ejemplo de salida:
/dev/loop0
No aparecen los dispositivos de partición
Ejecute:
partx -a "$LOOP_DEVICE" lsblk -f "$LOOP_DEVICE"
Si el disco usa LVM, ejecute:
vgscan --mknodes lvs
Si el disco usa RAID por software, ZFS dentro del invitado o cifrado de disco completo, utilice las herramientas de almacenamiento adecuadas del invitado y monte los archivos recuperados en modo de solo lectura siempre que sea posible.
El montaje falla con un tipo de sistema de archivos incorrecto
Compruebe el tipo de sistema de archivos:
blkid
Ejemplo de salida:
/dev/loop0p2: UUID="..." TYPE="ext4"
Después, monte con el tipo correcto si es necesario:
mount -t ext4 -o ro /dev/loop0p2 "$RESTORE_MOUNT"
La copia de archivos conserva un propietario incorrecto
Al copiar archivos como root desde un sistema de archivos de invitado montado, el propietario puede hacer referencia a ID de usuario numéricos del invitado. Esto es normal. Use rsync -a para conservar los metadatos para una inspección posterior, o copie sin conservar el propietario si solo necesita el contenido de los archivos.
Conclusión
Ha restaurado archivos individuales desde una copia de seguridad de VM en Proxmox Backup Server sin desplegar la VM completa. El método de la interfaz web es el camino más rápido para la mayoría de las tareas de restauración de archivos en Proxmox Backup Server, mientras que el método CLI le ofrece un control preciso para la recuperación avanzada de archivos en Proxmox y la inspección de sistemas de archivos. Para las operaciones rutinarias, utilice primero el flujo File Restore de Proxmox VE y recurra a proxmox-backup-client map cuando necesite una recuperación más profunda desde la línea de comandos a partir de un datastore de PBS.
Próximos pasos
Considere documentar su procedimiento interno de recuperación con los nombres exactos de los repositorios de PBS, los namespaces, los ID de VM, la ubicación de almacenamiento de la clave de cifrado y una lista de comprobación para validar la restauración. También puede probar periódicamente la restauración a nivel de archivo como parte de la verificación de copias de seguridad, ya que una copia de seguridad solo es útil si puede recuperar los datos que necesita.
Versión del documento: 1.0
Última actualización: junio de 2026
Responsable: Equipo de documentación técnica
