Jetpack si disconnette ogni 3-4 giorni: la soluzione

Il problema

Tutto inizia con il controllo dell’andamento delle vendite del sito, una mattina. L’app ufficiale di gestione di WooCommerce non riesce a connettersi allo shop! Aprendo la dashboard, si scopre che è saltato il sistema dei pagamenti WooPayments e guardando meglio anche il plugin Jetpack, da cui dipende tutta la catena, disconnesso! Cos’è successo? Non è chiaro. Riavviamo la connessione Jetpack a mano e tutto ritorna a funzionare. Risolto? No! Giorni dopo, in modo del tutto casuale, succede di nuovo! Sempre di notte! L’analisi dei log non fornisce indicazioni rilevanti. Che fare?

Intanto, abbiamo realizzato un utile plugin per monitorare la situazione della connessione Jetpack (e WooPayments), per loggare il problema e tenere traccia delle disconnessioni.

Scopriamo che le mail di alert arrivano tutte sempre alla stessa ora: 4:13 di notte!

Il pattern era preciso e misterioso allo stesso tempo: la disconnessione non avveniva ogni notte, ma ogni 3-4 giorni, sempre nella stessa finestra oraria. Il sito al mattino tornava operativo dopo una riconnessione manuale — una perdita di tempo e, soprattutto, un rischio concreto per le transazioni di pagamento nelle ore notturne.

Prima di arrivare alla causa, abbiamo percorso una strada lunga e ricca di falsi colpevoli. Vale la pena raccontarla, perché rispecchia fedelmente come funziona il debugging su sistemi complessi.

Come funziona la connessione Jetpack (in breve)

Per capire il problema, serve un minimo di contesto su come Jetpack gestisce la connessione con WordPress.com.

Quando si connette Jetpack a un sito, vengono generati e salvati nel database due token OAuth distinti:

• Blog token (o site token): identifica il sito WordPress come entità. È legato all’URL del sito.
• User token: identifica l’utente amministratore che ha autorizzato la connessione.

Entrambi i token vengono registrati su WordPress.com insieme all’URL del sito (siteurl) al momento della connessione. Ogni chiamata successiva tra il sito e WordPress.com viene firmata con questi token.

Il punto critico è questo: se l’URL del sito cambia — anche solo aggiungendo o rimuovendo www. — Jetpack rileva quello che chiama un Identity Crisis. Il sito risponde con un URL diverso da quello registrato, la firma non corrisponde, e la connessione viene invalidata. Da quel momento, WooPayments smette di funzionare, la sincronizzazione si interrompe, e qualsiasi servizio che si appoggi a Jetpack va in errore.

L’infrastruttura

Il setup del sito è rilevante per capire la vulnerabilità:

• HAProxy gestisce la terminazione TLS e il load balancing in ingresso
• Apache + mod_php serve WordPress
• All-in-One WP Migration Unlimited esegue un backup notturno automatico del database
• Il cron di WordPress è gestito via system cron (WP-CLI), non via wp-cron HTTP nativo

HAProxy ospita più siti sullo stesso server, quindi il routing avviene tramite l’header HTTP Host. La chiave del problema sta qui: in certi scenari edge, l’header Host passato da HAProxy al backend Apache poteva contenere www.nome-e-commerce.it invece di nome-e-commerce.it.

I falsi colpevoli: una cronaca del debugging

Tentativo 1 — PHP session timeout

Il primo sospettato è stato il cleanup delle sessioni PHP. Il sistema aveva session.gc_maxlifetime = 1440 (24 minuti), e il cleanup girava ogni 30 minuti alle :09 e :39. L’ipotesi: il token OAuth di Jetpack veniva salvato in sessione e poi cancellato.

Verdetto: innocente. Jetpack non usa sessioni PHP per i token — li salva nelle wp_options. Abbiamo comunque esteso il timeout a 86400 secondi, ma le disconnessioni sono continuate.

Tentativo 2 — e2scrub_all (filesystem check)

Nei log di sistema compariva e2scrub_all nella finestra notturna. L’ipotesi: il check del filesystem bloccava I/O e causava timeout nella connessione.

Verdetto: innocente. Su VM con dischi virtuali, e2scrub si avvia e si chiude immediatamente senza fare nulla. Falsa pista.

Tentativo 3 — All-in-One WP Migration (prima lettura)

Il backup notturno di AI1WM era schedulato alle 02:00 UTC, esattamente 13 minuti prima del nostro alert delle 04:13 (ora italiana). L’ipotesi: durante l’export del database il plugin causava una race condition sui cron job di Jetpack.

Questa lettura era parzialmente corretta: il plugin era coinvolto, ma non per il motivo che pensavamo. Abbiamo sviluppato un sistema di auto-recovery dei cron job mancanti, che però non risolveva il vero problema — la disconnessione della connessione sito, non solo i cron.

Verdetto: coinvolto, ma non per la causa che pensavamo.

La svolta: il cambio di URL

Analizzando i log del plugin con più attenzione, abbiamo notato che nelle notti della disconnessione compariva prima la perdita della connessione sito (Jetpack site is not connected) e solo dopo la scomparsa dei cron job. L’ordine degli eventi era invertito rispetto all’ipotesi dei cron: non erano i cron a causare la disconnessione, era la disconnessione a far sparire i cron.

Cercando tra i plugin chi poteva modificare siteurl e home nel database, abbiamo trovato il colpevole definitivo.

Il vero colpevole: wp_guess_url()

Nel codice di All-in-One WP Migration Unlimited, durante il processo di reset/export del database, troviamo questo:

php

$guess_url = ( wp_guess_url() !== 'http:' ) ? wp_guess_url() : $backup['blog']['site_url'];
update_option( 'siteurl', $guess_url );
update_option( 'home', $guess_url );

wp_guess_url() è una funzione di WordPress che tenta di ricostruire l’URL del sito dal contesto della richiesta corrente — leggendo $_SERVER['HTTP_HOST'], il percorso dello script, e altri parametri.

Il problema: durante l’esecuzione del cron notturno via WP-CLI, il contesto HTTP non è quello di una normale richiesta browser. L’header Host che arriva dipende da come il sistema cron invoca WP-CLI. Se in quel momento HAProxy aveva passato una richiesta con www.nome-e-commerce.it nell’header Host, wp_guess_url() restituiva https://www.nome-e-commerce.it — e AI1WM lo scriveva direttamente nel database come nuovo siteurl e home.

Jetpack, al check successivo, trovava l’URL del sito cambiato rispetto a quello registrato su WordPress.com: identity crisis, connessione invalidata.

Il motivo per cui non accadeva ogni notte ma ogni 3-4 giorni è ora chiaro: dipendeva da quale richiesta HAProxy stava gestendo in quel preciso momento, e se quella richiesta aveva l’header Host con o senza www. Un evento intermittente e difficile da riprodurre, che rendeva il debugging estremamente frustrante.

La soluzione definitiva

La correzione è elegante nella sua semplicità. WordPress prevede esattamente questo scenario: se WP_HOME e WP_SITEURL sono definite come costanti PHP in wp-config.php, qualsiasi chiamata a update_option('siteurl', ...) o update_option('home', ...) viene completamente ignorata. Le costanti hanno priorità assoluta sulle option del database.

php

// wp-config.php

// Forza l'hostname corretto in tutti i contesti (incluso WP-CLI)
$_SERVER['HTTP_HOST'] = $_SERVER['SERVER_NAME'] = 'nome-e-commerce.it';
// Rilevamento HTTPS dietro HAProxy
if ( isset( $_SERVER['HTTP_X_FORWARDED_PROTO'] ) &&
     $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https' ) {
    $_SERVER['HTTPS'] = 'on';
}

// WP-CLI ha bisogno del contesto HTTPS
if ( defined( 'WP_CLI' ) && WP_CLI ) {
    $_SERVER['HTTP_X_FORWARDED_PROTO'] = 'https';
    $_SERVER['HTTPS']                  = 'on';
}

// Blindatura URL — immune a qualsiasi update_option
define( 'WP_HOME',    'https://nome-e-commerce.it' );define( 'WP_SITEURL', 'https://nome-e-commerce.it' );

Questa configurazione agisce su due livelli:

1. $_SERVER['HTTP_HOST'] hardcoded: impedisce a wp_guess_url() di generare un URL sbagliato già alla radice
2. WP_HOME e WP_SITEURL come costanti: anche se wp_guess_url() restituisse comunque www.nome-e-commerce.it, l’update_option successivo non avrebbe alcun effetto sul database né sul comportamento di WordPress

Da quando abbiamo applicato questa modifica: zero disconnessioni.

Il plugin che abbiamo sviluppato: StSft Jetpack Connection Monitor

Durante questa lunga indagine abbiamo sviluppato e progressivamente evoluto un plugin WordPress che ha reso possibile l’intera diagnosi: StSft Jetpack Connection Monitor.

Cosa fa

Il plugin monitora in modo continuo lo stato di Jetpack e dei sistemi di pagamento collegati, e agisce attivamente in caso di problemi:

• Monitoraggio connessione Jetpack — controlla sia la connessione sito che la connessione utente, i due livelli che Jetpack richiede per funzionare correttamente con WooPayments
• Monitoraggio gateway di pagamento — WooPayments, PayPal, e qualsiasi altro gateway WooCommerce configurabile
• Controllo preventivo dei cron job — verifica che jetpack_sync_cron e jetpack_sync_full_cron siano presenti e schedulati
• Auto-recovery — quando i cron job spariscono, il plugin tenta di ricrearli automaticamente usando lo schedule nativo di Jetpack; se necessario, ricorre a WP-CLI
• Alert email — notifica immediata in caso di nuovo problema, con email di recovery quando tutto torna online
• Heatmap giorno × ora — dashboard visiva che mostra i pattern di disconnessione su 7, 14 o 30 giorni, rendendo immediatamente evidenti le ricorrenze sistematiche

Perché è utile

Su siti WooCommerce con WooPayments, una disconnessione di Jetpack significa pagamenti non funzionanti. Senza un sistema di monitoring attivo, il problema viene scoperto la mattina — dopo ore in cui i clienti non hanno potuto completare gli acquisti. Il plugin riduce il tempo di rilevamento a pochi minuti e, per i problemi risolvibili automaticamente, a zero intervento manuale.

La heatmap in particolare si è rivelata lo strumento chiave per questa diagnosi: visualizzando i pattern su settimane, il cluster di eventi alle 04:00 di notte in giorni non consecutivi era immediatamente leggibile, guidando l’indagine nella direzione giusta.

Come scaricarlo

Il plugin è disponibile gratuitamente. Per informazioni e download: info@stylesoft.it oppure visita la pagina del plugin.

Lezioni imparate

1. L’ordine degli eventi nei log è tutto. La svolta è arrivata quando abbiamo smesso di cercare la causa dei cron mancanti e abbiamo guardato cosa succedeva prima di loro. In un sistema complesso, distinguere causa ed effetto nei log richiede attenzione all’ordine temporale preciso degli eventi.

2. I problemi intermittenti sono i più difficili. Un bug che si manifesta ogni 3-4 giorni, dipendente da un’interazione tra sistema cron, HAProxy e un plugin di backup, non è riproducibile a piacimento. L’unico modo per diagnosticarlo è raccogliere dati pazientemente nel tempo — da cui l’utilità di avere un sistema di logging dedicato.

3. Le costanti di WordPress battono sempre le option. WP_HOME e WP_SITEURL come costanti in wp-config.php sono la difesa corretta contro qualsiasi tentativo — intenzionale o accidentale — di modificare l’URL del sito. Se il tuo sito vive dietro un reverse proxy, è buona pratica definirle sempre esplicitamente.

4. I plugin di backup toccano il database in modo profondo. All-in-One WP Migration è un prodotto eccellente, ma come ogni plugin di backup/migration opera a un livello molto basso del database. Vale la pena esaminare cosa scrive durante un export, specialmente su siti con configurazioni di rete non standard.

Come abbiamo risolto — la versione pratica

Questa sezione è per chi vuole applicare la soluzione senza necessariamente seguire tutto il ragionamento tecnico.

Se hai Jetpack che si disconnette periodicamente, specialmente su siti con HAProxy o altri reverse proxy, prova questa modifica a wp-config.php:

Aggiungi queste righe prima del commento /* That's all, stop editing! */, sostituendo tuosito.it con il tuo dominio reale:

php

define( 'WP_HOME',    'https://tuosito.it' );
define( 'WP_SITEURL', 'https://tuosito.it' );

Queste due righe impediscono a qualsiasi plugin — inclusi plugin di backup e migration — di modificare l’URL del sito nel database. Jetpack non vedrà mai un URL diverso da quello registrato, e le disconnessioni da Identity Crisis non potranno più verificarsi.

Se hai anche un reverse proxy (HAProxy, Nginx, Cloudflare) e usi WP-CLI, aggiungi anche questo prima delle costanti:

php

$_SERVER['HTTP_HOST'] = $_SERVER['SERVER_NAME'] = 'tuosito.it';

if ( isset( $_SERVER['HTTP_X_FORWARDED_PROTO'] ) &&
     $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https' ) {
    $_SERVER['HTTPS'] = 'on';
}

Questo è tutto. Nessun plugin aggiuntivo, nessuna modifica complessa — due righe di configurazione che chiudono definitivamente il problema.

Hai riscontrato un problema simile o stai valutando il plugin StSft Jetpack Connection Monitor per il tuo sito? Scrivici a info@stylesoft.it — siamo sempre disponibili per una consulenza.