Wiki

Backup e ripristino

Come QuoteNode gestisce backup di database e file: backup online, restore offline, cifratura e storage remoto.

Backup e ripristino

QuoteNode include un sistema di backup integrato che protegge i dati commerciali da guasti hardware, cancellazioni accidentali e incidenti operativi.

Cosa viene salvato

Ogni backup cattura tre componenti:

Database dump - dump completo PostgreSQL in formato custom con pg_dump --format=custom
File storage - tutti i file caricati e i PDF generati, archiviati come files.tar.gz
Integrity manifest - file checksums.sha256 con hash SHA-256 del dump database e dell’archivio file

Backup online

I backup online vengono eseguiti mentre l’applicazione continua a servire richieste. Non richiedono downtime.

Come funziona

pg_dump crea uno snapshot transazionalmente consistente senza bloccare tabelle o query
il file storage viene archiviato in parallelo
dump e archivio vengono sottoposti a checksum e possono essere cifrati prima dello storage

Limiti

se una transazione e in corso nel momento esatto del dump, i dati non ancora confermati restano fuori
per la maggior parte delle organizzazioni questo comportamento e corretto e sufficiente

Backup offline

Per ottenere la massima garanzia di consistenza, per esempio prima di upgrade importanti:

ferma i container applicativi con docker compose stop backend backup-worker
esegui pg_dump direttamente contro PostgreSQL
archivia i volumi di file storage
riavvia lo stack

Questo approccio elimina le transazioni in volo ma richiede una breve finestra di manutenzione.

Pianificazione

I backup vengono controllati dal container backup-worker, cioe un’istanza dedicata del backend in modalita backup-only:

schedulazione di default: 2:00 AM con 0 0 2 * * *
abilitazione/disabilitazione: BACKUP_ENABLED=true|false
trigger manuale: via pannello admin o API
protezione concorrenza: pattern SKIP LOCKED per garantire un solo backup attivo

Opzioni di storage

Storage locale

Per default i backup vengono scritti in BACKUP_LOCAL_DIR, tipicamente /app/data/backups, montato su volume Docker.

In produzione, i backup locali dovrebbero essere integrati con copie remote. Un backup sullo stesso disco del database non protegge da un guasto del disco stesso.

Storage remoto tramite rclone

Se BACKUP_RCLONE_REMOTE e configurato, il backup viene caricato automaticamente su una destinazione remota dopo la creazione locale. rclone supporta provider come:

S3 e compatibili
Google Cloud Storage
Azure Blob Storage
SFTP
WebDAV

Se l’upload remoto fallisce, la copia locale viene comunque preservata.

Cifratura

I backup possono essere cifrati at rest tramite GPG:

imposta BACKUP_GPG_RECIPIENT con ID o email della chiave
dump database e archivio file vengono cifrati prima dello storage
i file cifrati usano estensione .gpg
il restore richiede la corrispondente chiave privata

Questo e particolarmente importante quando i backup finiscono su infrastruttura cloud di terze parti.

Metadati e audit trail

Ogni backup, riuscito o fallito, viene registrato in backup_logs con:

stato
soggetto che ha avviato il backup
orario inizio e fine
dimensione
destinazione
checksum
eventuale messaggio di errore

Gli ultimi 50 backup possono essere consultati dal pannello amministrativo o via API.

Ripristino

Procedura completa

ferma tutti i container con docker compose down

ripristina il database:

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

estrai il file storage:
```
tar xzf files.tar.gz -C /app/data/
```
riavvia lo stack con docker compose up -d
verifica i checksum

Restore parziale

E possibile ripristinare singole tabelle o subset di dati con pg_restore e i relativi flag, senza restaurare l’intera istanza.

Restore di backup cifrati

Per backup cifrati GPG:

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

Poi si procede con il restore standard.

Timeout del backup

Ogni operazione di backup ha un timeout di 30 minuti. Se viene superato, il job viene terminato e marcato come FAILED.

Download dei backup

Gli amministratori possono scaricare i backup dal pannello:

vai in Settings > Backup
scegli un backup con stato Success
fai clic su Download

Il file scaricato e un .tar.gz contenente dump database, file storage e manifest di integrita.

Retention

I vecchi backup locali vengono puliti automaticamente dopo ogni backup riuscito. La retention e controllata da BACKUP_RETENTION_DAILY, che di default mantiene 7 copie.

I backup remoti non vengono rimossi da QuoteNode: la retention va gestita sul provider di storage.

Disaster recovery

In caso di perdita totale del server:

prepara un nuovo host con Docker
ricrea docker-compose.yml e .env
usa lo stesso DB_ENCRYPTION_KEY dell’installazione originaria
copia il file di backup sul nuovo server
esegui lo script di restore e verifica il risultato

Strategia consigliata

Per la produzione:

abilita backup automatici giornalieri con storage remoto
cifra i backup fuori infrastruttura con GPG
testa periodicamente il restore
conserva almeno una copia offline
monitora i log backup dal pannello
mantieni almeno sette giorni di storico

Download dei backup

Gli amministratori possono scaricare archivi di backup direttamente dal pannello amministrativo, scegliendo un backup riuscito e usando l’azione di download. Il file ottenuto contiene dump database, archivio file e manifest di integrita.

Ritenzione locale e remota

La retention locale viene applicata da QuoteNode dopo ogni backup riuscito. Le copie remote caricate tramite rclone non vengono eliminate automaticamente dall’applicazione: le relative policy devono essere gestite sul provider di storage.