修復 MySQL 版本升級後 Kopano 資料庫遷移錯誤

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 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

對於大型部署，也應保留/etc/kopano/附件儲存位置，並遵循現有的資料庫備份策略。如果附件儲存在 MySQL 之外，僅憑 SQL 轉儲不足以構成完整的 Kopano 備份。

停止 Kopano 向資料庫寫入資料的服務，並在更改架構或伺服器設定之前驗證是否存在新的資料庫轉儲。

成功訊號：您已擁有可還原到獨立資料庫執行個體的備份，並且知道外部附件的儲存位置。如果出現以下情況，請變更方法：轉儲本身失敗。在嘗試 Kopano 模式遷移之前，請修正資料庫損壞、權限、磁碟空間或連線問題。

2. 記錄確切的資料庫版本和更改後的預設設置

MySQL 的重大升級可能會在不修改現有資料表的情況下變更伺服器預設值。例如，MySQL 8.0 將預設伺服器字元集變更為 `<charset>` utf8mb4，並將預設排序規則變更為 `<collat​​ion> 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 執行此命令。反之，即使 MariaDB 伺服器也接受mysql客戶端協議，也不要將 MySQL 8.0 的假設應用於 MariaDB 伺服器。

6. 確認 Kopano 資料庫帳戶仍擁有所需的權限

Kopano 管理員手冊指出，伺服器需要對 Kopano 資料庫擁有包括ALTER、CREATE、CREATE ROUTINE、DELETE、DROP、INDEX、INSERT、和在內的權限。資料庫連線參數透過 MySQL 相關設定進行設定。請參閱“配置 KC 組件LOCK TABLES” 。SELECTUPDATE/etc/kopano/server.cfg

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 升級也至關重要。