Nextcloud 資料庫更新後出現錯誤：我該先檢查什麼？

如果 Nextcloud 在更新後出現「資料庫錯誤」異常，請nextcloud.log在變更任何表格之前檢查底層資料庫錯誤。首先恢復資料庫連線；如果更新過程中途停止，請先完成更新，occ upgrade然後僅在日誌顯示需要時才使用文件中記錄的修復命令。

找出實際故障

瀏覽器訊息只是症狀，並非診斷結果。 Nextcloud 可能無法連接到 MySQL/MariaDB 或 PostgreSQL，資料庫帳戶可能已失效，或者應用程式程式碼和架構可能處於不同的升級階段。 Nextcloud官方故障排除指南建議將失敗的請求 ID 與伺服器日誌進行比對。

1. 記錄時間、完整的瀏覽器錯誤訊息以及任何顯示的請求 ID。請勿在未刪除敏感資訊和個人資訊的情況下發布私人日誌條目。
2. 在 . 中找到已配置的資料目錄config/config.php。預設日誌檔案位於data/nextcloud.log，但自訂部署可能會將日誌記錄到其他位置。
3. 在標準的 Linux 系統上，檢查最近的條目，然後檢查資料庫服務日誌。將以下路徑替換為您實際的 Nextcloud 路徑：

sudo tail -n 100 /var/www/nextcloud/data/nextcloud.log
sudo journalctl -u mariadb --since '30 minutes ago'

第二條指令僅適用於在 systemd 下執行 MariaDB 的主機；其他部署，請使用 PostgreSQL 服務或容器記錄。請尋找異常SQLSTATE程式碼和第一個與資料庫相關的錯誤原因，而不是依賴堆疊追蹤的最後一行。

前三個範例已在 Nextcloud 的常見錯誤文件中說明。缺少表格資訊並不意味著允許手動建立表格：請先確定特定的遷移失敗原因。

在應用修復程式之前保護實例。

在重試遷移之前，請務必保留可復原的資料庫備份，其中包含 Nextcloud 的設定和資料。官方備份流程還包括自訂應用程式和主題（如有）。請確認備份的時間點一致；僅包含程式碼的備份無法還原部分變更的資料庫。

• 在復原視窗期間，盡可能暫停同步和背景作業，尤其是在涉及資料庫寫入或升級時。
• 記錄新舊 Nextcloud 版本、資料庫引擎/版本、PHP 版本以及更新方法。
• 不要刪除資料庫表、匯入空白架構、執行論壇上的隨機 SQL 語句，或重複僅還原多部分備份中的一個元件。

以下命令假設安裝在常見的 Debian/Ubuntu系統中/var/www/nextcloud，www-data其 Web 伺服器帳戶為 `<username>`。請occ以對應的 HTTP 使用者身分運作；軟體包、Docker、Snap、AIO 和託管安裝的路徑和執行方法各不相同。 occ命令參考文件解釋了這些要求。

遷移前恢復資料庫連接

檢查資料庫服務和 Nextcloud 連線設置

如果日誌顯示連線被拒絕、套接字不可達或伺服器無法使用，請先驗證現有資料庫服務是否正在執行。這些是主機層級的檢查方法，並非需要隨意執行的清單：

sudo systemctl status mariadb
sudo systemctl status postgresql

對於獨立的資料庫伺服器，還需檢查 DNS、防火牆規則、所選連接埠以及 Nextcloud 應用主機或容器的網路可及性。檢查config/config.php是否存在`<hostname> dbtype`、dbhost` <port> dbname` 和 `<connection>` 等設定項目dbuser。配置參數參考文件解釋了主機名稱、連接埠和 Unix 套接字語法。切勿將設定資訊貼dbpassword到公開工單或 shell 指令中，以免暴露歷史記錄。

如果在部署期間資料庫密碼輪替或憑證發生更改，請使用金鑰管理工作流程修正此不匹配。如果伺服器報告連線數過多，請在考慮容量變更之前檢查活動連線數和連線數累積的原因。索引指令無法解決連線中斷問題。

更新後請檢查運行時相容性。

同時升級 PHP 或資料庫伺服器可能會導致先前運作正常的安裝故障。請務必將目標Nextcloud 版本與其官方系統需求和發行說明進行比較，而不要想當然地認為所有已安裝的驅動程式和伺服器版本都仍然受支援。根據查閱的 Nextcloud 35 文檔，PHP 版本支援 8.3 至 8.5；支援的資料庫版本在文件中另有說明。更早的版本有不同的限制。

此外，請確認所選引擎所需的 PHP 資料庫驅動程式已在命令列和 Web PHP 環境中啟用。架構遷移後，切勿盲目降級資料庫伺服器：僅可從相容且一致的備份方案中進行還原。

完成或修復中斷的 Nextcloud 升級

資料庫可存取且備份安全後，切換至 Nextcloud 安裝目錄並檢查其狀態：

cd /var/www/nextcloud
sudo -E -u www-data php occ status

如果 Nextcloud 報告升級正在進行中或尚未完成，請按照已安裝的來源版本和目標版本的支援升級路徑進行操作。對於傳統的手動安裝，請運行：

sudo -E -u www-data php occ upgrade

請勿中斷指令或執行並發升級程序。請閱讀其輸出：成功遷移與資料庫連線異常有所不同。 Nextcloud 的手動升級文件明確建議occ upgrade在基於 Web 的升級進程停滯以及maintenance:repair升級路徑需要修復時採取以下措施：

sudo -E -u www-data php occ maintenance:repair

在分析故障原因後使用maintenance:repair此方法；它不能取代修復錯誤的憑證、停止運行的資料庫或真正不相容的執行環境。如果occ upgrade特定 SQL 遷移失敗，請儲存確切的異常訊息，並尋找特定版本的修復程式或還原完整的匹配備份，而不是嘗試手動使用 DDL。

僅在升級成功後處理架構警告

某些遷移操作會被有意延遲。在運行中的實例上，管理概覽可能會詢問是否需要新增可選的列、索引或主鍵。如果該版本支持，這些命令可以提供預運行預覽：

sudo -E -u www-data php occ db:add-missing-indices --dry-run
sudo -E -u www-data php occ db:add-missing-columns --dry-run
sudo -E -u www-data php occ db:add-missing-primary-keys --dry-run

--dry-run只有當已記錄的問題或管理檢查需要且建議的變更已審核時，才執行相應的命令。這些維護操作在大資料庫上可能需要一些時間。 Nextcloud 35 也提供了相關文件db:schema:check；請勿假定舊版本分支中存在此文件。有關特定版本的行為，請參閱資料庫指令參考。

驗證恢復情況並重新開放存取權限

1. 重複上述步驟sudo -E -u www-data php occ status。確認已安裝版本與預期版本相符，無需升級，且未產生新的致命 SQL 異常。
2. 如果維護模式仍然開啟且升級已成功完成，請使用下列命令將其停用sudo -E -u www-data php occ maintenance:mode --off。
3. 開啟 Web 圖形使用者介面，登錄，列出文件，並執行一次小規模的授權上傳和下載操作。nextcloud.log在這些檢查過程中，注意觀察是否有新的資料庫異常。
4. 復原排程任務和用戶端同步，然後檢查管理設定中是否有任何剩餘的資料庫警告。

如果再次出現相同的資料庫異常，請停止重複遷移，並收集請求 ID、SQLSTATE 文字、資料庫伺服器日誌、版本對以及失敗的occ輸出。這些資訊有助於確定剩餘問題是連接性問題、軟體不相容問題還是特定遷移失敗問題。僅憑登入成功並不能證明所有後台任務和資料庫查詢都能正常運作。