更新後修復 Nextcloud WebGUI「資料庫錯誤」：實用復原指南

如果在更新後立即出現類似「異常：資料庫錯誤」的 Nextcloud WebGUI 訊息，通常表示 Web 應用程式已載入到足以存取資料庫層的程度，但查詢、遷移、模式預期、連接或應用程式特定的資料庫操作失敗。請勿嘗試刪除表、重新安裝 Nextcloud 或將舊程式碼目錄還原到新目錄之上。更安全的做法是：首先確定失敗的 SQL 或遷移，完成支援的更新路徑，僅修復 Nextcloud 能夠修復的問題，然後在重新開啟存取之前驗證資料庫服務和模式。

本文檔遵循 2026 年 10 月發布的 Nextcloud 35 管理文件。以下命令假設是在常見的 Debian/Ubuntu 系統上/var/www/nextcloud以 Web 伺服器使用者身分安裝www-data。請根據您的實際部署情況調整路徑、PHP 二進位、容器指令或 HTTP 使用者。

快速診斷：錯誤通常指向什麼？

你所看到的	可能的分支	首先檢查
替換 Nextcloud 檔案後立即出現錯誤	資料庫/應用程式遷移尚未完成	`occ status`和`occ upgrade`
日誌顯示表或列不存在	遷移不完整、應用程式不符或架構漂移	`occ upgrade`然後是模式檢查
日誌顯示連線被拒絕、檔案不存在或伺服器已斷開連接	資料庫服務、套接字、主機、憑證或版本問題	資料庫服務和`config.php`
錯誤引用了第三方應用程式命名空間或其表	應用程式不相容或遷移失敗	從命令列介面停用該應用程序，然後重試升級。
管理員概覽報告缺少索引/列/主鍵	升級後可選的架構工作仍然存在	運行文件中記錄的`db:add-missing-*`命令

更新後，Nextcloud 瀏覽器頁面顯示異常和資料庫錯誤。 — WebGUI 中的資料庫異常只是一個症狀。真正有用的證據是匹配的日誌條目和更新狀態，而不僅僅是瀏覽器的通用訊息。

1. 在進行資料庫變更之前，請保留目前狀態

如果您仍然保留更新前的備份，請保持原樣。 Nextcloud 明確建議每次更新前都進行備份，其內建的更新程式備份功能可以備份程式碼庫，但不會備份資料庫或資料目錄。如果您沒有最新的資料庫備份，請在嘗試手動變更或還原 SQL 之前，請使用資料庫平台自帶的備份工具建立備份。

請勿將降級作為權宜之計。 Nextcloud 聲明不支援降級，且降級操作可能會導致資料損壞。如果必須回滾，支援的復原模式是全新安裝舊版本，然後還原符合的備份，而不是將舊程式檔案複製到已經開始遷移的資料庫上。請參閱Nextcloud 內建更新程式文件。

2. 在 Nextcloud 日誌中讀取具體的資料庫異常訊息

啟用檔案日誌記錄後，預設日誌檔案nextcloud.log位於配置的資料目錄中。 Nextcloud 的故障排除指南建議檢查該日誌，並在必要時檢查 Web 伺服器和 PHP 日誌。如果錯誤頁面顯示請求 ID，請搜尋該 ID 以定位符合的交易。

sudo -u www-data tail -n 100 /var/www/nextcloud/data/nextcloud.log

不要將日誌簡化為“資料庫錯誤”一詞。請擷取 SQLSTATE 程式碼、異常類別、出錯的表或列，以及堆疊追蹤中提到的應用程式或核心元件。例如，「表不存在」與「連線數過多」或「MySQL 伺服器已斷開連線」是截然不同的故障。 Nextcloud 在其通用故障排除文件中列出了幾種常見的 SQLSTATE 類型的故障。

終端機視窗顯示了 Nextcloud 日誌條目，其中包含資料庫異常和 SQLSTATE 詳細資訊。 — 使用完整的日誌條目來確定故障是缺少架構物件、連線失敗還是應用程式特定的資料庫查詢。

3. 檢查更新是否已完成

內建更新程式會先取代 Nextcloud 程式碼。資料庫和應用程式遷移是另一個獨立的階段。在命令列模式下，更新程式可以occ upgrade自動運作；否則，遷移仍需在之後手動完成。這種差異解釋了為什麼很多情況下，更新程式看起來“已完成”，但普通的 WebGUI 卻傳回資料庫異常。

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

如果在排查故障時需要保護實例，請啟用維護模式。 Nextcloud 將維護模式描述為專為升級而設計的模式，因為它會阻止新的登入並鎖定活動工作階段。

sudo -E -u www-data php occ maintenance:mode --on
sudo -E -u www-data php occ status

終端機顯示 Nextcloud occ 狀態，隨後維護模式已啟用。 — 在執行修復或遷移命令之前，請檢查已安裝的版本和維護狀態，然後在復原過程中封鎖使用者存取。

4. 使用 occ upgrade 完成支援的資料庫和應用程式遷移。

如果程式碼已更新但遷移未完成，請以 HTTP 使用者身分執行升級命令：

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

密切觀察輸出，直到命令報告成功或因特定錯誤而停止。如果失敗，請先解決該先決條件，然後再重複執行命令。常見的阻止因素包括應用程式不相容、PHP/資料庫版本不支援、資料庫服務不可用，或權限問題導致無法執行必要的更新操作。遷移失敗期間，請勿重複刷新 WebGUI。

Nextcloud的升級文件也警告不要跳過主要版本更新。跨主要版本升級時，一次只升級一個主要版本。

終端機視窗顯示 Nextcloud occ upgrade 命令正在運行資料庫和應用程式更新步驟 — 對於不完整的更新，決定性的復原步驟是讓 Nextcloud 運行自己的遷移，並在遇到第一個需要修正的特定錯誤時停止。

5. 遷移問題解決後，執行 Nextcloud 的修復程式。

maintenance:repair執行 Nextcloud 修復步驟，升級期間也會自動運作。在解決中斷更新的問題後，手動執行此命令也是合理的：

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

這比編寫 SQL 語句更安全，因為修復步驟由 Nextcloud 核心和應用程式提供。但它並非萬能的替代方案occ upgrade，也無法修復已損壞的資料庫伺服器或不受支援的資料庫版本。該命令的文檔位於Nextcloud 系統和維護命令中。

終端機顯示 Nextcloud 維護修復指令正在完成修復步驟 — 執行 maintenance:rapair 以修正底層更新失敗；它會執行 Nextcloud 和已安裝應用程式提供的修復邏輯。

6. 驗證資料庫服務、連線設定和支援的版本

如果日誌指向連線問題而非資料庫架構問題，請驗證資料庫服務是否正在執行，以及是否可以從 Nextcloud PHP 環境存取。在典型的 MariaDB 主機上，一個有用的檢查方法是：

sudo systemctl status mariadb

然後檢查資料庫設定config/config.php：資料庫類型、主機、資料庫名稱、使用者以及任何套接字或連接埠設定。 Unix 套接字錯誤可能顯示為“沒有這樣的檔案或目錄”，而遠端資料庫故障可能由路由、DNS、TLS、防火牆規則、憑證或伺服器本身的問題引起。

Nextcloud 重大更新後，版本相容性至關重要。 Nextcloud 35 的官方發行說明指出，不再支援 MariaDB 10.6 和 MySQL 8.0；文件中列出的最低版本要求為 MariaDB 10.11 LTS 和 MySQL 8.4 LTS。在單獨升級資料庫之前，請務必確認您的 Nextcloud 主要版本的特定要求。請參閱“升級到 Nextcloud 35”。

終端機顯示 MariaDB 服務狀態為活動且正在執行 — 當日誌顯示連線失敗時，請先確認資料庫守護程式正在執行，然後再變更 Nextcloud 架構或應用程式設定。

7. 檢查模式偏移，僅新增已記錄的缺失結構

Nextcloud 35 新增了一個功能db:schema:check，用於比較即時資料庫架構與已安裝的核心和應用程式遷移所期望的架構。該功能為唯讀：它僅報告差異，不會更改資料庫。

sudo -E -u www-data php occ db:schema:check
sudo -E -u www-data php occ db:schema:check -v

如果管理員概覽或命令輸出報告缺少可選列、索引或主鍵，請使用已記錄的維護命令：

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

每個命令都支援--dry-run預覽 SQL。這些命令不應取代失敗的核心遷移。如果db:schema:check報告意外物件或列屬性差異，請在進行任何變更之前查看結果；Nextcloud 指出，某些資料庫範圍的預設值不符合預期模式模型。權威的命令參考是Nextcloud DAV 和資料庫命令。

終端機顯示 Nextcloud 資料庫架構檢查並新增缺少的列、索引和主鍵命令 — 首先使用模式檢查，然後僅當輸出或管理概覽顯示需要時才套用 Nextcloud 支援的缺失模式指令。

8. 在重新開啟 WebGUI 之前，請先排除第三方應用程式故障。

如果在堆疊追蹤中指向一個未發布的應用程序，則其遷移可能與新伺服器版本不相容。 Nextcloud 的故障排除指南建議在升級和故障排除期間停用第三方/未發布的應用程式。使用已安裝版本中提供的應用程式命令，從命令列停用特定可疑應用程序，重新運行命令occ upgrade，並在確認版本相容後再重新啟用該應用程式。

當核心表看起來正常，但異常資訊指向供應商命名空間或某個應用程式的表時，這個分支就顯得特別重要。手動刪除該應用程式的表風險很高，因為這可能會破壞應用程式仍需要的資料。

9. 登出維護模式並驗證登入頁面以外的內容

修復/架構檢查完成後occ upgrade，不再顯示阻塞問題，資料庫服務穩定，停用維護模式：

sudo -E -u www-data php occ maintenance:mode --off

然後分層驗證實例：載入登入頁面、登入、開啟「檔案」資料夾、瀏覽幾個資料夾、測試一個檔案的上傳/下載、檢查管理設定中的警告，並查看最新nextcloud.log條目。同時確認定時任務/後台任務運作正常。僅恢復主頁並不能證明應用程式遷移、檔案操作和後台任務運作良好。

Nextcloud 檔案介面在瀏覽器中打開，並顯示「文件」、「照片」和「範本」資料夾。 — 資料庫和遷移檢查通過後，重新開啟 WebGUI 並驗證檔案瀏覽和基本操作是否正常，然後宣布更新已復原。

恢復檢查清單

保留更新前的備份，避免進行不支援的降級作業。
讀取完整的資料庫異常訊息nextcloud.log，包括 SQLSTATE 和追蹤中指定的元件。
維修期間，請檢查occ status並將實例置於維護模式。
運行occ upgrade以完成受支援的核心和應用程式遷移。
先解決第一個具體障礙，而不是盲目地修改資料庫表。
maintenance:repair待根本故障修復後再運行。
檢查資料庫服務運作狀況、連線設定和版本相容性。
db:schema:check在 Nextcloud 35 上使用，並db:add-missing-*酌情使用文件中記錄的命令。
如果追蹤資訊明確指向某個第三方應用程序，請停用該應用程序，然後重試升級。
只有在 CLI 檢查通過後才能關閉維護模式，然後測試檔案、傳輸、管理員警告、日誌和背景作業。

何時應該修復而不是修理

當資料庫本身損壞、遷移導致資料部分變更且無法安全撤銷，或所需表/資料在 Nextcloud 外部被刪除時，請使用已知良好且內部一致的備份進行還原。資料庫、配置、資料目錄和程式碼版本必須屬於相容的復原點。如果您已付費購買 Nextcloud 支援或部署了業務關鍵型系統，請在進行破壞性 SQL 操作之前停止，並提供完整的日誌條目、確切的來源 Nextcloud 版本和目標 Nextcloud 版本、資料庫類型/版本、PHP 版本以及相關occ命令的輸出結果，以便及時回報支援。

核心原則很簡單：更新後出現的「資料庫錯誤」並非猜測 SQL 程式碼的理由。應該讓日誌識別故障，完成occ upgrade預期的遷移，使用 Nextcloud 自帶的修復和架構工具，並在重新開啟實例之前驗證資料庫平台。