Risolvere gli errori di migrazione del database Kopano dopo un aggiornamento della versione di MySQL

Un errore di migrazione del database di Kopano subito dopo un aggiornamento di versione di MySQL o MariaDB di solito significa che l'applicazione e il database non sono più coerenti su qualcosa che prima era implicito: stato dello schema, impostazioni predefinite del server, comportamento SQL, autenticazione o il percorso di aggiornamento stesso. L'obiettivo utile non è semplicemente quello di far kopano-serverpartire il sistema una volta per tutte. L'obiettivo è raggiungere uno stato in cui lo schema sia coerente, Kopano si avvii senza errori di aggiornamento del database, gli utenti possano aprire i negozi e il flusso di posta elettronica sopravviva a un riavvio.

Questa guida si concentra sulle prove. Ogni fase include un segnale di successo e un punto in cui è opportuno smettere di provare la stessa soluzione e cambiare direzione. La documentazione pubblica per gli amministratori di Kopano è precedente alle versioni attuali di MySQL e MariaDB, quindi non dare per scontato che ogni versione moderna del database sia supportata da ogni versione precedente di Kopano. Utilizza la versione esatta del pacchetto Kopano, il fornitore del database e l'errore del server come prova decisiva.

Inizia con il risultato di cui hai bisogno

Prima di modificare la configurazione, definisci cosa intendi per "fisso". Un ripristino corretto presenta normalmente tutti questi segnali:

• kopano-serverSi avvia e rimane in esecuzione dopo il riavvio del servizio.
• Il registro di Kopano non segnala più aggiornamenti dello schema del database o errori di esecuzione SQL.
• Il database è leggibile e scrivibile dall'account Kopano configurato.
• Vengono visualizzati i negozi e gli utenti esistenti, anziché uno schema vuoto creato ex novo.
• L'invio e la consegna della posta riprendono regolarmente.
• Un secondo riavvio produce lo stesso risultato positivo.

Se riesci a raggiungere solo il primo obiettivo, continua a testare. Un avvio temporaneo dopo aver apportato una modifica sql_mode, ad esempio, non dimostra che lo schema sottostante sia corretto.

1. Interrompere i processi di scrittura di Kopano ed eseguire un backup del database ripristinabile.

La documentazione di aggiornamento di Kopano raccomanda di eseguire il backup del database e dei file di configurazione e di arrestare i servizi che utilizzano il database prima di procedere con l'aggiornamento. La documentazione specifica in particolare l'arresto di kopano-spoolere kopano-server, oltre ai componenti opzionali in esecuzione. Consultare la documentazione di aggiornamento di Kopano Core .

sudo systemctl stop kopano-spooler
sudo systemctl stop kopano-server

mysqldump -u root -p --single-transaction kopano > /root/kopano-before-fix.sql
ls -lh /root/kopano-before-fix.sql

Per installazioni di grandi dimensioni, è inoltre necessario conservare i dati /etc/kopano/, annotare la posizione di archiviazione degli allegati e seguire la politica di backup del database in uso. Se gli allegati sono archiviati al di fuori di MySQL, un semplice dump SQL non costituisce un backup completo di Kopano.

Interrompere i servizi di Kopano che scrivono sul database e verificare la presenza di un dump aggiornato prima di modificare lo schema o le impostazioni del server.

Segnale di successo: disponi di un backup che può essere ripristinato su un'istanza di database separata e sai dove sono archiviati gli allegati esterni. Cambia approccio se: il dump stesso fallisce. Risolvi eventuali problemi di danneggiamento del database, autorizzazioni, spazio su disco o connettività prima di tentare una migrazione dello schema Kopano.

2. Registrare la versione esatta del database e le impostazioni predefinite modificate.

Un importante aggiornamento di MySQL può modificare le impostazioni predefinite del server senza modificare le tabelle esistenti. MySQL 8.0, ad esempio, ha modificato il set di caratteri predefinito del server in utf8mb4e la collazione predefinita in utf8mb4_0900_ai_ci. Ha inoltre modificato altre impostazioni predefinite e rimosso o deprecato comportamenti precedenti. Oracle documenta queste differenze in Changes in MySQL 8.0 .

Acquisisci lo stato effettivo del server anziché presumere cosa abbia fatto l'aggiornamento del pacchetto:

mysql -u root -p

SELECT VERSION();
SHOW VARIABLES LIKE 'sql_mode';
SHOW VARIABLES LIKE 'character_set_server';
SHOW VARIABLES LIKE 'collation_server';

Annota la versione del database e le impostazioni predefinite che Kopano rileva attualmente; questi valori aiutano a spiegare gli errori che si sono verificati solo dopo l'aggiornamento del database.

Non disabilitare immediatamente le modalità SQL rigorose. Un errore in modalità rigorosa può rivelare dati legacy non validi o istruzioni SQL che devono essere corrette. Disattivare la modalità rigorosa potrebbe nascondere il sintomo, lasciando però dei dati che causeranno errori in seguito. Per prima cosa, recupera l'istruzione o l'errore del database esatto dal log di Kopano.

3. Leggi il primo errore SQL, non solo l'errore finale del servizio.

Systemd spesso mostra solo che kopano-serverè uscito. La riga utile si trova solitamente prima nel journal o nel log di Kopano. Inizia con:

journalctl -u kopano-server -n 100 --no-pager

Successivamente, classificate il guasto. La tabella seguente è una mappa di triage pratica, non un'affermazione secondo cui un'unica causa si applica a ogni installazione.

Il registro delle modifiche di Kopano conferma che alcune release hanno introdotto modifiche allo schema che richiedevano kopano-dbadmoperazioni specifiche. Registra inoltre i difetti storici degli aggiornamenti del database, inclusi gli errori relativi a vecchie definizioni di tabelle MySQL e aggiornamenti utf8mb4. Utilizza il registro delle modifiche di Kopano Core per individuare l'intervento di manutenzione più adatto alla tua versione specifica di Kopano.

4. Confronta lo schema Kopano esistente con le impostazioni predefinite del nuovo server

Verifica lo schema così come esiste; le impostazioni predefinite del server da sole non ti dicono quanto sono vecchie le tabelle di Kopano.

SHOW CREATE DATABASE kopano;
SHOW TABLE STATUS FROM kopano;

Esamina la definizione del database Kopano esistente e i motori di archiviazione, mantenendo visibile l'errore di migrazione originale per confronto.

Se il database è stato originariamente creato con una versione precedente di MySQL, le sue tabelle potrebbero conservare set di caratteri obsoleti anche se i nuovi oggetti creati ora utilizzano utf8mb4 come set di caratteri predefinito. MySQL specifica esplicitamente che l'aggiornamento dalla versione 5.7 alla 8.0 non converte automaticamente gli oggetti del database esistenti al nuovo set di caratteri predefinito. Questa distinzione è importante: una migrazione può fallire se viene creata una nuova colonna o un nuovo indice con set di caratteri predefiniti diversi da quelli degli oggetti adiacenti.

Kopano stesso ha aggiunto il supporto per utf8mb4 nelle versioni successive di Core e ha documentato una specifica procedura di manutenzione del database kopano-dbadm usmpper l'aggiornamento dei database esistenti al supporto Unicode a 4 byte. Non eseguire quel comando solo perché MySQL ora utilizza utf8mb4 come predefinito; eseguilo solo quando la documentazione della versione di Kopano installata o l'output del server lo richiedono.

5. Se MariaDB è stato aggiornato, completare prima l'aggiornamento lato MariaDB.

Se il tuo backend è MariaDB anziché Oracle MySQL, completa la procedura di aggiornamento del server di database prima di dare la colpa a Kopano. La documentazione di MariaDB descrive Kopano mariadb-upgradecome lo strumento che aggiorna le tabelle di sistema e verifica le tabelle dopo i cambiamenti di versione principali. La documentazione raccomanda di eseguire prima un backup di tutti i database. Consulta la documentazione ufficiale di mariadb-upgrade .

Questo è un comando specifico, non universale. Non eseguirlo mariadb-upgradesu Oracle MySQL. Allo stesso modo, non applicare le ipotesi di MySQL 8.0 a un server MariaDB solo perché entrambi accettano il mysqlprotocollo client.

6. Verificare che l'account del database Kopano disponga ancora dei privilegi richiesti.

Il manuale di amministrazione di Kopano afferma che il server necessita di autorizzazioni tra cui ALTER, CREATE, CREATE ROUTINE, DELETE, DROP, INDEX, INSERT, LOCK TABLES, SELECT, e UPDATEsul database di Kopano. I parametri di connessione al database vengono configurati tramite le impostazioni relative a MySQL in /etc/kopano/server.cfg. Vedere Configurare i componenti KC .

Dopo una migrazione di versione di MySQL, un amministratore potrebbe ricreare gli utenti, modificare i plugin di autenticazione, spostare l'host del database o ripristinare i permessi in modo incompleto. Prova a utilizzare lo stesso hostname e lo stesso account usati da Kopano. Se l'autenticazione fallisce prima dell'esecuzione di qualsiasi query SQL di migrazione, risolvi prima il problema relativo all'account o ai permessi.

7. Riparare solo il problema dimostrato dall'errore

A questo punto dovreste avere una classe di errore concreta. Applicate la modifica più piccola che la spieghi:

• Aggiornamento parziale dello schema Kopano: seguire l'aggiornamento Kopano specifico per la release o kopano-dbadmle istruzioni identificate dalla versione installata. Non eliminare mai un indicatore di versione né aggiungere manualmente colonne solo per far funzionare l'istruzione successiva.
• Mancata corrispondenza del set di caratteri o della collazione: identificare innanzitutto la tabella e la colonna interessate. Pianificare le conversioni rispetto a una copia ripristinata prima di intervenire sull'ambiente di produzione, poiché le modifiche al set di caratteri possono alterare le dimensioni degli indici e il comportamento dei confronti.
• Mancata corrispondenza della tabella di sistema di MariaDB: completare la procedura di aggiornamento di MariaDB documentata, quindi riprovare con Kopano.
• Permessi o autenticazione: correggere l'account Kopano DB e verificare l'accesso dall'host Kopano.
• Combinazione di versioni non supportata: interrompere gli esperimenti di configurazione. Ripristinare l'ambiente del database precedente all'aggiornamento oppure passare a una combinazione Kopano/database supportata dal fornitore o dalla fonte del pacchetto.

L'ultimo caso è importante. Il manuale di amministrazione di Kopano Core, accessibile al pubblico, si riferisce a una generazione di prodotto precedente, mentre le versioni attuali di MySQL e MariaDB sono in continua evoluzione. Se non si trova una dichiarazione di supporto per la propria specifica combinazione di sistemi, la mancanza di documentazione non deve essere interpretata come indice di compatibilità.

8. Avvia Kopano e convalida più dello stato del processo

sudo systemctl start kopano-server
sudo systemctl start kopano-spooler

systemctl --no-pager --full status kopano-server
journalctl -u kopano-server -n 50 --no-pager

Uno stato di servizio corretto è necessario ma non sufficiente; esamina il registro di avvio e quindi verifica gli archivi utente e il flusso di posta.

Dopo aver verificato che il servizio rimanga attivo, testate il comportamento reale dell'applicazione. Aprite almeno una casella di posta esistente, verificate la presenza di cartelle e messaggi precedenti, inviate un messaggio tra due account locali, inviate un messaggio in uscita e confermate che la ricezione dei messaggi funzioni correttamente. Se utilizzate IMAP, ActiveSync, l'archiviazione, componenti multi-server o l'archiviazione esterna degli allegati, testate anche queste opzioni.

Quando è opportuno cambiare approccio?

Interrompere la ripetizione delle modifiche allo schema quando si verifica una qualsiasi di queste condizioni:

• L'errore SQL cambia dopo ogni modifica manuale, il che suggerisce uno schema parzialmente migrato.
• Il database ripristinato prima dell'aggiornamento funziona con la vecchia versione del database, ma non funziona correttamente con la nuova.
• Non è possibile stabilire se la build di Kopano in uso supporti la versione principale di MySQL o MariaDB installata.
• I controlli delle tabelle segnalano un danneggiamento anziché una normale incompatibilità dello schema.
• Una conversione del set di caratteri richiederebbe la modifica di molte tabelle di grandi dimensioni senza un rollback testato.

In questi casi, la soluzione più sicura è spesso quella di ricreare l'ambiente del database precedente, ripristinare un backup funzionante e pianificare un aggiornamento graduale in un clone. Oracle precisa che il downgrade di MySQL 8.0 alla versione 5.7 non è supportato in loco; l'alternativa supportata è il ripristino di un backup eseguito prima dell'aggiornamento. Consultare le note di rilascio di MySQL 8.0 .

Lista di controllo per la verifica finale

• Vengono conservati il ​​backup del database e il backup della configurazione di Kopano.
• Viene registrata la versione esatta di MySQL o MariaDB.
• Il primo vero errore SQL è stato identificato e spiegato.
• Non è stata applicata alcuna soluzione alternativa generica relativa alla modalità SQL o al set di caratteri senza prove.
• La manutenzione richiesta dello schema Kopano corrisponde alla versione di Kopano installata.
• kopano-serversopravvive a un secondo riavvio.
• Le caselle di posta, le cartelle e i messaggi esistenti sono rimasti intatti.
• I test di consegna in entrata, in uscita e locale hanno esito positivo.
• I componenti opzionali utilizzati dal vostro ambiente sono stati testati.

Un problema di migrazione del database si risolve quando lo schema, il server del database e la versione di Kopano tornano a essere coerenti, non quando il messaggio di errore scompare semplicemente. Conservate le prove che hanno portato alla risoluzione del problema, perché si tratta delle informazioni necessarie anche per il prossimo aggiornamento del database o di Kopano.