Aggiornare n8n in produzione senza rompere i workflow

Si può aggiornare n8n senza fermare i workflow?

Sì, con un fermo di pochi minuti e senza sorprese, a quattro condizioni: la versione è bloccata a un numero preciso e non a latest; hai letto le release notes e i breaking changes tra la tua versione e quella di arrivo; hai un backup fatto un minuto prima, con dump del database; hai un percorso di rollback scritto. Le migrazioni del database sono automatiche e non tornano indietro, quindi il backup non è un'opzione.

Perché non usare il tag latest in produzione?

n8n pubblica una minor quasi ogni settimana. Con la 2.0 i canali di rilascio sono stati rinominati: stable è la versione consigliata per la produzione, beta la più recente e meno collaudata; latest e next restano come alias, ma la documentazione avverte che spariranno in una major futura e raccomanda di bloccare un numero di versione.

Il problema di latest non è la qualità delle release, è il momento in cui arrivano. Un docker compose up -d lanciato per un altro motivo, un riavvio del server dopo un aggiornamento del kernel, un pull fatto per abitudine: ognuno di questi diventa un aggiornamento di n8n non pianificato, con migrazioni dello schema applicate a un database di cui non hai un dump recente.

Cosa leggere prima: release notes e breaking changes

Le release notes ufficiali elencano per ogni minor le novità e i nodi toccati; le pagine dei breaking changes elencano, per ogni major, cosa smette di funzionare. La 2.0 è l'esempio di quanto una major possa incidere su un'istanza che sembrava tranquilla:

• il nodo Start è stato rimosso, sostituito dal Manual Trigger e dall'Execute Workflow Trigger;
• i task runner sono attivi per default e il nodo Code non accede più alle variabili d'ambiente;
• i nodi Execute Command e Local File Trigger sono disattivati per default (NODES_EXCLUDE);
• la modalità binaria in memoria è sparita, MySQL e MariaDB non sono più supportati come database;
• l'interruttore attivo/inattivo è diventato pubblica/spubblica, e il comando CLI update:workflow è deprecato.

La 3.0, prevista per ottobre 2026, ha già la sua pagina: solo installazioni Docker (niente più npm), rimozione dei nodi Function, Function Item e Item Lists, rimozione della versione 1 dell'AI Agent con le modalità SQL e Conversational, rimozione dell'helper $getPairedItem, rotazione delle chiavi attiva per default, limiti più bassi sul nodo Compression. Chi ha ancora un nodo Function in un workflow del 2024 lo scoprirà a ottobre, oppure oggi, leggendo la pagina.

Per la 2.0 c'è anche uno strumento interno: Settings, voce Migration Report, elenca i workflow incompatibili con la severità di ogni problema. Se sei ancora sulla 1.x, è il primo posto dove guardare.

Come bloccare la versione nell'immagine?

Nel compose.yml l'immagine porta il numero completo, e ogni aggiornamento è una modifica a quella riga, versionata in Git insieme al resto della configurazione:

services:
  n8n:
    image: n8nio/n8n:2.37.7

Per sapere cosa gira davvero non fidarti del file: chiedilo al container.

docker compose exec n8n n8n --version
docker compose images n8n

Se i due output non coincidono con il compose.yml, qualcuno ha aggiornato a mano e il file non è più la fonte di verità: allineali prima di fare qualsiasi altra cosa.

Cosa salvare prima di aggiornare?

Tutto quello descritto nella guida al backup di n8n self-hosted, ma con un vincolo di tempo: il dump del database va fatto subito prima dell'aggiornamento, non la notte precedente, altrimenti il rollback perde le esecuzioni della giornata. La sequenza minima:

cd /opt/n8n
docker compose exec -T postgres \
  pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc > "pre-upgrade-$(date +%F-%H%M).dump"
docker compose exec -u node n8n \
  n8n export:workflow --backup --output=/home/node/.n8n/backup/pre-upgrade/
cp compose.yml "compose.yml.bak.$(date +%F-%H%M)"

La copia del compose.yml è il pezzo del rollback che tutti dimenticano: contiene il numero della versione a cui tornare.

Perché aggiornare a step?

La documentazione ufficiale dice di aggiornare spesso, almeno una volta al mese, per non dover saltare molte versioni in un colpo solo. Ogni minor porta le sue migrazioni e i suoi cambi ai nodi: un salto di dieci minor somma dieci pagine di note e dieci possibili cause di un guasto da isolare.

Dentro la stessa major, saltare qualche minor va bene se hai letto le note di tutte quelle intermedie. Le major non si saltano mai: da 1.x si arriva alla 2.x, si esercita l'istanza per qualche settimana, e solo dopo si affronta la 3.0. Ogni passaggio di major merita anche un test di ripristino fatto prima, non dopo.

Cosa succede al database durante l'aggiornamento?

All'avvio con una versione nuova, n8n confronta la tabella migrations con quelle incluse nel codice e applica le mancanti, una dopo l'altra, prima di accettare richieste. È automatico e non chiede conferma. Non esiste un comando di downgrade: una volta migrato, il database non è più leggibile dalla versione precedente. Per questo il dump va fatto un minuto prima e per questo la sequenza di aggiornamento va seguita guardando i log:

sed -i 's|n8nio/n8n:2.35.2|n8nio/n8n:2.37.7|' compose.yml
docker compose pull n8n
docker compose up -d n8n
docker compose logs -f n8n

Nei log compaiono le migrazioni applicate; l'istanza è pronta quando curl -s https://n8n.example.com/healthz risponde con lo stato ok. Un caso particolare dalla 2.x: se attivi la rotazione delle chiavi di cifratura, i dati vengono scritti in un formato nuovo che le versioni precedenti non leggono; anche qui l'unica via di ritorno è il backup fatto prima.

Come testare su staging?

Lo staging utile è una copia della produzione, non un'istanza vuota con due workflow di prova. Sulla stessa macchina o su una VM temporanea:

1. Stesso compose.yml, stessa N8N_ENCRYPTION_KEY, porta diversa o dominio diverso.
2. Ripristino del dump di produzione con pg_restore nel Postgres dello staging.
3. Prima dell'avvio dell'istanza aggiornata, spubblica tutto: docker compose exec -u node n8n n8n unpublish:workflow --all. Così nessun webhook, nessun cron e nessuna mail partono due volte.
4. Alza la versione, leggi i log delle migrazioni, poi esegui a mano i workflow critici: quelli con credenziali OAuth, quelli con nodi AI, quelli che trattano file, quelli con sub-workflow.

Come tornare indietro se qualcosa si rompe?

Il rollback è due passi, nell'ordine giusto: prima si ferma n8n e si ripristina il database, poi si riparte con l'immagine precedente. Il contrario non funziona, perché la vecchia versione non legge lo schema nuovo.

docker compose stop n8n
docker compose exec -T postgres \
  pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists --no-owner < pre-upgrade-2026-09-02-0705.dump
cp compose.yml.bak.2026-09-02-0705 compose.yml
docker compose up -d n8n
docker compose exec n8n n8n --version

Le esecuzioni tra il dump e il rollback si perdono: scegli la finestra quando i workflow sono fermi o quasi.

Prima, durante e dopo: la tabella

Prima	Durante	Dopo
Leggere release notes e breaking changes tra le due versioni	Cambiare solo il numero di versione nel Compose	Verificare n8n --version e /healthz
Provare su staging con dump ripristinato e workflow spubblicati	docker compose pull n8n e up -d n8n	Aprire una credenziale e usare il test di connessione
Dump del database e export dei workflow un minuto prima	Guardare i log delle migrazioni fino a healthz ok	Eseguire a mano i workflow critici
Copia del compose.yml con la versione attuale	Non toccare Postgres, Caddy o il sistema nello stesso momento	Controllare i log per 24 ore, chiudere la finestra di rollback
Avvisare chi usa l'editor e scegliere un orario a basso traffico	Rollback immediato se una migrazione fallisce	Annotare versione e data nel registro delle modifiche

Perché gli aggiornamenti del sistema operativo e di Docker sono un'altra cosa?

Aggiornare n8n non aggiorna nulla sotto di lui: il kernel, le patch di sicurezza del sistema, Docker Engine, Caddy, Postgres. Ognuno ha il suo ciclo e i suoi rischi. Due esempi concreti: un aggiornamento del kernel richiede un riavvio, e un riavvio con latest nel Compose diventa un aggiornamento di n8n non voluto. Un salto di major di Postgres non si fa cambiando il tag dell'immagine: la documentazione di n8n lo dice chiaramente, il container si ferma con un errore di file incompatibili e serve pg_dumpall più la procedura di upgrade ufficiale.

Tienili separati nel calendario, mai nella stessa finestra, così quando qualcosa si rompe sai cosa hai cambiato.

Un calendario mensile che regge

• Prima settimana del mese: patch di sicurezza del sistema operativo e riavvio se serve, con n8n bloccato alla versione corrente.
• Seconda settimana: lettura delle release notes uscite, scelta della versione di arrivo, prova su staging.
• Terza settimana: aggiornamento di n8n in produzione in una finestra a basso traffico, con dump fatto un minuto prima.
• Ogni tre mesi: test di ripristino del backup su VM pulita e controllo di Docker Engine, Caddy e Postgres.
• Prima di ogni major: Migration Report, lettura della pagina dei breaking changes, staging obbligatorio.

E il server?

Le sezioni qui sopra riguardano n8n. Il sistema operativo, Docker, il firewall, i certificati e Postgres hanno bisogno della stessa disciplina, con un calendario loro e qualcuno che guardi i log dopo ogni riavvio. Se in azienda nessuno può farlo, esistono gli aggiornamenti del server gestiti e l'assistenza sul server Linux come servizio esterno, mentre n8n resta dove preferisci.

Il perimetro è netto: n8n.it segue l'istanza n8n, i workflow e le integrazioni; managedvps.it segue il server sotto. Se vuoi una mano a pianificare il passaggio alla 2.x o a prepararti alla 3.0, contattaci.