Backup & Ripristino

Il modulo Backup & Ripristino consente di proteggere i dati aziendali creando copie di sicurezza del database e di ripristinarli in caso di necessità.

Ogni workspace ha il proprio archivio backup separato. Il sistema supporta sia backup manuali (su richiesta) che automatici (programmati).

Funzionalità principali

• Backup manuale: genera un dump SQL compresso del database del workspace corrente
• Ripristino: riporta il database a un punto nel tempo selezionando un backup dall'archivio
• Importazione: carica un file di backup esterno (da altro workspace o altro sistema)
• Download: scarica un backup sul proprio computer per conservazione esterna
• Rinomina: assegna nomi descrittivi ai backup per facilitarne l'identificazione
• Backup automatico: ogni notte per tutte le aziende del server; frequenza e giorni di conservazione li imposta solo il SUPERADMIN, perché valgono per tutti
• Notifiche email: dopo il giro notturno, un’email all’indirizzo della configurazione se qualche archivio non è stato salvato (e, se lo si chiede, anche quando va tutto bene). Parte dalla casella di sistema del programma; l’indirizzo lo imposta e lo vede solo il SUPERADMIN
• Multi-azienda: ogni azienda ha backup indipendenti; l'archivio mostra l'azienda in cui si è
• Scelta dell'azienda (solo SUPERADMIN): la tendina Azienda in cima alla pagina fa backup, ripristino, importazione e download di qualunque azienda senza entrarci.

La schermata è divisa in tre aree principali:

1. Barra strumenti (in alto)

• Importa Backup (pulsante arancione, solo per il Super Amministratore): apre il selettore file per caricare un backup esterno
• Backup Manuale (pulsante blu): avvia la creazione di un nuovo backup
• Durante l'esecuzione, i pulsanti si disabilitano e mostrano “in corso...”

2. Configurazione Backup Automatico (solo Super Amministratore)

Card con i parametri di programmazione: frequenza, orario, conservazione, notifiche. Valgono per tutte le aziende del server. Pulsante Salva che si attiva solo quando ci sono modifiche non salvate. Sotto c'è la card del backup automatico locale all'avvio (sez. 14).

3. Archivio Backup

Tabella con l'elenco di tutti i backup del workspace corrente. Il titolo mostra: “Archivio Backup — {nome workspace} (N)”.

1. Verificare di essere nel workspace corretto: il nome è visibile nel titolo dell'archivio e nella topbar.
2. Premere il pulsante “Backup Manuale” (blu) nella barra strumenti.
3. Il pulsante si disabilita e mostra “Backup in corso...” con un'icona di caricamento.
4. Il sistema genera un dump SQL completo del database corrente (con pg_dump --no-owner --no-privileges --clean --if-exists).
5. Il file viene compresso in formato .sql.gz e salvato nell'archivio del server.
6. Al completamento, appare il messaggio “Backup completato con successo” in verde.
7. Il nuovo backup appare in cima alla lista con stato COMPLETATO e tipo MANUALE.

Per salvare una copia del backup sul proprio computer:

1. Nella lista archivio, individuare il backup desiderato (stato COMPLETATO).
2. Premere l'icona Scarica (freccia verso il basso) nella colonna Azioni.
3. Il browser avvia il download del file con il nome originale (es. backup_20260413_020000.sql.gz).
4. Conservare il file scaricato in un luogo sicuro (disco esterno, cloud, NAS).

Il ripristino riporta il database del workspace corrente allo stato in cui era al momento del backup selezionato.

1. Nella lista archivio, individuare il backup da ripristinare.
2. Premere l'icona Ripristina (icona orologio/freccia) nella colonna Azioni.
3. Si apre una modale di conferma che mostra:
   • Nome del file backup in font monospace
   • Nome del workspace di destinazione evidenziato in rosso e in grande
   • Avviso: “Il database attuale verrà completamente sovrascritto”
4. Premere “Conferma Ripristino” per procedere, oppure “Annulla” per tornare indietro.
5. Il sistema esegue: DROP SCHEMA CASCADE → ripristino dal file → ricostruzione indici.
6. Al completamento, appare il messaggio: “Ripristino completato. Ricaricare la pagina.”
7. Ricaricare la pagina (F5) per vedere i dati ripristinati.

L'importazione consente di caricare un file di backup proveniente da un altro workspace, un altro server o un altro sistema gestionale.

1. Premere il pulsante “Importa Backup” (arancione) nella barra strumenti.
2. Si apre il selettore file del sistema operativo. Selezionare un file nei formati supportati: .sql, .gz, .sql.gz, .dump.
3. Si apre una modale di conferma che mostra:
   • Nome del file selezionato in font monospace
   • Nome del workspace di destinazione evidenziato in rosso
   • Avviso: “Il database attuale verrà completamente sovrascritto”
4. Premere “Conferma Importazione” per caricare il file.
5. Il pulsante mostra “Importazione...” durante il caricamento e l'elaborazione.
6. Il sistema carica il file, cancella lo schema corrente e ripristina dal file importato.
7. Al completamento: “Backup importato e ripristinato con successo. Ricaricare la pagina.”
8. Ricaricare la pagina (F5) per vedere i dati importati.

Casi d'uso dell'importazione

• Migrazione tra workspace: scaricare un backup dal workspace sorgente, importarlo nel workspace di destinazione
• Migrazione da altro server: portare un database da un'installazione NOX a un'altra
• Ripristino da copia locale: reimportare un backup precedentemente scaricato sul proprio PC
• Test: importare dati di produzione in un workspace di test (nascosto) per verifiche

I backup generati automaticamente hanno nomi tecnici (es. backup_20260413_020000.sql.gz). È possibile rinominarli con nomi descrittivi per facilitarne l'identificazione.

1. Nella lista archivio, fare doppio clic sul nome del file, oppure premere l'icona matita (visibile al passaggio del mouse).
2. Il nome diventa un campo di input modificabile in font monospace.
3. Digitare il nuovo nome descrittivo (es. Pre-aggiornamento_v2.1, Chiusura_trimestre_Q1).
4. Premere il segno di spunta verde per confermare, oppure la X rossa per annullare.
5. In alternativa: Enter per confermare, Esc per annullare.

1. Nella lista archivio, premere l'icona Elimina (cestino) sulla riga del backup.
2. Appare una finestra di conferma con il nome del file.
3. Premere “OK” per eliminare definitivamente, oppure “Annulla”.
4. Il backup viene rimosso dall'archivio e dal server.

La card “Configurazione Backup Automatico” permette di programmare i backup senza intervento manuale. La vede e la salva solo il Super Amministratore: la configurazione è una sola per tutto il server, e il giro notturno salva tutte le aziende.

Parametri configurabili

Come configurare

1. Attivare la checkbox “Backup automatico abilitato”.
2. Selezionare la frequenza desiderata.
3. Impostare l'ora di esecuzione (consigliato: tra le 01:00 e le 05:00 quando il sistema è meno utilizzato).
4. Se frequenza settimanale: scegliere il giorno della settimana.
5. Se frequenza mensile: scegliere il giorno del mese (1–28).
6. Impostare i giorni di retention (quanti giorni conservare i backup prima dell'eliminazione automatica).
7. Inserire l'email per le notifiche e scegliere quali notifiche ricevere.
8. Premere “Salva Configurazione” (il pulsante si attiva solo quando ci sono modifiche).

NOX supporta ambienti multipli (workspace), ciascuno con il proprio database indipendente. Il modulo Backup rispetta questa separazione:

• L'archivio mostra solo i backup del workspace attualmente selezionato
• Il backup manuale genera un dump del database del workspace corrente
• Il ripristino e l'importazione operano sul database del workspace corrente
• La configurazione automatica è una sola per tutto il server: il giro notturno salva ogni azienda, ciascuna nel suo file
• Il nome del workspace è sempre visibile nel titolo dell'archivio e nelle modali di conferma

Migrare dati tra workspace

Operazione del Super Amministratore: scaricare e importare una copia sono riservati a lui.

1. Selezionare il workspace sorgente dalla topbar.
2. Eseguire un Backup Manuale o individuare un backup esistente.
3. Premere Scarica per salvare il file sul PC.
4. Selezionare il workspace di destinazione dalla topbar.
5. Premere Importa Backup e caricare il file scaricato.
6. Confermare nella modale (verificare che il nome workspace sia quello corretto).

Formati accettati per l'importazione

Formato generato dal sistema

I backup creati da NOX (manuali e automatici) sono in formato .sql.gz generati con:

• pg_dump con flag --no-owner --no-privileges --clean --if-exists
• Compressione Gzip per ridurre lo spazio occupato
• Contiene l'intero schema del database (tabelle, dati, indici, vincoli)

Strategia 3-2-1

La strategia di backup raccomandata è la regola 3-2-1:

• 3 copie dei dati (originale + 2 backup)
• 2 supporti diversi (server + disco esterno o cloud)
• 1 copia off-site (fuori dalla sede, per protezione da incendi, furti, calamità)

Prima di operazioni critiche

Eseguire sempre un backup manuale prima di:

• Aggiornamenti del software (frontend o backend)
• Migrazioni di database (Prisma push/migrate)
• Importazioni massive (Import/Export)
• Operazioni di pulizia dati (cancellazione soggetti, documenti)
• Cambio workspace o riassegnazione utenti

Verifica periodica dei backup

• Scaricare periodicamente un backup e verificare che il file non sia corrotto (aprire con un editor di testo o provare a importare in un workspace di test)
• Controllare che i backup automatici vengano effettivamente generati (verificare date e dimensioni nell'archivio)
• Attivare le notifiche email per errori

Retention consigliata

Il modulo Backup è stato esteso con uno scheduler automatico server-side e supporto multi-workspace nativo.

Scheduler automatico (node-cron)

Il backup automatico è ora gestito da un job node-cron lato server che gira 24/7. L'orario è configurabile dalla UI (campo Orario esecuzione, default 02:00). La pianificazione sopravvive ai riavvii del server.

Multi-workspace automatico

Ad ogni esecuzione il sistema esegue pg_dump:

• sul database principale (utenti, workspace, log)
• su ogni workspace attivo (pazienti, documenti, catalogo, ecc.)

I file sono salvati in directory dedicate per workspace, con il timestamp nel nome.

Retention automatica

A fine giro notturno, dopo il dump, il sistema elimina le copie vecchie:

Se il valore della conservazione salvato non è valido, notturne e manuali non si cancellano. Una copia da tenere più a lungo va scaricata e conservata fuori dal server.

Frequenze supportate

Il backup automatico locale all'avvio salva una copia del database della propria azienda direttamente in una cartella del computer, oltre che sul server.

Come funziona

1. Vai in Backup & Ripristino, card «Backup automatico locale all'avvio»
2. Attiva la casella «Attiva backup automatico locale all'avvio»
3. Scegli la cartella — il browser apre il suo selettore di cartelle
4. Seleziona la cartella di destinazione (es. ~/Documents/NOX-Backup/ o un disco esterno NAS sincronizzato)
5. Concedi i permessi di scrittura quando richiesto dal browser
6. NOX memorizza il handle della cartella in IndexedDB per riutilizzarlo nei backup successivi senza richiedere di nuovo i permessi

Comportamento

• Il backup parte all'avvio del programma, al massimo una volta ogni 24 ore: NOX genera la copia sul server e la scarica nella cartella scelta. Sul server ne restano le ultime 5
• I file hanno nel nome data e ora, così non si sovrascrivono
• Se la cartella locale non è più raggiungibile (disco esterno scollegato, permessi revocati), la card mostra l'errore
• La scelta della cartella funziona con Chrome ed Edge sul computer. Con Firefox, Safari o dal telefono la card lo dice e il file finisce nella cartella Download del browser

Vantaggi

• Disponibilità offline: anche se il server NOX è irraggiungibile, hai una copia recente in locale
• Backup ridondante: in caso di perdita totale del server (ransomware, disastro fisico), il PC dell'utente conserva i dump
• Sincronizzazione cloud: scegliendo una cartella sincronizzata con Dropbox/OneDrive/Google Drive, ottieni automaticamente backup off-site
• Velocità di restore: il ripristino da file locale è più veloce del download dal server (se la connessione è lenta)

Ogni backup (manuale, locale o notturno) è registrato nella tabella log_backup_esecuzioni, anche quando non riesce. Ognuno vede solo le righe della propria azienda; il SUPERADMIN le vede tutte (o quelle dell’azienda scelta in alto).

Dati registrati

Endpoint: GET /api/backup/log/esecuzioni con filtri per stato e limit.

L'hash SHA-256 registrato alla creazione permette di verificare in qualsiasi momento se il file è stato alterato o corrotto (bitrot).

Come funziona

1. Endpoint: GET /api/backup/log/verifica/:id (serve il permesso di eseguire i backup, e solo sulle copie della propria azienda)
2. Il sistema legge il file dal path registrato
3. Calcola SHA-256 in streaming (compatibile con file grandi)
4. Confronta con l'hash storico
5. Ritorna: OK, HASH_MISMATCH, FILE_MANCANTE (cancellato dalla pulizia o a mano) o SENZA_IMPRONTA (righe vecchie registrate senza SHA-256)

Il campo tipo del log permette di distinguere chiaramente backup on-demand e backup automatici.

• MANUALE e AUTO_LOCAL: eseguito_da = utente (username / id)
• AUTO (notturno): eseguito_da = "notturno", una riga per ogni archivio

Lo scheduler interno avvia il backup all’ora impostata nella configurazione, in ora italiana (oggi le 02:15). Anche l’ora nel nome dei file è italiana.

Strategia di conservazione a più livelli per bilanciare costo e compliance.

Procedura di ripristino del database da backup esistente.

1. Identificare il backup da ripristinare (lista + filtro data)
2. Eseguire POST /api/backup/:id/ripristina con conferma esplicita
3. Il sistema scarica il file, esegue psql di ripristino
4. Ricaricare il PrismaClient per ogni workspace coinvolto