使用 OCC 安全清除卡住的 Nextcloud 維護模式

如果在更新或維護任務後 Nextcloud 仍然顯示“維護模式”，請先檢查資料庫升級是否已完成。如果occ status顯示“已完成” needsDbUpgrade: false，請occ maintenance:mode --off在正確的 Nextcloud 安裝中以 Web 伺服器使用者身分執行命令；如果顯示“true已完成”，請occ upgrade在重新開啟網站之前完成升級。

停用該標誌可以恢復登錄，但無法修復升級失敗的問題。目標是在確認維護標誌和升級狀態均已驗證的情況下，使實例重新上線。

1. 在變更實例狀態之前，請先檢查實例。

連接到提供受影響的 Nextcloud URL 的主機或容器。對於手動安裝的 Linux 系統，請切換到 Nextcloud 目錄（通常為 `/etc/Nextcloud` /var/www/nextcloud），並以 HTTP 使用者身分檢查狀態：

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

尋找 `maintenance`maintenance和 `maintenance`參數。通常情況下，當 `maintenance` 為 `false` 時，needsDbUpgrade可以安全地停用維護模式。如果 `maintenance` 已為 `false`，則瀏覽器可能正在顯示過時的頁面或連接到不同的後端。如果 `maintenance`為 `true`，則暫時不要關閉維護模式。maintenance: trueneedsDbUpgrade: falseneedsDbUpgrade

Nextcloud 要求 OCC 以 HTTP 使用者身分執行，以確保檔案所有權的一致性。在 Debian 或 Ubuntu 系統中，該使用者通常是 `/usr/local` www-data；其他發行版可能使用`/usr/local` apache、http`/usr/local` 或 `/ usr/local` wwwrun。在命令中替換使用者之前，請檢查您安裝的用戶端服務帳戶。目前的Nextcloud OCC 文件列出了不同使用者之間的差異以及狀態命令。

2. 使用 OCC 停用維護模式

對於歸檔檔案或軟體包安裝，請從包含正確腳本的目錄中執行命令occ：

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

此命令應報告維護模式已停用。此--off選項會變更維護狀態；它不會執行遷移、修復權限或撤銷中斷的檔案替換。

使用與您的安裝相符的包裝器。對於官方的 Nextcloud Docker 映像，專案文件docker exec中提供了 Docker Compose 範例。請將範例中的容器或服務名稱替換為您自己的名稱：

# Docker Compose; "app" is an example service name
docker compose exec --user www-data app php occ maintenance:mode --off

# Docker; replace CONTAINER_ID with the Nextcloud container
docker exec -it --user www-data CONTAINER_ID php occ maintenance:mode --off

對於 Nextcloud Snap，請使用其主機端的 OCC 包裝器，而不是進入 snap 的內部目錄：

sudo nextcloud.occ maintenance:mode --off

snap 專案指出，/snap/bin/nextcloud.occ如果目錄不在 shell 的 PATH 環境變數中，則可能需要執行此操作。請參閱其Snap 維護模式說明。 Nextcloud 官方Docker 映像的 README 文件記錄了容器指令模式。

3. 如果還有待處理的升級，請先完成它。

當狀態報告needsDbUpgrade: true顯示 Nextcloud 程式碼和資料庫遷移不同步時，通常表示更新程式取代了程式碼，但遷移階段尚未完成。在這種情況下，可能只有部分 OCC 命令可用，且維護模式可能被有意地設定為開啟狀態，以防止使用者在升級期間存取系統。

請使用與您的安裝類型相符的升級路徑，並在繼續操作前查看更新程式的錯誤訊息。對於標準的基於歸檔檔案的安裝，在確認所需的 Nextcloud 程式碼版本存在，並且如果您還沒有資料庫和檔案/配置備份，請先進行備份，然後執行以下命令：

sudo -E -u www-data php occ upgrade

讓命令執行完畢並解決所有報告的故障。請勿重複切換維護模式以繞過遷移錯誤。 Nextcloud 的升級文件解釋說，資料庫遷移是在伺服器程式碼替換之後進行的，並建議在升級前進行全新備份。 Docker、Snap 和託管軟體包可能有各自的升級流程；如果與基於歸檔的範例不同，請使用相應的說明。

升級成功完成後，狀態不再顯示待處理的資料庫升級，請執行maintenance:mode --off上述對應的指令。避免編輯config.php或使用直接資料庫更新作為捷徑。如果 OCC 無法寫入設置，請檢查是否選擇了正確的安裝用戶和 HTTP 用戶，並在更改權限之前檢查是否存在唯讀設定策略或檔案系統權限錯誤。

4. 驗證旗幟和即時站點

使用相同的安裝路徑、容器和使用者再次執行狀態檢查：

sudo -E -u www-data php occ status

確認這兩個maintenance: false參數needsDbUpgrade: false。在 Docker 或 Snap 中，透過用於停用該標誌的相同包裝器重複檢查。 Nextcloud 狀態指令會記錄這些欄位；其機器可讀格式為occ status --output=json_pretty。

然後，在新的瀏覽器標籤頁中重新載入網站，並測試正常的登入和檔案清單功能。 Nextcloud 指出，在維護模式開啟前已登入的使用者可能需要在伺服器恢復線上後重新整理瀏覽器。如果 OCC 報告維護狀態為 false，但網站仍顯示維護頁面，請檢查主機名稱或負載平衡器是否路由至您變更的相同執行個體；如果存在多個容器或節點，則可能還有其他後端仍在維護中。

因此，成功的修復不僅僅是命令回應顯示「已停用」：OCC 狀態必須顯示兩個標誌都已清除，並且預期的公共 URL 必須能夠存取正常工作的實例。如果升級標誌仍然為真或遷移命令失敗，請先阻止使用者訪問，並在重新開啟 Nextcloud 之前解決該升級錯誤。