Solucionar errores de migración de la base de datos Kopano después de una actualización de la versión de MySQL

Un error de migración de base de datos de Kopano inmediatamente después de una actualización de MySQL o MariaDB suele significar que la aplicación y la base de datos ya no coinciden en algún aspecto que antes era implícito: el estado del esquema, la configuración predeterminada del servidor, el comportamiento de SQL, la autenticación o la ruta de actualización. El objetivo no es simplemente que Kopano kopano-serverarranque una sola vez, sino alcanzar un estado en el que el esquema sea coherente, Kopano se inicie sin errores de actualización de la base de datos, los usuarios puedan abrir tiendas y el flujo de correo se mantenga tras un reinicio.

Esta guía se centra en la evidencia. Cada etapa incluye una señal de éxito y un punto en el que debes dejar de intentar la misma solución y cambiar de enfoque. La documentación pública del administrador de Kopano es anterior a las versiones actuales de MySQL y MariaDB, así que no asumas que todas las versiones modernas de bases de datos son compatibles con todas las versiones históricas de Kopano. Utiliza la versión exacta del paquete de Kopano, el proveedor de la base de datos y el error del servidor como evidencia determinante.

Empiece por el resultado que necesita

Antes de cambiar la configuración, defina qué significará "corregido". Una recuperación exitosa normalmente presenta todas estas señales:

• kopano-serverSe inicia y permanece en funcionamiento después de reiniciar el servicio.
• El registro de Kopano ya no informa de una actualización del esquema de la base de datos ni de un fallo en la ejecución de SQL.
• La base de datos es legible y editable por la cuenta de Kopano configurada.
• Se muestran las tiendas y los usuarios existentes, en lugar de un esquema vacío de nueva creación.
• El envío y la entrega de correo se reanudan con normalidad.
• Un segundo reinicio produce el mismo resultado satisfactorio.

Si solo logras el primer elemento, continúa haciendo pruebas. Un inicio temporal después de realizar un cambio sql_mode, por ejemplo, no demuestra que el esquema subyacente sea correcto.

1. Detenga los escritores de Kopano y realice una copia de seguridad restaurable de la base de datos.

La documentación de actualización de Kopano recomienda realizar una copia de seguridad de la base de datos y los archivos de configuración, así como detener los servicios que utilizan la base de datos antes de la actualización. La documentación menciona específicamente la detención de kopano-spoolery kopano-server, además de los componentes opcionales que se estén ejecutando. Consulte la documentación de actualización 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

Para una instalación grande, conserve también /etc/kopano/la ubicación de almacenamiento de los archivos adjuntos y siga su política de copias de seguridad de la base de datos. Si los archivos adjuntos se almacenan fuera de MySQL, una copia de seguridad SQL por sí sola no constituye una copia de seguridad completa de Kopano.

Detenga los servicios de Kopano que escriben en la base de datos y verifique que exista una copia de seguridad reciente antes de cambiar el esquema o la configuración del servidor.

Señal de éxito: dispone de una copia de seguridad que se puede restaurar en una instancia de base de datos independiente y sabe dónde se almacenan los archivos adjuntos externos. Modifique el enfoque si: la copia de seguridad falla. Solucione la corrupción de la base de datos, los permisos, el espacio en disco o la conectividad antes de intentar una migración del esquema de Kopano.

2. Registre la versión exacta de la base de datos y los cambios en la configuración predeterminada.

Una actualización importante de MySQL puede cambiar la configuración predeterminada del servidor sin modificar las tablas existentes. MySQL 8.0, por ejemplo, cambió el conjunto de caracteres predeterminado del servidor a utf8mb4y la intercalación predeterminada a utf8mb4_0900_ai_ci. También cambió otras configuraciones predeterminadas y eliminó o dejó de usar comportamientos anteriores. Oracle documenta estas diferencias en Cambios en MySQL 8.0 .

Capture el estado real del servidor en lugar de suponer qué hizo la actualización del paquete:

mysql -u root -p

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

Registre la versión de la base de datos y los valores predeterminados que Kopano ahora detecta; estos valores ayudan a explicar los fallos que aparecieron solo después de la actualización de la base de datos.

No desactive inmediatamente los modos SQL estrictos. Un error en modo estricto puede revelar datos heredados no válidos o código SQL que deben corregirse. Desactivar el modo estricto puede ocultar el problema y dejar datos que posteriormente presenten errores. Primero, capture la instrucción o el error de base de datos exacto del registro de Kopano.

3. Lea el primer error SQL, no solo el fallo final del servicio.

Systemd a menudo solo muestra que kopano-serversalió. La línea útil suele estar más arriba en el registro o en el registro de Kopano. Empiece con:

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

A continuación, clasifique la falla. La siguiente tabla es un mapa práctico de clasificación, no una afirmación de que una misma causa se aplique a todas las instalaciones.

El registro de cambios de Kopano confirma que algunas versiones introdujeron cambios en el esquema que requirieron kopano-dbadmoperaciones específicas. También registra defectos históricos en las actualizaciones de la base de datos, incluyendo fallos relacionados con definiciones de tablas MySQL antiguas y actualizaciones a utf8mb4. Utilice el registro de cambios de Kopano Core para relacionar la acción de mantenimiento con su versión exacta de Kopano.

4. Compare el esquema de Kopano existente con la nueva configuración predeterminada del servidor.

Verifique el esquema tal como existe; la configuración predeterminada del servidor por sí sola no le indica qué antigüedad tienen definidas las tablas de Kopano.

SHOW CREATE DATABASE kopano;
SHOW TABLE STATUS FROM kopano;

Inspeccione la definición de la base de datos Kopano existente y los motores de almacenamiento, manteniendo visible el error de migración original para poder compararlo.

Si la base de datos se creó originalmente con una versión anterior de MySQL, sus tablas podrían conservar conjuntos de caracteres antiguos, aunque los objetos recién creados ahora utilicen utf8mb4 por defecto. MySQL especifica que la actualización de la versión 5.7 a la 8.0 no convierte automáticamente los objetos de la base de datos existentes al nuevo conjunto de caracteres predeterminado. Esta distinción es importante: una migración puede fallar si se crea una nueva columna o índice con valores predeterminados diferentes a los de los objetos vecinos.

Kopano incorporó compatibilidad con utf8mb4 en versiones posteriores de Core y documentó un paso específico de mantenimiento de la base de datos kopano-dbadm usmppara actualizar las bases de datos existentes y que admitan Unicode de 4 bytes. No ejecute ese comando simplemente porque MySQL ahora usa utf8mb4 por defecto; ejecútelo únicamente cuando la documentación de la versión de Kopano instalada o la salida del servidor lo indiquen.

5. Si se actualizó MariaDB, complete primero la actualización del lado de MariaDB.

Si su base de datos es MariaDB en lugar de Oracle MySQL, complete el procedimiento de actualización del servidor de base de datos antes de culpar a Kopano. MariaDB se describe mariadb-upgradecomo la herramienta que actualiza las tablas del sistema y verifica las tablas después de cambios de versión principales. Su documentación recomienda realizar copias de seguridad de todas las bases de datos primero. Consulte la referencia oficial de mariadb-upgrade .

Esto es una rama, no un comando universal. No lo ejecute mariadb-upgradecontra Oracle MySQL. Del mismo modo, no aplique las suposiciones de MySQL 8.0 a un servidor MariaDB solo porque ambos acepten el mysqlprotocolo del cliente.

6. Verifique que la cuenta de la base de datos de Kopano aún tenga los privilegios necesarios.

El manual de administración de Kopano indica que el servidor necesita permisos que incluyen ALTER, CREATE, CREATE ROUTINE, DELETE, DROP, INDEX, INSERT, LOCK TABLES, SELECT, y UPDATEen la base de datos de Kopano. Los parámetros de conexión a la base de datos se configuran a través de la configuración relacionada con MySQL en /etc/kopano/server.cfg. Consulte Configurar componentes de KC .

Tras una migración de versión de MySQL, un administrador podría recrear usuarios, modificar los complementos de autenticación, cambiar el servidor de la base de datos o restaurar los permisos de forma incompleta. Pruebe con el mismo nombre de host y la misma cuenta que utiliza Kopano. Si la autenticación falla antes de que se ejecute cualquier consulta SQL de migración, solucione primero el problema de la cuenta o de los permisos.

7. Reparar únicamente la condición demostrada por el error.

En este punto, debería tener una clase de fallo concreta. Aplique el cambio más pequeño que la explique:

• Actualización parcial del esquema de Kopano: siga las instrucciones de actualización de Kopano específicas kopano-dbadmde la versión instalada. Nunca elimine un marcador de versión ni agregue columnas manualmente solo para que se ejecute la siguiente instrucción.
• Discrepancia en el conjunto de caracteres o la intercalación: identifique primero la tabla y la columna afectadas. Planifique las conversiones con una copia restaurada antes de modificar el entorno de producción, ya que los cambios en el conjunto de caracteres pueden alterar el tamaño de los índices y el comportamiento de las comparaciones.
• Desajuste de la tabla del sistema de MariaDB: complete el procedimiento de actualización de MariaDB documentado y, a continuación, vuelva a intentar Kopano.
• Permisos o autenticación: corrija la cuenta de la base de datos de Kopano y verifique el inicio de sesión desde el host de Kopano.
• Combinación de versiones no compatible: detenga los experimentos de configuración. Restaure el entorno de base de datos anterior a la actualización o cambie a una combinación de Kopano/base de datos compatible con su proveedor o proveedor de paquetes.

El último caso es importante. El manual de administración de Kopano Core, de acceso público, pertenece a una generación anterior del producto, mientras que las versiones actuales de MySQL y MariaDB han seguido evolucionando. Si no encuentra una declaración de soporte para su combinación específica, la falta de documentación no debe interpretarse como compatibilidad.

8. Inicie Kopano y valide más que el estado del proceso.

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 estado de servicio saludable es necesario, pero no suficiente; revise el registro de inicio y luego valide los almacenes de usuarios y el flujo de correo.

Una vez que el servicio esté operativo, realice pruebas con el comportamiento real de la aplicación. Abra al menos un buzón de correo existente, verifique que las carpetas y los mensajes antiguos estén presentes, envíe un mensaje entre dos cuentas locales, envíe un mensaje saliente y confirme que la entrega entrante funcione correctamente. Si utiliza IMAP, ActiveSync, archivado, componentes de varios servidores o almacenamiento externo de archivos adjuntos, pruebe también esas opciones.

¿Cuándo deberías cambiar de enfoque?

Deje de repetir los cambios de esquema cuando se presente alguna de estas condiciones:

• El error SQL cambia después de cada modificación manual, lo que sugiere que el esquema se ha migrado parcialmente.
• La base de datos restaurada previa a la actualización funciona en la versión antigua, pero falla sistemáticamente en la nueva.
• No se puede determinar si la compilación de Kopano es compatible con la versión principal de MySQL o MariaDB instalada.
• Las comprobaciones de tabla informan de corrupción en lugar de una incompatibilidad de esquema normal.
• Una conversión de codificación de caracteres requeriría modificar muchas tablas grandes sin una forma probada de revertir los cambios.

En esos casos, la opción más segura suele ser recrear el entorno de base de datos anterior, restaurar la copia de seguridad que funciona correctamente y planificar una actualización gradual en un clon. Oracle indica que no se admite la degradación de MySQL 8.0 a 5.7 in situ; la alternativa compatible es restaurar una copia de seguridad realizada antes de la actualización. Consulte las notas de la versión de MySQL 8.0 .

Lista de verificación final

• Se conservan la copia de seguridad de la base de datos y la copia de seguridad de la configuración de Kopano.
• Se registra la versión exacta de MySQL o MariaDB.
• Se ha identificado y explicado el primer error real de SQL.
• No se aplicó ninguna solución alternativa general de modo SQL o conjunto de caracteres sin pruebas.
• El mantenimiento del esquema de Kopano requerido debe coincidir con la versión de Kopano instalada.
• kopano-serverSobrevive a un segundo reinicio.
• Los buzones, carpetas y mensajes existentes permanecen intactos.
• Las pruebas de entrega entrante, saliente y local se realizaron con éxito.
• Los componentes opcionales utilizados por su entorno han sido probados.

Un problema de migración de base de datos se resuelve cuando el esquema, el servidor de base de datos y la versión de Kopano coinciden, no cuando simplemente desaparece el mensaje de error. Conserve la evidencia que llevó a la solución, ya que también es la información que necesitará para la próxima actualización de la base de datos o de Kopano.