Backup y restauracion

QuoteNode incluye un sistema integrado de backup que protege tus datos comerciales frente a fallos de hardware, borrados accidentales e incidencias operativas.

Que se respalda

Cada backup captura tres componentes:

1. Database dump - volcado completo de PostgreSQL en formato custom mediante pg_dump --format=custom, incluyendo tablas, secuencias y constraints.
2. File storage - todos los archivos subidos, como imagenes de producto y logos de empresa, y todos los PDF generados, archivados como files.tar.gz.
3. Integrity manifest - un fichero checksums.sha256 con hashes SHA-256 tanto del dump de base como del archivo de ficheros, para verificar corrupcion o manipulacion.

Backup online (por defecto)

Los backups online se ejecutan mientras la aplicacion sigue atendiendo peticiones. No requieren downtime.

Como funciona:

• pg_dump en formato custom crea un snapshot transaccionalmente consistente de la base sin bloquear tablas ni consultas.
• El almacenamiento de ficheros se archiva en paralelo. Como los archivos subidos y los PDF son inmutables una vez creados, el archivo resultante es consistente.
• Ambas salidas reciben checksum y pueden cifrarse opcionalmente antes del almacenamiento.

Limitaciones:

• Si hay una transaccion en curso exactamente en el momento del dump, sus datos no confirmados quedan fuera. Eso es comportamiento correcto porque el dump representa un punto consistente en el tiempo.
• Para la mayoria de organizaciones, este enfoque es suficiente. El backup online es la opcion recomendada.

Backup offline

Si quieres la maxima garantia de consistencia, por ejemplo antes de upgrades mayores o migraciones:

1. detiene los contenedores de aplicacion con docker compose stop backend backup-worker
2. ejecuta pg_dump directamente contra el contenedor PostgreSQL
3. archiva los volumenes de almacenamiento
4. vuelve a iniciar la aplicacion

Este enfoque garantiza cero transacciones en vuelo, pero requiere una breve ventana de mantenimiento, normalmente entre uno y cinco minutos segun el tamano de la base.

Programacion

Los backups los controla el contenedor backup-worker, que es una instancia dedicada del backend en modo backup-only:

• Horario por defecto: 2:00 AM diaria mediante 0 0 2 * * *, configurable por BACKUP_CRON
• Activacion/desactivacion: BACKUP_ENABLED=true|false
• Disparo manual: los administradores pueden lanzar un backup inmediato desde el panel o via API con POST /api/v1/admin/backup/trigger
• Proteccion frente a concurrencia: el patron SKIP LOCKED garantiza que solo se ejecute un backup a la vez, aunque existan varios workers

Opciones de almacenamiento

Almacenamiento local

Por defecto, los backups se guardan en BACKUP_LOCAL_DIR, normalmente /app/data/backups, montado sobre un volumen Docker. Esto es suficiente para desarrollo y despliegues pequenos.

En produccion, los backups locales deben complementarse con copias remotas. Un backup almacenado en el mismo disco que la base no te protege frente a fallo del propio disco.

Almacenamiento remoto con rclone

Si BACKUP_RCLONE_REMOTE esta configurado, los backups se suben automaticamente a un destino remoto despues de crearse localmente. rclone soporta mas de 70 proveedores, entre ellos:

• S3-compatible - AWS S3, MinIO, DigitalOcean Spaces o Backblaze B2
• Google Cloud Storage
• Azure Blob Storage
• SFTP - cualquier servidor con acceso SSH
• WebDAV - soluciones como Nextcloud u ownCloud

Si la subida remota falla, el backup local se conserva y el error queda registrado.

Cifrado

Los backups pueden cifrarse en reposo mediante GPG:

• define BACKUP_GPG_RECIPIENT con el ID o email de la clave GPG
• el script cifra tanto el dump de base como el archivo de ficheros antes de almacenarlos
• los archivos cifrados usan extension .gpg
• para descifrarlos hace falta la clave privada correspondiente

Esto es especialmente importante si guardas backups en almacenamiento cloud de terceros y no quieres que el proveedor pueda leer su contenido.

Metadatos y rastro de auditoria

Cada backup, exitoso o fallido, queda registrado en la tabla backup_logs:

Campo	Descripcion
Status	PENDING, RUNNING, COMPLETED o FAILED
Initiated by	SCHEDULER o ADMIN
Start time	Momento de inicio del proceso
Completion time	Momento de finalizacion
Size (bytes)	Tamano total del archivo de backup
Destination	Ruta local o URL remota
SHA-256 checksum	Hash de integridad
Error message	Motivo del fallo si aplica

Los 50 backups mas recientes pueden revisarse desde el panel administrativo o la API.

Restauracion

Procedimiento de restauracion completa

1. detiene todos los contenedores con docker compose down
2. restaura la base de datos:

   pg_restore --clean --if-exists -d quotenode backup.dump

3. extrae el almacenamiento de ficheros:

   tar xzf files.tar.gz -C /app/data/

4. arranca de nuevo los contenedores con docker compose up -d
5. verifica que el checksum coincide con el manifest del backup

Restauracion parcial

Tambien se pueden restaurar tablas concretas o subconjuntos de datos desde un dump en formato custom usando flags de pg_restore. Esto es util para recuperar registros borrados accidentalmente sin restaurar toda la instancia.

Restauracion de backups cifrados

Para backups cifrados con GPG:

gpg --decrypt backup.dump.gpg > backup.dump
gpg --decrypt files.tar.gz.gpg > files.tar.gz

Despues de eso, continua con el procedimiento normal de restauracion.

Timeout de backup

Cada operacion de backup tiene un timeout de 30 minutos. Si no termina en ese plazo, se aborta y se registra como FAILED. Para bases muy grandes, el timeout puede ampliarse mediante configuracion.

Descarga de backups

Los administradores pueden descargar backups directamente desde el panel:

1. navega a Settings > Backup
2. busca el backup deseado, con estado Success
3. pulsa Download

El archivo descargado es un .tar.gz que contiene el dump de base, los ficheros y el manifest de integridad. Guardalo de forma segura porque contiene todos tus datos de negocio.

Los backups descargados sirven tanto para disaster recovery en un nuevo servidor como para migrar a otro entorno de hosting.

Nota: los backups almacenados en S3, SFTP u otros remotos no se descargan desde el panel. Debes recuperarlos desde el proveedor correspondiente.

Retencion de backups

Los backups antiguos se limpian automaticamente tras cada backup exitoso. La politica local depende de BACKUP_RETENTION_DAILY, que por defecto conserva las ultimas siete copias exitosas.

Los backups remotos enviados con rclone no se eliminan desde QuoteNode. Configura las lifecycle policies directamente en tu proveedor de almacenamiento.

Disaster recovery - reconstruir desde cero

Tu servidor ha desaparecido. Tienes un archivo de backup, descargado del panel o guardado en almacenamiento remoto, y dispones de un servidor nuevo con Docker instalado. Asi puedes restaurar todo.

Paso 1 - Preparar el nuevo servidor

Crea un directorio de proyecto y prepara los archivos de configuracion tal como se describe en la Installation Guide:

mkdir quotenode && cd quotenode

Necesitas dos archivos:

• docker-compose.yml
• .env, restaurado desde tu copia segura

Critico: usa el mismo DB_ENCRYPTION_KEY que en la instalacion original. Sin esa clave, los datos cifrados como codigos MFA, credenciales SMTP y PII cifrada no podran leerse.

Paso 2 - Copiar el backup al servidor

Transfiere el backup con scp, rsync o herramienta equivalente:

scp quotenode-backup-20260320.tar.gz user@new-server:~/quotenode/

Paso 3 - Descargar el script de restauracion

cp /path/to/your/quotenode-repository/scripts/restore.sh .
chmod +x restore.sh

Si el repositorio vive en otra maquina, copia ese mismo script al servidor:

scp /path/to/your/quotenode-repository/scripts/restore.sh user@new-server:~/quotenode/

Paso 4 - Ejecutar la restauracion

./restore.sh --fresh-install ~/quotenode/quotenode-backup-20260320.tar.gz

El script hara lo siguiente:

1. arrancar el contenedor de base de datos
2. esperar a que este listo
3. restaurar la base desde el dump
4. iniciar la pila completa
5. copiar ficheros subidos y PDF generados
6. ejecutar un health check final

Paso 5 - Verificar

Abre tu dominio en el navegador e inicia sesion con tus credenciales existentes. Clientes, ofertas, productos y configuraciones deberian quedar exactamente como estaban en el momento del backup.

Dry run opcional

Para validar un backup sin modificar nada:

RESTORE_DRY_RUN=true ./restore.sh --fresh-install backup-file.tar.gz

Esto extrae y valida el archivo, verifica checksums y te muestra el plan de restauracion sin tocar la base de datos ni el almacenamiento.

Estrategia recomendada de backup

Para despliegues de produccion:

1. activa backups automaticos diarios con almacenamiento remoto
2. activa cifrado GPG para backups fuera de tu infraestructura
3. prueba periodicamente el procedimiento de restauracion
4. descarga al menos una copia mensual a una ubicacion offline
5. monitoriza los logs de backup en el panel para detectar fallos
6. conserva al menos siete dias de historial de backup