Behebung von Kopano-Datenbankmigrationsfehlern nach einem MySQL-Versionsupgrade

Ein Datenbankmigrationsfehler in Kopano unmittelbar nach einem MySQL- oder MariaDB-Versionsupgrade deutet in der Regel darauf hin, dass Anwendung und Datenbank in Bezug auf zuvor implizite Aspekte nicht mehr übereinstimmen: Schemastatus, Servervorgaben, SQL-Verhalten, Authentifizierung oder der Upgrade-Pfad selbst. Ziel ist es nicht, Kopano einfach nur kopano-servereinmalig zum Laufen zu bringen. Vielmehr soll ein Zustand erreicht werden, in dem das Schema konsistent ist, Kopano ohne Datenbank-Upgrade-Fehler startet, Benutzer Shops öffnen können und der E-Mail-Verkehr auch nach einem Neustart funktioniert.

Dieser Leitfaden konzentriert sich auf die Beweisführung. Jede Phase beinhaltet ein Erfolgssignal und einen Punkt, an dem Sie die gleiche Lösung nicht weiterverfolgen und eine andere Vorgehensweise wählen sollten. Die öffentliche Administratordokumentation von Kopano ist älter als die aktuellen MySQL- und MariaDB-Versionen. Gehen Sie daher nicht davon aus, dass jede moderne Datenbankversion von jeder älteren Kopano-Version unterstützt wird. Verwenden Sie die genaue Kopano-Paketversion, den Datenbankanbieter und die Serverfehlermeldung als entscheidenden Beweis.

Beginnen Sie mit dem gewünschten Ergebnis.

Bevor Sie die Konfiguration ändern, definieren Sie, was „behoben“ bedeutet. Eine erfolgreiche Wiederherstellung weist normalerweise alle folgenden Merkmale auf:

• kopano-serverStartet und läuft nach einem Neustart des Dienstes weiter.
• Im Kopano-Protokoll werden keine Aktualisierungen des Datenbankschemas oder Fehler bei der SQL-Ausführung mehr gemeldet.
• Die Datenbank ist für das konfigurierte Kopano-Konto les- und beschreibbar.
• Es werden bestehende Shops und Benutzer angezeigt, anstatt eines neu erstellten leeren Schemas.
• Postannahme und -zustellung werden wieder normal aufgenommen.
• Ein zweiter Neustart führt zum gleichen positiven Ergebnis.

Wenn Sie nur den ersten Punkt erreicht haben, testen Sie weiter. Ein vorübergehender Erfolg nach einer Änderung sql_modebeweist beispielsweise nicht, dass das zugrunde liegende Schema korrekt ist.

1. Kopano-Schreiber stoppen und ein wiederherstellbares Datenbank-Backup erstellen.

Die Upgrade-Dokumentation von Kopano empfiehlt, vor dem Upgrade die Datenbank und die Konfigurationsdateien zu sichern sowie die datenbankbezogenen Dienste zu beenden. Die Dokumentation weist insbesondere auf das Beenden von [hier fehlende Information] kopano-spoolerund kopano-server[hier fehlende Information] sowie optionaler, laufender Komponenten hin. Weitere Informationen finden Sie in der Kopano Core-Upgrade-Dokumentation .

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

Bei einer großen Installation sollten Sie auch /etc/kopano/die Speicherorte der Anhänge beachten und Ihre bestehende Datenbank-Backup-Richtlinie befolgen. Wenn Anhänge außerhalb von MySQL gespeichert werden, stellt ein SQL-Dump allein kein vollständiges Kopano-Backup dar.

Stoppen Sie die Kopano-Dienste, die in die Datenbank schreiben, und vergewissern Sie sich, dass ein aktueller Datenbank-Dump vorhanden ist, bevor Sie das Schema oder die Servereinstellungen ändern.

Erfolgssignal: Sie verfügen über ein Backup, das auf einer separaten Datenbankinstanz wiederhergestellt werden kann, und wissen, wo externe Anhänge gespeichert sind. Vorgehensweise ändern, falls: die Sicherung selbst fehlschlägt. Beheben Sie Datenbankbeschädigungen, Berechtigungen, Speicherplatzprobleme oder Verbindungsprobleme, bevor Sie eine Kopano-Schema-Migration durchführen.

2. Notieren Sie die genaue Datenbankversion und die geänderten Standardeinstellungen.

Ein größeres MySQL-Upgrade kann die Serverstandardeinstellungen ändern, ohne bestehende Tabellen zu modifizieren. MySQL 8.0 hat beispielsweise den Standardzeichensatz utf8mb4und die Standardsortierung geändert utf8mb4_0900_ai_ci. Außerdem wurden weitere Standardeinstellungen angepasst und ältere Verhaltensweisen entfernt oder als veraltet markiert. Oracle dokumentiert diese Unterschiede in „ Changes in MySQL 8.0“ .

Erfassen Sie den tatsächlichen Serverzustand, anstatt anzunehmen, was das Paket-Upgrade bewirkt hat:

mysql -u root -p

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

Notieren Sie die Datenbankversion und die Standardeinstellungen, die Kopano jetzt sieht; diese Werte helfen, Fehler zu erklären, die erst nach dem Datenbank-Upgrade aufgetreten sind.

Deaktivieren Sie den strikten SQL-Modus nicht sofort. Ein Fehler im strikten Modus kann ungültige Altdaten oder fehlerhaften SQL-Code aufdecken, der korrigiert werden muss. Das Deaktivieren des strikten Modus kann das Symptom verschleiern, während Daten, die später zu Fehlern führen, bestehen bleiben. Ermitteln Sie zunächst die genaue fehlerhafte Anweisung oder den Datenbankfehler aus dem Kopano-Protokoll.

3. Lesen Sie den ersten SQL-Fehler, nicht nur den letzten Dienstausfall.

Systemd zeigt oft nur die kopano-serverBeendigung an. Die relevante Zeile befindet sich meist weiter oben im Journal oder Kopano-Log. Beginnen Sie mit:

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

Klassifizieren Sie anschließend den Fehler. Die folgende Tabelle dient als praktische Priorisierungshilfe und erhebt keinen Anspruch darauf, dass eine einzige Ursache für jede Installation zutrifft.

Das Änderungsprotokoll von Kopano bestätigt, dass einige Versionen Schemaänderungen mit sich brachten, die spezielle kopano-dbadmOperationen erforderten. Es dokumentiert außerdem Fehler bei früheren Datenbank-Upgrades, darunter Probleme mit alten MySQL-Tabellendefinitionen und utf8mb4-Upgrades. Nutzen Sie das Änderungsprotokoll von Kopano Core, um die Wartungsmaßnahme Ihrer genauen Kopano-Version zuzuordnen.

4. Vergleichen Sie das bestehende Kopano-Schema mit den neuen Serverstandardeinstellungen.

Prüfen Sie das bestehende Schema; die Servervorgaben allein geben keine Auskunft darüber, wie alte Kopano-Tabellen definiert sind.

SHOW CREATE DATABASE kopano;
SHOW TABLE STATUS FROM kopano;

Untersuchen Sie die bestehende Kopano-Datenbankdefinition und die Speichermodule, während Sie den ursprünglichen Migrationsfehler zum Vergleich sichtbar lassen.

Wurde die Datenbank ursprünglich mit einer älteren MySQL-Version erstellt, verwenden ihre Tabellen möglicherweise weiterhin ältere Zeichensätze, obwohl neu erstellte Objekte standardmäßig utf8mb4 verwenden. MySQL weist ausdrücklich darauf hin, dass ein Upgrade von Version 5.7 auf 8.0 bestehende Datenbankobjekte nicht automatisch in den neuen Standardzeichensatz konvertiert. Diese Unterscheidung ist wichtig: Eine Migration kann fehlschlagen, wenn eine neue Spalte oder ein neuer Index mit anderen Standardwerten als benachbarte Objekte erstellt wird.

Kopano selbst hat in späteren Core-Versionen die Unterstützung für utf8mb4 hinzugefügt und einen spezifischen Wartungsschritt für die Datenbanken dokumentiert, kopano-dbadm usmpum bestehende Datenbanken für die Unterstützung von 4-Byte-Unicode zu aktualisieren. Führen Sie diesen Befehl nicht einfach aus, nur weil MySQL jetzt standardmäßig utf8mb4 verwendet; führen Sie ihn nur dann aus, wenn die Dokumentation Ihrer installierten Kopano-Version oder die Serverausgabe dies erfordert.

5. Falls MariaDB aktualisiert wurde, führen Sie zuerst das MariaDB-seitige Upgrade durch.

Wenn Sie MariaDB anstelle von Oracle MySQL als Backend verwenden, führen Sie bitte das Upgrade des Datenbankservers durch, bevor Sie Kopano die Schuld geben. MariaDB ist mariadb-upgradeals Tool zum Aktualisieren von Systemtabellen und zum Überprüfen von Tabellen nach Versionsänderungen dokumentiert. Die Dokumentation empfiehlt, zuvor alle Datenbanken zu sichern. Weitere Informationen finden Sie in der offiziellen Referenz zu MariaDB-Upgrades .

Dies ist ein Zweig, kein universeller Befehl. Führen Sie ihn nicht mariadb-upgrademit Oracle MySQL aus. Umgekehrt sollten Sie die Annahmen von MySQL 8.0 nicht auf einen MariaDB-Server anwenden, nur weil beide das mysqlClient-Protokoll akzeptieren.

6. Überprüfen Sie, ob das Kopano-Datenbankkonto noch über die erforderlichen Berechtigungen verfügt.

Das Administratorhandbuch von Kopano gibt an, dass der Server unter anderem die Berechtigungen für die Kopano-Datenbank benötigt . Die Datenbankverbindungsparameter ALTERwerden über die MySQL-bezogenen Einstellungen konfiguriert . Siehe „KC - Komponenten konfigurierenCREATE “ .CREATE ROUTINEDELETEDROPINDEXINSERTLOCK TABLESSELECTUPDATE/etc/kopano/server.cfg

Nach einer MySQL-Versionsmigration kann es vorkommen, dass ein Administrator Benutzer neu anlegt, Authentifizierungs-Plugins ändert, den Datenbank-Host verschiebt oder Berechtigungen unvollständig wiederherstellt. Testen Sie daher denselben Hostnamen und dasselbe Konto, die auch Kopano verwendet. Falls die Authentifizierung vor der Ausführung von Migrations-SQL fehlschlägt, beheben Sie zunächst das Konto- oder Berechtigungsproblem.

7. Reparieren Sie nur den durch den Fehler nachgewiesenen Mangel.

An diesem Punkt sollten Sie eine konkrete Fehlerklasse haben. Wenden Sie die kleinste Änderung an, die diese erklärt:

• Partielle Kopano-Schemaaktualisierung: Befolgen Sie die versionsspezifische Kopano-Aktualisierung oder kopano-dbadmdie Anweisungen, die für die installierte Version angegeben sind. Löschen Sie niemals eine Versionsmarkierung oder fügen Sie manuell Spalten hinzu, nur um die nächste Anweisung auszuführen.
• Zeichensatz- oder Sortierungskonflikt: Identifizieren Sie zunächst die betroffene Tabelle und Spalte. Planen Sie Konvertierungen anhand einer wiederhergestellten Kopie, bevor Sie die Produktionsumgebung beeinträchtigen, da Zeichensatzänderungen die Indexgrößen und das Vergleichsverhalten verändern können.
• MariaDB-Systemtabellenkonflikt: Führen Sie die dokumentierte MariaDB-Upgrade-Prozedur durch und versuchen Sie es dann erneut mit Kopano.
• Berechtigungen oder Authentifizierung: Korrigieren Sie das Kopano-DB-Konto und überprüfen Sie eine Anmeldung vom Kopano-Host.
• Nicht unterstützte Versionskombination: Konfigurationsversuche abbrechen. Stellen Sie die Datenbankumgebung vor dem Upgrade wieder her oder wechseln Sie zu einer Kopano/Datenbank-Kombination, die von Ihrem Anbieter oder Ihrer Paketquelle unterstützt wird.

Der letzte Fall ist wichtig. Das öffentlich zugängliche Administratorhandbuch für Kopano Core stammt aus einer älteren Produktgeneration, während sich die aktuellen Versionen von MySQL und MariaDB ständig weiterentwickeln. Sollten Sie keine Support-Aussage für Ihre genaue Systemkombination finden, bedeutet das Fehlen von Dokumentation nicht automatisch Kompatibilität.

8. Starten Sie Kopano und validieren Sie mehr als nur den Prozessstatus.

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

Ein einwandfreier Dienstzustand ist notwendig, aber nicht ausreichend; überprüfen Sie das Startprotokoll und validieren Sie anschließend die Benutzerspeicher und den E-Mail-Verkehr.

Nachdem der Dienst stabil läuft, testen Sie ihn mit realen Anwendungen. Öffnen Sie mindestens ein vorhandenes Postfach, prüfen Sie, ob alte Ordner und Nachrichten vorhanden sind, senden Sie eine Nachricht zwischen zwei lokalen Konten, senden Sie eine ausgehende Nachricht und bestätigen Sie die Zustellung eingehender Nachrichten. Falls Sie IMAP, ActiveSync, Archivierung, Multi-Server-Komponenten oder externen Speicher für Anhänge verwenden, testen Sie auch diese Funktionen.

Wann sollten Sie Ihre Vorgehensweise ändern?

Die Schemaänderungen sollten nicht wiederholt werden, wenn eine der folgenden Bedingungen eintritt:

• Der SQL-Fehler ändert sich nach jeder manuellen Änderung, was auf ein nur teilweise migriertes Schema hindeutet.
• Die wiederhergestellte Datenbank vor dem Upgrade funktioniert mit der alten Datenbankversion, schlägt aber mit der neuen Version stets fehl.
• Sie können nicht feststellen, ob Ihre Kopano-Version die installierte MySQL- oder MariaDB-Hauptversion unterstützt.
• Die Tabellenprüfungen melden eine Beschädigung und keine normale Schema-Inkompatibilität.
• Eine Zeichensatzkonvertierung würde die Änderung vieler großer Tabellen ohne getestete Rücksetzmöglichkeit erfordern.

In solchen Fällen ist es oft sicherer, die vorherige Datenbankumgebung wiederherzustellen, das funktionierende Backup einzuspielen und ein schrittweises Upgrade in einem Klon zu planen. Oracle weist darauf hin, dass ein Downgrade von MySQL 8.0 auf 5.7 nicht direkt unterstützt wird; die empfohlene Alternative ist die Wiederherstellung eines Backups, das vor dem Upgrade erstellt wurde. Siehe die Versionshinweise zu MySQL 8.0 .

Checkliste zur abschließenden Überprüfung

• Die Datenbanksicherung und die Kopano-Konfigurationssicherung bleiben erhalten.
• Die genaue MySQL- oder MariaDB-Version wird protokolliert.
• Der erste echte SQL-Fehler wurde identifiziert und erklärt.
• Ohne Beweise wurde kein umfassender SQL-Modus- oder Zeichensatz-Workaround angewendet.
• Die erforderliche Kopano-Schema-Wartung entspricht der installierten Kopano-Version.
• kopano-serverÜbersteht auch einen zweiten Neustart.
• Vorhandene Postfächer, Ordner und Nachrichten bleiben erhalten.
• Die Tests für eingehende, ausgehende und lokale Zustellungen waren erfolgreich.
• Die in Ihrer Umgebung verwendeten optionalen Komponenten wurden getestet.

Ein Problem mit der Datenbankmigration ist erst dann behoben, wenn Schema, Datenbankserver und Kopano-Version wieder übereinstimmen – nicht erst, wenn die Fehlermeldung einfach verschwunden ist. Bewahren Sie die Nachweise für die erfolgreiche Behebung auf, da Sie diese Informationen auch für das nächste Datenbank- oder Kopano-Upgrade benötigen.