Résolution des erreurs de migration de la base de données Kopano après une mise à niveau de MySQL

Une erreur de migration de base de données Kopano survenant immédiatement après une mise à niveau de MySQL ou MariaDB signifie généralement que l'application et la base de données ne sont plus compatibles sur un point auparavant implicite : état du schéma, paramètres par défaut du serveur, comportement SQL, authentification ou chemin de mise à niveau lui-même. L'objectif n'est pas simplement de réussir le kopano-serverdémarrage. Il s'agit d'atteindre un état où le schéma est cohérent, où Kopano démarre sans erreur de mise à niveau, où les utilisateurs peuvent ouvrir leurs boutiques et où le flux de messagerie est rétabli après un redémarrage.

Ce guide se base sur les preuves. Chaque étape comprend un indicateur de réussite et un moment où il est conseillé d'abandonner la même solution et de changer de direction. La documentation d'administration publique de Kopano étant antérieure aux versions actuelles de MySQL et MariaDB, ne présumez pas que toutes les versions modernes de bases de données sont compatibles avec toutes les anciennes versions de Kopano. Utilisez la version exacte du package Kopano, le fournisseur de la base de données et l'erreur serveur comme éléments de preuve déterminants.

Commencez par le résultat dont vous avez besoin

Avant de modifier la configuration, définissez ce que signifie « corrigé ». Une récupération réussie présente généralement tous les signes suivants :

• kopano-serverdémarre et reste en fonctionnement après un redémarrage du service.
• Le journal de Kopano ne signale plus de mise à niveau du schéma de base de données ni d'échec d'exécution SQL.
• La base de données est accessible en lecture et en écriture par le compte Kopano configuré.
• Les magasins et utilisateurs existants sont visibles, et non un schéma vide nouvellement créé.
• L'envoi et la livraison du courrier reprennent normalement.
• Un second redémarrage produit le même résultat satisfaisant.

Si vous n'atteignez que le premier objectif, poursuivez les tests. Un démarrage temporaire après une modification sql_mode, par exemple, ne prouve pas que le schéma sous-jacent est correct.

1. Arrêtez les processus d'écriture Kopano et effectuez une sauvegarde de base de données restaurable.

La documentation de mise à niveau de Kopano recommande de sauvegarder la base de données et les fichiers de configuration, puis d'arrêter les services qui utilisent la base de données avant toute opération de mise à niveau. La documentation mentionne spécifiquement l'arrêt de ces services kopano-spooler, kopano-serverainsi que celui des composants optionnels en cours d'exécution. Consultez la documentation de mise à niveau de 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

Pour une installation importante, conservez également /etc/kopano/les fichiers joints, notez leur emplacement de stockage et suivez votre politique de sauvegarde de base de données existante. Si les pièces jointes sont stockées en dehors de MySQL, une simple sauvegarde SQL ne constitue pas une sauvegarde complète de Kopano.

Arrêtez les services Kopano qui écrivent dans la base de données et vérifiez qu'une sauvegarde récente existe avant de modifier le schéma ou les paramètres du serveur.

Signal de réussite : vous disposez d’une sauvegarde qui peut être restaurée sur une instance de base de données distincte et vous savez où sont stockées les pièces jointes externes. Changez d’approche si la sauvegarde elle-même échoue. Corrigez la corruption de la base de données, les permissions, l’espace disque ou la connectivité avant de tenter une migration de schéma Kopano.

2. Notez la version exacte de la base de données et les valeurs par défaut modifiées.

Une mise à jour majeure de MySQL peut modifier les paramètres par défaut du serveur sans toucher aux tables existantes. Par exemple, MySQL 8.0 a modifié le jeu de caractères par défaut du serveur utf8mb4et le classement par défaut utf8mb4_0900_ai_ci. D'autres paramètres par défaut ont également été modifiés, et des comportements antérieurs ont été supprimés ou rendus obsolètes. Oracle documente ces différences dans le document « Changes in MySQL 8.0 » .

Capturez l'état réel du serveur plutôt que de supposer ce qu'a fait la mise à jour du paquet :

mysql -u root -p

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

Notez la version de la base de données et les valeurs par défaut que Kopano utilise actuellement ; ces valeurs permettent d’expliquer les erreurs survenues uniquement après la mise à niveau de la base de données.

Ne désactivez pas immédiatement les modes SQL stricts. Une erreur en mode strict peut révéler des données héritées invalides ou des requêtes SQL qui doivent être corrigées. La désactivation du mode strict peut masquer le problème tout en laissant des données susceptibles d'échouer ultérieurement. Commencez par extraire l'instruction ou l'erreur de base de données exacte à partir du journal de Kopano.

3. Lisez la première erreur SQL, et pas seulement l'échec final du service.

Systemd n'affiche souvent que l' kopano-serverinstruction « exited ». La ligne utile se trouve généralement plus tôt dans le journal ou le journal Kopano. Commencez par :

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

Ensuite, classifiez la panne. Le tableau suivant constitue un outil de triage pratique et non une affirmation selon laquelle une seule cause s'applique à toutes les installations.

Le journal des modifications de Kopano confirme que certaines versions ont introduit des changements de schéma nécessitant kopano-dbadmdes opérations spécifiques. Il recense également les anomalies survenues lors des mises à niveau de la base de données, notamment les échecs liés aux anciennes définitions de tables MySQL et aux mises à niveau vers utf8mb4. Consultez le journal des modifications de Kopano Core pour identifier la procédure de maintenance applicable à votre version de Kopano.

4. Comparez le schéma Kopano existant avec les paramètres par défaut du nouveau serveur.

Vérifiez le schéma tel qu'il existe ; les paramètres par défaut du serveur ne vous indiquent pas à quoi ressemblent les anciennes tables Kopano.

SHOW CREATE DATABASE kopano;
SHOW TABLE STATUS FROM kopano;

Examinez la définition de la base de données Kopano existante et les moteurs de stockage tout en conservant l'erreur de migration d'origine visible à des fins de comparaison.

Si la base de données a été initialement créée avec une version antérieure de MySQL, ses tables peuvent conserver d'anciens jeux de caractères, même si les nouveaux objets utilisent désormais par défaut l'UTF-8MB4. MySQL précise que la mise à niveau de la version 5.7 à la version 8.0 ne convertit pas automatiquement les objets de base de données existants vers le nouveau jeu de caractères par défaut. Cette distinction est importante : une migration peut échouer si une nouvelle colonne ou un nouvel index est créé avec des valeurs par défaut différentes de celles des objets voisins.

Kopano a intégré la prise en charge de l'UTF-8mb4 dans ses versions ultérieures et a documenté une procédure de maintenance spécifique kopano-dbadm usmppour la mise à niveau des bases de données existantes afin de prendre en charge l'Unicode 4 octets. N'exécutez pas cette commande simplement parce que MySQL utilise désormais l'UTF-8mb4 par défaut ; exécutez-la uniquement si la documentation de votre version de Kopano ou les messages du serveur le demandent.

5. Si MariaDB a été mis à niveau, effectuez d'abord la mise à niveau côté MariaDB.

Si votre base de données est MariaDB et non Oracle MySQL, terminez la procédure de mise à niveau de votre serveur de base de données avant d'incriminer Kopano. La documentation de MariaDB décrit mariadb-upgradecet outil comme mettant à jour les tables système et vérifiant les tables après les changements de version majeure. Il est recommandé de sauvegarder toutes les bases de données au préalable. Consultez la documentation officielle de mariadb-upgrade .

Il s'agit d'une branche spécifique, et non d'une commande universelle. Ne l'exécutez pas mariadb-upgradesur Oracle MySQL. Inversement, n'appliquez pas les hypothèses de MySQL 8.0 à un serveur MariaDB sous prétexte que les deux acceptent le mysqlprotocole client.

6. Vérifiez que le compte de base de données Kopano dispose toujours des privilèges requis.

Le manuel d'administration de Kopano indique que le serveur nécessite les autorisations suivantes sur la base de données KopanoALTER : [ CREATEliste CREATE ROUTINEdes DELETEautorisations DROPmanquante ] . Les paramètres de connexion à la base de données sont configurés via les paramètres MySQL dans [référence manquante] . INDEXVoir « Configurer les composants KC » .INSERTLOCK TABLESSELECTUPDATE/etc/kopano/server.cfg

Après une migration de version MySQL, un administrateur peut être amené à recréer des utilisateurs, modifier les plugins d'authentification, déplacer l'hôte de la base de données ou restaurer partiellement les droits d'accès. Testez avec le même nom d'hôte et le même compte que ceux utilisés par Kopano. Si l'authentification échoue avant l'exécution de toute requête SQL de migration, corrigez d'abord le problème de compte ou de droits d'accès.

7. Ne réparez que la condition prouvée par l'erreur.

À ce stade, vous devriez avoir une seule classe de défaillance concrète. Appliquez la plus petite modification qui l'explique :

• Mise à jour partielle du schéma Kopano : suivez la procédure de mise à niveau Kopano spécifique à votre version ou kopano-dbadmles instructions identifiées par la version installée. Ne supprimez jamais un marqueur de version et n’ajoutez jamais manuellement de colonnes dans le seul but de permettre l’exécution de la requête suivante.
• Incompatibilité de jeu de caractères ou de classement : identifiez d’abord la table et la colonne concernées. Planifiez les conversions à partir d’une copie restaurée avant d’intervenir en production, car les modifications du jeu de caractères peuvent altérer la taille des index et le comportement des comparaisons.
• Incompatibilité des tables système MariaDB : veuillez suivre la procédure de mise à niveau documentée de MariaDB, puis réessayer Kopano.
• Autorisations ou authentification : corrigez le compte de base de données Kopano et vérifiez la connexion depuis l’hôte Kopano.
• Combinaison de versions non prise en charge : arrêtez les tests de configuration. Restaurez l’environnement de base de données antérieur à la mise à niveau ou utilisez une combinaison Kopano/base de données compatible avec votre fournisseur ou votre source de paquets.

Ce dernier point est important. Le manuel d'administration de Kopano Core, accessible au public, concerne une version antérieure du produit, tandis que les versions actuelles de MySQL et MariaDB ont évolué. Si vous ne trouvez aucune mention de compatibilité pour votre configuration exacte, l'absence de documentation ne signifie pas nécessairement que le produit est compatible.

8. Démarrez Kopano et validez plus que l'état du processus.

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

Un état de service sain est nécessaire mais non suffisant ; consultez le journal de démarrage, puis validez les magasins d’utilisateurs et le flux de messagerie.

Une fois le service opérationnel, effectuez des tests en conditions réelles d'utilisation. Ouvrez au moins une boîte mail existante, vérifiez la présence des anciens dossiers et messages, envoyez un message entre deux comptes locaux, envoyez un message sortant et assurez-vous que la réception des messages fonctionne correctement. Si vous utilisez IMAP, ActiveSync, l'archivage, des composants multi-serveurs ou un stockage externe de pièces jointes, effectuez également ces tests.

Quand faut-il changer d'approche ?

Cessez de répéter les modifications de schéma lorsque l'une de ces conditions apparaît :

• L'erreur SQL change après chaque modification manuelle, ce qui suggère un schéma partiellement migré.
• La base de données restaurée avant la mise à niveau fonctionne sur l'ancienne version de la base de données, mais échoue systématiquement sur la nouvelle.
• Vous ne pouvez pas établir que votre version de Kopano prend en charge la version majeure de MySQL ou MariaDB installée.
• Les vérifications de tables signalent une corruption plutôt qu'une incompatibilité de schéma classique.
• Une conversion d'encodage de caractères nécessiterait la modification de nombreuses tables volumineuses sans procédure de restauration testée.

Dans ces cas-là, la solution la plus sûre consiste souvent à recréer l'environnement de base de données précédent, à restaurer la sauvegarde valide et à planifier une mise à niveau progressive dans un clone. Oracle précise que la rétrogradation de MySQL 8.0 vers la version 5.7 n'est pas prise en charge ; l'alternative recommandée est la restauration d'une sauvegarde effectuée avant la mise à niveau. Consultez les notes de version de MySQL 8.0 .

Liste de vérification finale

• La sauvegarde de la base de données et la sauvegarde de la configuration de Kopano sont conservées.
• La version exacte de MySQL ou de MariaDB est enregistrée.
• La première véritable erreur SQL a été identifiée et expliquée.
• Aucune solution de contournement générale concernant le mode SQL ou l'encodage de caractères n'a été appliquée sans preuve.
• La maintenance requise du schéma Kopano correspond à la version de Kopano installée.
• kopano-serversurvit à un second redémarrage.
• Les boîtes aux lettres, dossiers et messages existants sont intacts.
• Les tests de livraison entrante, sortante et locale sont concluants.
• Les composants optionnels utilisés par votre environnement ont été testés.

Un problème de migration de base de données est résolu lorsque le schéma, le serveur de base de données et la version de Kopano sont de nouveau compatibles, et non lorsque le message d'erreur a simplement disparu. Conservez les éléments de preuve ayant permis la réparation, car ils vous seront nécessaires pour la prochaine mise à niveau de votre base de données ou de Kopano.