使用 OCC 修復 Nextcloud 維護模式卡住的問題

您完成了 Nextcloud 更新，但所有人仍然看到維護頁面。或升級中斷，網站始終無法恢復線上。禁用維護模式的 OCC 命令雖然很短，但在檢查升級狀態之前執行該命令可能會暴露未完成的安裝。首先，請確認您正在管理哪個 Nextcloud 實例，以及是否仍需要資料庫升級。

範例：假設一個小型辦公室在 Ubuntu 系統上執行 Nextcloud。計劃更新在部署新程式碼檔案後中斷，網頁仍然顯示伺服器處於維護模式。此範例僅為假設，旨在示範如何應用以下檢查，並非真實事件或測試報告。

維護模式是什麼意思

Nextcloud 的維護模式會在管理員執行升級或備份等作業時阻止一般使用者存取。這是一個伺服器層級的狀態，因此即使 Web 伺服器本身正在運行，使用者也可能會收到維護通知。 Nextcloud 目前的管理手冊中記錄了用於啟用或停用此模式的 OCC 命令，並指出使用者可能需要在關閉此模式後刷新瀏覽器。

以範例辦公室為例，僅憑維護頁面無法告知管理員升級是否完成。他們需要在更改模式之前查詢 Nextcloud 本身。

步驟 1：確認安裝類型和 OCC 路徑

此處的命令範例適用於在 Ubuntu 上進行傳統的基於歸檔的 Nextcloud 安裝，程式碼位於 `<path>` /var/www/nextcloud，Web 伺服器帳號名為 `<username>` www-data。 Nextcloud 文件occ位於安裝目錄中，必須以 HTTP 使用者身分執行；在 Debian 和 Ubuntu 上，該使用者通常是 `<username>` www-data。

對於這種標準佈局，請輸入安裝目錄：

cd /var/www/nextcloud

如果您的 Nextcloud 檔案位於其他位置，請使用該實際路徑。 Snap、Docker、虛擬設備和託管主機使用不同的命令封裝或檔案系統佈局。請勿對容器安裝執行 host 指令，也不要假設歸檔路徑適用於這些部署。請依照Nextcloud 官方升級指南中所述的安裝方式的更新說明進行操作。

在辦公室範例中，管理員檢查部署說明，並在執行 OCC 之前確認這是歸檔安裝。

步驟 2：在停用維護之前，請檢查 Nextcloud 的狀態。

以 Web 伺服器帳戶身分執行 OCC，以便檔案和設定保留其預期的所有權：

sudo -E -u www-data php occ status

查看 ` maintenanceand`needsDbUpgrade字段。當前版本還支援狀態退出代碼：

sudo -E -u www-data php occ status -e
echo $?

當腳本檢查輸出時，文件中記錄的退出代碼非常有用：0表示正常運行，1表示已啟用維護模式，表示需要重新開啟2網站occ upgrade。此外，還應查看純狀態輸出；不要僅憑退出代碼來決定是否重新開啟網站。

對於假設的辦公伺服器，如果needsDbUpgrade為真或status -e返回2，則正確的下一步是完成升級，而不是簡單地關閉維護模式。

步驟 3：先完成未完成的升級

如果已有意部署 Nextcloud 程式碼升級，且 OCC 報告需要升級資料庫，請在繼續操作之前備份或驗證資料庫、設定和資料的最新狀態。然後從安裝目錄執行文件中提供的命令：

sudo -E -u www-data php occ upgrade

閱讀命令輸出並等待其完成。請勿中斷遷移過程，因為遷移期間網頁可能看起來沒有變更。內建更新程式在程式碼替換occ upgrade失敗時可能會保持維護模式啟用狀態。如果更新程式本身未完成程式碼替換，請查看其日誌，並根據您的安裝情況恢復相應的更新程式進程，而不是直接跳到下一步maintenance:mode --off。 Nextcloud 的內建更新程式說明解釋了更新的各個階段，並將更新程式日誌作為診斷資源加以說明。

在這個例子中，只有當狀態顯示資料庫遷移仍在進行中且預期的新程式碼已就緒時，辦公室管理員才會執行該指令occ upgrade。如果命令報告錯誤，他們會先將伺服器置於不可用狀態，並調查該錯誤。

步驟 4：使用 OCC 關閉維護模式

當升級完成且狀態不再顯示需要資料庫升級時，使用 Nextcloud 的內建指令來停用維護模式：

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

命令執行成功後，會報告維護模式已停用。這是標準安裝中更改模式的官方支援方法；它還能在 Nextcloud 自身的命令介面內完成狀態更改，而無需手動編輯設定檔config.php。

範例辦公室管理員現在僅在遷移完成後執行此命令。如果未進行任何升級且狀態顯示安裝已準備就緒，則相同指令可以清除計劃維護後遺留的維護標誌。

步驟 5：驗證狀態和 Web 介面

請再次檢查狀態：

sudo -E -u www-data php occ status
sudo -E -u www-data php occ status -e

安裝完成後，預期會顯示「已安裝」maintenance: false、「已needsDbUpgrade: false安裝」和正常的退出代碼0。然後，在新開啟的隱私瀏覽視窗中開啟網站，並使用管理員帳號登入。請一位普通用戶刷新瀏覽器，然後再確認其會話是否仍被阻止。

在範例場景中，「成功」指的是 OCC 狀態和網頁都顯示實例已恢復上線。該範例並未聲稱實際執行了任何命令或修復了任何真實的伺服器。

如果維護頁面仍然存在

OCC稱維護情況不實

確認您已針對提供該 URL 的相同安裝執行了 OCC。這在負載平衡部署、包含多個容器的 Docker 主機或新舊 Nextcloud 目錄並存的伺服器上尤其重要。檢查實際的文檔根目錄或容器路徑，並查詢受影響 URL 背後的實例。如果每個 Web 節點都有自己的配置，請確認所有節點共用預期的配置和資料庫。

如果正確的實例報告維護已停用，請將伺服器來源頁面與公用 URL 進行比較。反向代理或快取可能提供了過時的回應。只有在確認是哪個層返回了維護頁面後，才能清除或繞過該快取。

OCC 無法運作或傳回 PHP 錯誤

請檢查該指令使用的 PHP CLI 版本和所需擴充功能是否與 Web 安裝相容。 Nextcloud 指出，預設情況下 CLI PHP 停用 APCu，如果將 APCu 配置為本機緩存，則可能導致 OCC 錯誤。其手冊中記錄如何apc.enable_cli在 CLI PHP 配置中啟用 APCu，或--define apc.enable_cli=1在適當情況下將其新增至 PHP 指令：

sudo -E -u www-data php --define apc.enable_cli=1 occ status

僅當錯誤訊息指向 APCu CLI 問題時才使用此方法；它並非適用於所有 PHP 錯誤的通用修復方案。此外，請確認該命令以正確的 Web 使用者身分執行，並且運行目錄正確。

資料庫升級仍然是必需的。

請勿強制關閉維護標誌以隱藏此狀態。請重新檢查更新程式輸出和日誌，確認已安裝正確的 Nextcloud 程式碼版本，並完成適用於您安裝類型的支援升級流程。官方OCC 系統和維護命令參考文件maintenance:mode、status以及命令列升級指南。

控制維護窗口

停用維護模式後，使用者可以重新存取實例，因此請先確認資料庫升級和所有必要的程式碼替換均已完成。切勿先手動刪除更新程式檔案或編輯設定檔中的維護設定；這樣做可能會掩蓋問題，而無法完成觸發維護模式的根本原因。

對於假設的辦公室而言，穩健的做法很簡單：確認安裝正確，檢查狀態，完成任何必要的升級，然後執行maintenance:mode --off並驗證 OCC 和瀏覽器。如果升級無法順利完成，請保持維護模式開啟，並根據更新程式日誌或特定於安裝的復原步驟進行故障排除。