修復 Nextcloud “資料庫缺少某些索引”警告

您開啟 Nextcloud 的管理概覽，看到「資料庫缺少一些索引」的提示。此警告可能在升級後出現，因為 Nextcloud 會隨著時間的推移為現有資料表新增索引，但對於大型資料庫，它並非總是自動建立索引。缺少索引會導致某些資料庫查詢速度變慢。支援的修復方法是使用內建occ db:add-missing-indices命令。

在變更架構之前，請確認您執行的命令適用於正確的 Nextcloud 安裝，備份資料庫，並使用 Web 伺服器的作業系統使用者。在支援的版本中，請使用 `--preview` 指令預覽建議的 SQL 語句--dry-run。然後運行修復操作並再次檢查管理概覽。

警告的含義

資料庫索引是一種結構，它可以幫助資料庫在不掃描整個表的情況下找到行。 Nextcloud 及其應用程式會為其使用的資料表和欄位定義索引。當較新的 Nextcloud 版本或應用程式版本引入現有安裝尚不存在的索引時，管理頁面會報告此不符情況。這是一個架構維護警告；它本身並不意味著資料庫已損壞或使用者檔案遺失。

Nextcloud 的管理手冊指出，索引可以隨著時間的推移而添加，包括為了提高效能，並指導管理員執行相關命令occ db:add-missing-indices。新增索引可能需要一些時間，尤其是在處理大型資料表時，而且資料庫負載或鎖定行為會因資料庫引擎和工作負載而異。如果您的實例正處於繁忙狀態，建議在空閒時段進行變更。

在運行修復程序之前

確認安裝路徑和版本。從包含目標安裝腳本的目錄執行命令occ，或提供其完整路徑。
備份資料庫。使用您常用的 MariaDB/MySQL、PostgreSQL 或 SQLite 備份流程。確認備份已完成，並確保您知道如何還原備份。
找到 HTTP 用戶。使用執行 Nextcloud Web 伺服器的帳戶。常見範例包括www-dataDebian 或 Ubuntu、apacheFedora 或 CentOS、httpArch 和wwwrunopenSUSE。您的部署可能有所不同。
檢查命令選項。 Nextcloud 35 的穩定版管理手冊中有相關文件--dry-run。如果您的已安裝版本無法識別該選項，請查閱該版本的occ db:add-missing-indices --help輸出並跳過預覽，而不是想當然地認為該選項存在。

官方備份指南列出了完整備份中應保留的資料庫、設定、資料目錄和其他安裝元件。對於此架構操作，至少應使用適合您資料庫的備份步驟進行經過測試的資料庫備份。

步驟 1：在 Nextcloud 安裝目錄中開啟一個 shell。

對於傳統的 Linux 安裝，請透過 SSH 連接到伺服器並切換到 Nextcloud 目錄。常見的 Ubuntu 路徑是 `/usr/local/share/Nextcloud` /var/www/nextcloud，但請使用您伺服器上的路徑。

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

確認狀態輸出顯示的是預期的已安裝實例。如果您使用的 Web 伺服器 PHP 二進位與 shell 預設的 PHP 不同php，請使用相同的相容 PHP 版本occ。occ以 HTTP 使用者身分執行有助於保留預期的檔案所有權和權限。

步驟 2：預覽索引更改

如果您的已安裝版本支持，請先運行試運行：

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

試運行會預覽 SQL 語句，但不會實際執行它們。請閱讀輸出結果，確認其與您要修復的缺失索引相關。如果輸出結果中出現了您不認識的表或索引，請記錄其確切名稱，並檢查相關應用程式是否已安裝且為最新版本。請勿將預覽的 SQL 語句貼到資料庫控制台中作為捷徑。

步驟 3：新增缺少的索引

當預覽正常進行且備份準備就緒時，執行文件中記錄的修復命令：

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

此指令會檢查資料庫表，並建立架構中定義但目前安裝中缺少的索引。請耐心等待其完成。對於大型資料庫，這可能需要一些時間。在架構變更期間，請勿中斷此操作。 Nextcloud 的文檔指出，此命令可以在實例保持在線狀態時運行；維護模式並非此特定修復的先決條件。如果需要維護窗口，請遵循您自己的變更控制流程。

Docker 和其他安裝類型

在容器化部署中，請occ在 Nextcloud 應用程式容器內運行，而不是在資料庫容器內運行。容器和服務名稱可能有所不同，因此請檢查您的部署並替換為正確的名稱。例如，對於名為 `<container_name>` 的 Docker 容器nextcloud，其模式為：

docker exec --user www-data nextcloud php occ db:add-missing-indices

對於 Docker Compose，對應的模式是 `<container_name> docker compose exec -u www-data <nextcloud-service> php occ db:add-missing-indices`。某些打包部署會使用專用指令或不同的容器使用者；請依照該軟體包的具體說明進行操作。未經驗證，請勿從他人的配置複製容器名稱。

如果命令失敗或警告仍然存在

權限被拒絕：請驗證 HTTP 使用者和安裝路徑。除非您的部署文件明確要求使用特權包裝器，否則請勿以 root 使用者身分執行命令來解決此問題；PHP 進程通常應以 Web 伺服器使用者身分執行。
資料庫連線或 PHP 錯誤：檢查 Nextcloud 日誌、資料庫服務運作狀況、配置的 PHP 版本、指令輸出。在重新執行 schema 指令之前，請解決底層連線或執行時間問題。
重複鍵或唯一索引錯誤：請停止操作並保留完整的錯誤文字。這可能表示存在衝突行，導致無法建立唯一索引。請確定受影響的應用程式和表，確認應用程式和 Nextcloud 的版本，並諮詢應用程式的維護人員或熟悉該資料庫的管理員。切勿在未進行資料相關的診斷和備份的情況下刪除行或索引。
「命令未找到」或「不支援的選項」：請確認您使用的是正確的 Nextcloud 安裝，並以 HTTP 使用者身分進行檢查。舊版本可能無法顯示所有新選項php occ list。php occ help db:add-missing-indices
警告仍然存在：命令成功退出後，請重新整理管理概覽。請仔細閱讀警告中顯示的索引和表名。可能存在多個缺少的索引、應用程式更新後新增的索引、資料庫操作失敗，或此命令未能解決的架構不符問題。

不要將缺少的索引與缺少的列或主鍵混淆。 Nextcloud 文件中提供了針對這些架構變更的單獨命令，例如 `git checkout index` 和 `git checkout column` db:add-missing-columns。db:add-missing-primary-keys僅當管理員警告或特定版本的文件要求時才執行不同的修復。

驗證結果

等待直至db:add-missing-indices退出並報告完成，例如Done.
重新載入管理概覽並確認缺少索引的警告已消失。
如果問題仍然存在，請將其確切的表名和索引名與命令輸出進行比較，而不是盲目地重新運行。
檢查 Nextcloud 日誌和資料庫運作狀況是否有新錯誤，然後確認正常檔案存取和使用受影響表的應用程式仍然可以正常運作。
保留備份，直到實例正常運作且您的保留策略允許刪除為止。

有關目前指令語法，請參閱Nextcloud 資料庫和索引指令參考。有關使用者和 PHP 要求，請參閱使用 occ 指令和Nextcloud 備份指南。這些穩定頁面在 2026 年 10 月 6 日檢查時，將目前手冊標識為 Nextcloud Server 35；路徑、選項和打包說明在其他版本或部署類型中可能有所不同。