Corrigeer migratiefouten in de Kopano-database na een MySQL-versie-upgrade.

Een database-migratiefout in Kopano direct na een upgrade van MySQL of MariaDB betekent meestal dat de applicatie en de database het niet langer eens zijn over iets dat voorheen impliciet was: de schemastatus, serverinstellingen, SQL-gedrag, authenticatie of het upgradepad zelf. Het nuttige doel is niet alleen om het systeem kopano-serveréén keer te laten opstarten. Het doel is om een ​​situatie te bereiken waarin het schema consistent is, Kopano opstart zonder database-upgradefouten, gebruikers winkels kunnen openen en de e-mailstroom een ​​herstart overleeft.

Deze handleiding richt zich op bewijsmateriaal. Elke fase bevat een succesindicator en een punt waarop u moet stoppen met het proberen van dezelfde oplossing en een andere richting moet inslaan. De openbare beheerdersdocumentatie van Kopano is ouder dan de huidige MySQL- en MariaDB-releases, dus ga er niet vanuit dat elke moderne databaseversie wordt ondersteund door elke oudere Kopano-build. Gebruik de exacte Kopano-pakketversie, databaseleverancier en serverfout als doorslaggevend bewijsmateriaal.

Begin met het gewenste resultaat.

Voordat u de configuratie wijzigt, definieer dan wat "opgelost" inhoudt. Een succesvol herstel vertoont normaal gesproken al deze kenmerken:

• kopano-serverStart en blijft draaien na een herstart van de service.
• Het Kopano-logboek meldt niet langer een upgrade van het databaseschema of een fout bij de uitvoering van SQL-query's.
• De database is leesbaar en beschrijfbaar voor het geconfigureerde Kopano-account.
• Bestaande winkels en gebruikers zijn zichtbaar, in plaats van een nieuw, leeg schema.
• Het verzenden en bezorgen van post verloopt weer zoals gebruikelijk.
• Een tweede herstart levert hetzelfde gezonde resultaat op.

Als je alleen het eerste item bereikt, blijf dan testen. Een tijdelijke start na een wijziging sql_modebewijst bijvoorbeeld niet dat het onderliggende schema correct is.

1. Stop de Kopano-writers en maak een herstelbare back-up van de database.

De upgrade-documentatie van Kopano adviseert om een ​​back-up te maken van de database en configuratiebestanden en de services die de database gebruiken te stoppen voordat de upgrade wordt uitgevoerd. De documentatie vermeldt specifiek het stoppen van kopano-spooleren kopano-server, plus optionele componenten die actief zijn. Zie de upgrade-documentatie van 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

Voor een grote installatie is het belangrijk om ook /etc/kopano/de locatie van de bijlagen te bewaren en uw bestaande back-upbeleid voor de database te volgen. Als bijlagen buiten MySQL worden opgeslagen, is een SQL-dump alleen geen volledige Kopano-back-up.

Stop de Kopano-services die naar de database schrijven en controleer of er een recente back-up beschikbaar is voordat u schema- of serverinstellingen wijzigt.

Succesvol resultaat: u hebt een back-up die kan worden hersteld naar een aparte database-instantie en u weet waar externe bijlagen zijn opgeslagen. Wijzig uw aanpak als: de dump zelf mislukt. Los databasecorruptie, machtigingen, schijfruimteproblemen of verbindingsproblemen op voordat u een Kopano-schemamigratie probeert uit te voeren.

2. Noteer de exacte databaseversie en de gewijzigde standaardinstellingen.

Een grote MySQL-upgrade kan de standaardinstellingen van de server wijzigen zonder de bestaande tabellen aan te passen. MySQL 8.0 heeft bijvoorbeeld de standaard tekenset van de server gewijzigd naar utf8mb4en de standaard sortering naar utf8mb4_0900_ai_ci. Ook andere standaardinstellingen zijn gewijzigd en ouder gedrag is verwijderd of afgekeurd. Oracle documenteert deze verschillen in Changes in MySQL 8.0 .

Leg de daadwerkelijke serverstatus vast in plaats van te veronderstellen wat de pakketupgrade heeft gedaan:

mysql -u root -p

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

Noteer de databaseversie en de standaardinstellingen die Kopano nu ziet; deze waarden helpen bij het verklaren van fouten die pas na de database-upgrade zijn opgetreden.

Schakel de strikte SQL-modus niet direct uit. Een fout in de strikte modus kan ongeldige, verouderde gegevens of SQL-query's aan het licht brengen die gecorrigeerd moeten worden. Het uitschakelen van de strikte modus kan het symptoom maskeren, terwijl er gegevens achterblijven die later problemen veroorzaken. Leg eerst de exacte foutieve instructie of databasefout vast uit het logboek van Kopano.

3. Lees de eerste SQL-fout, niet alleen de uiteindelijke servicefout.

Systemd laat vaak alleen zien dat het kopano-serverprogramma is afgesloten. De nuttige regel staat meestal eerder in het journal of het Kopano-logboek. Begin met:

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

Classificeer vervolgens de storing. De volgende tabel is een praktisch stappenplan voor het vaststellen van de oorzaak, en geen bewering dat één oorzaak op elke installatie van toepassing is.

Het changelog van Kopano bevestigt dat sommige releases schemawijzigingen introduceerden die specifieke kopano-dbadmbewerkingen vereisten. Het registreert ook historische fouten bij database-upgrades, waaronder fouten met oude MySQL-tabeldefinities en upgrades naar utf8mb4. Gebruik het changelog van Kopano Core om de onderhoudsactie te koppelen aan uw exacte Kopano-release.

4. Vergelijk het bestaande Kopano-schema met de nieuwe serverstandaardinstellingen.

Controleer het bestaande schema; de standaardinstellingen van de server geven op zichzelf geen informatie over hoe oud de Kopano-tabellen zijn gedefinieerd.

SHOW CREATE DATABASE kopano;
SHOW TABLE STATUS FROM kopano;

Controleer de bestaande Kopano-databasedefinitie en opslagengines, terwijl u de oorspronkelijke migratiefout zichtbaar houdt ter vergelijking.

Als de database oorspronkelijk is aangemaakt met een oudere MySQL-versie, kunnen de tabellen nog steeds oudere tekensets bevatten, zelfs als nieuw aangemaakte objecten nu standaard utf8mb4 gebruiken. MySQL geeft expliciet aan dat een upgrade van 5.7 naar 8.0 bestaande databaseobjecten niet automatisch converteert naar de nieuwe standaardtekenset. Dat onderscheid is belangrijk: een migratie kan mislukken wanneer een nieuwe kolom of index wordt aangemaakt met andere standaardwaarden dan aangrenzende objecten.

Kopano heeft zelf in latere Core-releases ondersteuning voor utf8mb4 toegevoegd en een specifieke databaseonderhoudsstap gedocumenteerd kopano-dbadm usmpvoor het upgraden van bestaande databases naar 4-byte Unicode-ondersteuning. Voer die opdracht niet uit alleen omdat MySQL nu standaard utf8mb4 gebruikt; voer deze alleen uit als de documentatie van uw geïnstalleerde Kopano-release of de serveruitvoer daarom vraagt.

5. Als MariaDB is geüpgraded, voer dan eerst de MariaDB-upgrade uit.

Als je backend MariaDB gebruikt in plaats van Oracle MySQL, voltooi dan eerst de upgrade-procedure van de databaseserver zelf voordat je Kopano de schuld geeft. MariaDB beschrijft zichzelf mariadb-upgradeals de tool die systeemtabellen bijwerkt en tabellen controleert na grote versie-updates. De documentatie raadt aan om eerst een back-up van alle databases te maken. Zie de officiële mariadb-upgrade-referentie .

Dit is een vertakking, geen universeel commando. Voer dit commando niet uit mariadb-upgradeop Oracle MySQL. Omgekeerd geldt de aanname dat MySQL 8.0 niet van toepassing is op een MariaDB-server, alleen omdat beide het mysqlclientprotocol accepteren.

6. Controleer of het Kopano-databaseaccount nog steeds de vereiste rechten heeft.

In de beheerdershandleiding van Kopano staat dat de server machtigingen nodig heeft voor de Kopano-database, waaronder ALTER, CREATE, CREATE ROUTINE, DELETE, DROP, INDEX, INSERT, LOCK TABLES, SELECT, en UPDATE. De databaseverbindingsparameters worden geconfigureerd via de MySQL-gerelateerde instellingen in /etc/kopano/server.cfg. Zie Componenten van Kopano configureren .

Na een MySQL-versiemigratie kan een beheerder gebruikers opnieuw aanmaken, authenticatieplugins wijzigen, de databasehost verplaatsen of machtigingen onvolledig herstellen. Test dezelfde hostnaam en hetzelfde account dat Kopano gebruikt. Als de authenticatie mislukt voordat de migratie-SQL wordt uitgevoerd, los dan eerst het account- of machtigingsprobleem op.

7. Herstel alleen de toestand die door de fout is aangetoond.

Op dit punt zou je één concrete faalklasse moeten hebben. Voer de kleinste wijziging door die deze faalklasse verklaart:

• Gedeeltelijke Kopano-schema-update: volg de releasespecifieke Kopano-upgrade-instructies of kopano-dbadmde instructies die bij de geïnstalleerde versie horen. Verwijder nooit een versieaanduiding en voeg nooit handmatig kolommen toe om de volgende instructie te laten werken.
• Mismatch in tekenset of sortering: identificeer eerst de betreffende tabel en kolom. Plan conversies aan de hand van een herstelde kopie voordat u de productieomgeving aanraakt, omdat wijzigingen in de tekenset de indexgrootte en het vergelijkingsgedrag kunnen beïnvloeden.
• Er is een mismatch in de MariaDB-systeemtabel: voltooi de gedocumenteerde MariaDB-upgradeprocedure en probeer Kopano vervolgens opnieuw.
• Machtigingen of authenticatie: corrigeer het Kopano DB-account en verifieer een aanmelding vanaf de Kopano-host.
• Niet-ondersteunde versiecombinatie: stop de configuratie-experimenten. Herstel de databaseomgeving van vóór de upgrade of stap over naar een Kopano/databasecombinatie die door uw leverancier of pakketbron wordt ondersteund.

Het laatste punt is belangrijk. De openbaar toegankelijke beheerdershandleiding van Kopano Core stamt uit een oudere productgeneratie, terwijl de huidige releases van MySQL en MariaDB voortdurend zijn veranderd. Als u geen ondersteuningsverklaring kunt vinden voor uw specifieke combinatie, moet een gebrek aan documentatie niet worden geïnterpreteerd als compatibiliteit.

8. Start Kopano en valideer meer dan alleen de processtatus.

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

Een goede werking van de service is noodzakelijk, maar niet voldoende; controleer het opstartlogboek en valideer vervolgens de gebruikersarchieven en de e-mailstroom.

Nadat de service operationeel is gebleven, test u het gedrag van de applicatie in de praktijk. Open ten minste één bestaande mailbox, controleer of de oude mappen en berichten aanwezig zijn, verstuur een bericht tussen twee lokale accounts, verstuur één uitgaand bericht en controleer of de inkomende berichten correct worden bezorgd. Als u IMAP, ActiveSync, archivering, componenten voor meerdere servers of externe opslag voor bijlagen gebruikt, test dan ook die mogelijkheden.

Wanneer moet je je aanpak veranderen?

Stop met het herhalen van schemawijzigingen wanneer een van deze situaties zich voordoet:

• De SQL-fout verandert na elke handmatige aanpassing, wat erop wijst dat het schema slechts gedeeltelijk is gemigreerd.
• De herstelde database van vóór de upgrade werkt wel met de oude databaseversie, maar faalt consequent met de nieuwe.
• Je kunt niet vaststellen of je Kopano-build de geïnstalleerde hoofdversie van MySQL of MariaDB ondersteunt.
• Tabelcontroles melden corruptie in plaats van een normale schema-incompatibiliteit.
• Een conversie van de tekenset zou het wijzigen van veel grote tabellen vereisen zonder een geteste terugdraaifunctie.

In dergelijke gevallen is het vaak veiliger om de vorige databaseomgeving te herstellen, de bekende goede back-up terug te zetten en een gefaseerde upgrade in een kloon te plannen. Oracle merkt op dat downgraden van MySQL 8.0 naar 5.7 niet ter plaatse wordt ondersteund; het ondersteunde alternatief is het terugzetten van een back-up die vóór de upgrade is gemaakt. Zie de release-opmerkingen van MySQL 8.0 .

Definitieve verificatiechecklist

• De databaseback-up en de Kopano-configuratieback-up zijn bewaard gebleven.
• De exacte MySQL- of MariaDB-versie wordt vastgelegd.
• De eerste echte SQL-fout is geïdentificeerd en verklaard.
• Er is geen algemene oplossing met betrekking tot de SQL-modus of tekenset toegepast zonder bewijs.
• Het vereiste onderhoud van het Kopano-schema moet overeenkomen met de geïnstalleerde Kopano-release.
• kopano-serveroverleeft een tweede herstart.
• Bestaande mailboxen, mappen en berichten zijn intact.
• De tests voor inkomende, uitgaande en lokale leveringen zijn geslaagd.
• De optionele componenten die in uw omgeving worden gebruikt, zijn getest.

Een probleem met een databasemigratie is opgelost wanneer het schema, de databaseserver en de Kopano-versie weer overeenkomen – niet wanneer de foutmelding simpelweg is verdwenen. Bewaar het bewijsmateriaal dat tot de oplossing heeft geleid, want deze informatie hebt u ook nodig voor de volgende database- of Kopano-upgrade.