Исправление ошибок миграции базы данных Kopano после обновления версии MySQL.

Ошибка миграции базы данных Kopano, возникающая сразу после обновления версии MySQL или MariaDB, обычно означает, что приложение и база данных больше не согласуются в отношении чего-то, что раньше было неявным: состояния схемы, настроек сервера по умолчанию, поведения SQL, аутентификации или самого пути обновления. Полезная цель состоит не просто в том, чтобы запустить систему kopano-serverодин раз. Цель состоит в достижении состояния, когда схема согласована, Kopano запускается без ошибок обновления базы данных, пользователи могут открывать хранилища, а поток почты сохраняется после перезапуска.

В этом руководстве основное внимание уделяется доказательствам. Каждый этап включает в себя сигнал об успехе и точку, в которой следует прекратить попытки применения одного и того же решения и изменить направление. Публичная документация администратора Kopano старше текущих версий MySQL и MariaDB, поэтому не следует предполагать, что каждая современная версия базы данных поддерживается каждой исторической сборкой Kopano. Используйте точную версию пакета Kopano, поставщика базы данных и ошибку сервера в качестве решающего доказательства.

Начните с того результата, который вам нужен.

Прежде чем менять конфигурацию, определите, что будет означать «исправлено». Здоровое восстановление обычно сопровождается всеми этими признаками:

• kopano-serverЗапускается и продолжает работать после перезапуска службы.
• В логах Kopano больше не сообщается об обновлении схемы базы данных или сбое выполнения SQL-запроса.
• База данных доступна для чтения и записи настроенной учетной записью Kopano.
• Видны существующие магазины и пользователи, а не новая, пустая схема.
• Отправка и доставка почты возобновляются в обычном режиме.
• Повторная перезагрузка дает тот же, исправный результат.

Если вам удалось выполнить только первый пункт, продолжайте тестирование. Временный запуск после внесения изменений sql_mode, например, не доказывает корректность базовой схемы.

1. Остановите запись в Kopano и создайте восстанавливаемую резервную копию базы данных.

В документации по обновлению Kopano рекомендуется создать резервные копии базы данных и файлов конфигурации, а также остановить службы, использующие базу данных, перед началом работ по обновлению. В документации особо отмечается необходимость остановки kopano-spoolerи kopano-server, а также необязательных запущенных компонентов. См. документацию по обновлению ядра Kopano .

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

Для больших установок также сохраните данные /etc/kopano/, запишите место хранения вложений и следуйте существующей политике резервного копирования базы данных. Если вложения хранятся вне MySQL, дамп SQL сам по себе не является полной резервной копией Kopano.

Остановите службы Kopano, которые записывают данные в базу данных, и убедитесь, что существует актуальный дамп, прежде чем изменять схему или настройки сервера.

Сигнал успеха: у вас есть резервная копия, которую можно восстановить в отдельный экземпляр базы данных, и вы знаете, где хранятся внешние вложения. Измените подход, если: сам дамп не удался. Устраните повреждения базы данных, проблемы с правами доступа, дисковым пространством или подключением, прежде чем пытаться выполнить миграцию схемы Kopano.

2. Запишите точную версию базы данных и измененные значения по умолчанию.

Крупное обновление MySQL может изменить настройки сервера по умолчанию без изменения существующих таблиц. Например, в MySQL 8.0 кодировка сервера по умолчанию была изменена на , utf8mb4а сортировка по умолчанию — на utf8mb4_0900_ai_ci. Также были изменены другие параметры по умолчанию, а также удалены или объявлены устаревшими старые настройки. Oracle описывает эти различия в документе « Изменения в MySQL 8.0» .

Получайте фактическое состояние сервера, а не полагайтесь на предположения о том, что произошло после обновления пакета:

mysql -u root -p

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

Запишите версию базы данных и параметры по умолчанию, которые теперь видит Kopano; эти значения помогают объяснить ошибки, которые появились только после обновления базы данных.

Не следует сразу отключать строгий режим SQL. Ошибка в строгом режиме может выявить некорректные устаревшие данные или SQL-запросы, которые необходимо исправить. Отключение строгого режима может скрыть симптом, но при этом оставить данные, которые впоследствии могут дать сбой. Сначала зафиксируйте точное сообщение об ошибке или ошибку базы данных из журнала Kopano.

3. Прочитайте первое сообщение об ошибке SQL, а не только окончательное сообщение о сбое сервиса.

Systemd часто показывает только сообщение kopano-serverо завершении работы. Полезная строка обычно находится раньше в журнале или логе Kopano. Начните с:

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

Затем классифицируйте причину неисправности. Приведенная ниже таблица представляет собой практическую схему сортировки не является утверждением о том, что одна причина применима ко всем установкам.

В журнале изменений Kopano подтверждается, что в некоторых релизах были внесены изменения в схему, требующие выполнения определенных kopano-dbadmопераций. В нем также зафиксированы исторические дефекты обновления базы данных, включая сбои, связанные со старыми определениями таблиц MySQL и обновлениями до utf8mb4. Используйте журнал изменений ядра Kopano, чтобы сопоставить действия по техническому обслуживанию с вашей конкретной версией Kopano.

4. Сравните существующую схему Kopano с новыми настройками сервера по умолчанию.

Проверьте существующую схему; одних только настроек сервера по умолчанию недостаточно, чтобы определить, насколько старые таблицы Kopano были определены.

SHOW CREATE DATABASE kopano;
SHOW TABLE STATUS FROM kopano;

Проверьте существующие определения базы данных Kopano и механизмы хранения, сохранив при этом видимой исходную ошибку миграции для сравнения.

Если база данных изначально была создана в более старой версии MySQL, её таблицы могут сохранять старые кодировки символов, даже несмотря на то, что вновь созданные объекты теперь по умолчанию используют utf8mb4. MySQL прямо указывает, что обновление с версии 5.7 до 8.0 не приводит к автоматическому преобразованию существующих объектов базы данных в новую кодировку по умолчанию. Это различие имеет значение: миграция может завершиться неудачей, если новый столбец или индекс создан с кодировкой по умолчанию, отличной от кодировки соседних объектов.

В более поздних версиях ядра Kopano была добавлена ​​поддержка utf8mb4, а также описан специальный шаг по обслуживанию базы данных kopano-dbadm usmpдля обновления существующих баз данных с поддержкой 4-байтового Unicode. Не запускайте эту команду только потому, что MySQL теперь по умолчанию использует utf8mb4; запускайте её только тогда, когда этого требует документация вашей установленной версии Kopano или вывод сервера.

5. Если MariaDB была обновлена, сначала выполните обновление на стороне MariaDB.

Если в качестве бэкенда используется MariaDB, а не Oracle MySQL, завершите процедуру обновления сервера базы данных, прежде чем обвинять Kopano. В документации MariaDB указано mariadb-upgrade, что это инструмент для обновления системных таблиц и проверки таблиц после изменения основной версии. Рекомендуется сначала создать резервные копии всех баз данных. См. официальный справочник по mariadb-upgrade .

Это отдельная ветка, а не универсальная команда. Не используйте mariadb-upgradeеё с Oracle MySQL. И наоборот, не применяйте предположения MySQL 8.0 к серверу MariaDB только потому, что оба поддерживают mysqlклиентский протокол.

6. Убедитесь, что учетная запись базы данных Kopano по-прежнему обладает необходимыми привилегиями.

В руководстве администратора Kopano указано, что серверу необходимы права доступа, включая ALTER, CREATE, CREATE ROUTINE, DELETE, DROP, INDEX, INSERT, LOCK TABLES, SELECTи UPDATEк базе данных Kopano. Параметры подключения к базе данных настраиваются через параметры, связанные с MySQL, в файле /etc/kopano/server.cfg. См. раздел «Настройка компонентов KC» .

После миграции версии MySQL администратор может заново создать пользователей, изменить плагины аутентификации, переместить хост базы данных или восстановить права доступа не полностью. Проверьте использование того же имени хоста и учетной записи, что и в Kopano. Если аутентификация не удается до выполнения каких-либо SQL-запросов миграции, сначала устраните проблему с учетной записью или правами доступа.

7. Устраняйте только ту неисправность, которая была выявлена ​​в результате ошибки.

На этом этапе у вас должен быть один конкретный класс ошибок. Внесите минимальное изменение, которое его объясняет:

• Частичное обновление схемы Kopano: следуйте инструкциям по обновлению Kopano, kopano-dbadmуказанным для конкретной версии. Никогда не удаляйте маркер версии и не добавляйте столбцы вручную только для того, чтобы выполнить следующее выражение.
• Несоответствие кодировки или параметров сопоставления: сначала определите затронутую таблицу и столбец. Планируйте преобразования на основе восстановленной копии, прежде чем вносить изменения в рабочую среду, поскольку изменения кодировки могут повлиять на размеры индексов и поведение при сравнении.
• Несоответствие системных таблиц MariaDB: выполните описанную процедуру обновления MariaDB, затем повторите попытку обновления Kopano.
• Права доступа или аутентификация: исправьте учетную запись в базе данных Kopano и подтвердите вход в систему с хоста Kopano.
• Неподдерживаемая комбинация версий: прекратите эксперименты с конфигурацией. Восстановите среду базы данных, существовавшую до обновления, или перейдите на комбинацию Kopano/база данных, поддерживаемую вашим поставщиком или источником пакетов.

Последний случай важен. Общедоступное руководство администратора Kopano Core относится к более старой версии продукта, в то время как текущие версии MySQL и MariaDB продолжают меняться. Если вы не можете найти информацию о поддержке именно вашей пары, отсутствие документации не следует интерпретировать как несовместимость.

8. Запустите Kopano и проверьте не только состояние процесса, но и другие параметры.

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

Наличие работоспособного состояния службы необходимо, но недостаточно; просмотрите журнал запуска, а затем проверьте хранилища пользователей и поток почты.

После того, как служба заработает, протестируйте её в реальных условиях. Откройте хотя бы один существующий почтовый ящик, убедитесь в наличии старых папок и сообщений, отправьте сообщение между двумя локальными учетными записями, отправьте одно исходящее сообщение и подтвердите работоспособность входящей доставки. Если вы используете IMAP, ActiveSync, архивирование, многосерверные компоненты или внешнее хранилище вложений, проверьте и эти пути.

Когда следует изменить подход?

Прекратите повторять изменения схемы при появлении любого из следующих условий:

• Ошибка SQL меняется после каждого ручного изменения, что указывает на частичную миграцию схемы.
• Восстановленная до обновления база данных работает со старой версией, но постоянно дает сбои в новой.
• Невозможно установить, что ваша сборка Kopano поддерживает установленные основные версии MySQL или MariaDB.
• Проверка таблиц выявляет повреждения, а не обычную несовместимость схем.
• Для преобразования кодировки символов потребуется изменить множество больших таблиц без проверенного механизма отката.

В таких случаях более безопасным вариантом часто является воссоздание предыдущей среды базы данных, восстановление заведомо исправной резервной копии и планирование поэтапного обновления в клонированном хранилище. Oracle отмечает, что понижение версии MySQL 8.0 до 5.7 не поддерживается на месте; поддерживаемой альтернативой является восстановление резервной копии, сделанной до обновления. См. примечания к выпуску MySQL 8.0 .

Контрольный список для окончательной проверки

• Резервная копия базы данных и резервная копия конфигурации Kopano сохраняются.
• Точная версия MySQL или MariaDB указана.
• Выявлена ​​и объяснена первая реальная ошибка SQL.
• Без подтверждающих доказательств не применялось никаких универсальных обходных путей, связанных с режимом SQL или кодировкой символов.
• Необходимые изменения в схеме Kopano соответствуют установленной версии Kopano.
• kopano-serverВыдерживает вторую перезагрузку.
• Существующие почтовые ящики, папки и сообщения остались нетронутыми.
• Тесты входящей, исходящей и локальной доставки прошли успешно.
• Дополнительные компоненты, используемые в вашей среде, были протестированы.

Проблема миграции базы данных решается, когда схема, сервер базы данных и версия Kopano снова совпадают, а не когда сообщение об ошибке просто исчезает. Сохраните доказательства, которые привели к исправлению, поскольку эта информация также понадобится вам для следующего обновления базы данных или Kopano.