修正 Nextcloud 預覽產生器 CPU 使用率過高的問題：設定預覽產生器

簡而言之：安裝預覽生成器應用並啟用它，先運行一次精心設計的初始生成，然後安排occ preview:pre-generate在使用者較少的時間段運行。同時，限制預覽檔案的大小以及 Nextcloud 一次產生的預覽數量。該應用程式會將工作負載轉移到使用者開啟檔案之外；它不會限制 CPU 使用率，並且可能會增加磁碟使用量。

這種配置適用於自架的 Nextcloud 伺服器，尤其是在瀏覽縮圖時，如果伺服器規模較小且擁有大量照片或文件庫，則會導致 CPU 使用率大幅上升。如果您的執行個體使用了伺服器端加密，則此配置的實用性會降低：預覽產生器專案已將加密列為已知不相容性。託管主機、Nextcloud AIO、Docker 和軟體包安裝也使用不同的命令路徑，因此請根據您的部署環境調整命令。切勿從猜測的目錄執行命令。

目前應用說明建議安裝並啟用該應用，運行preview:generate-all一次，然後安排preview:pre-generate後續文件變更的自動處理。對於大型庫，首次運行命令可能會消耗大量資源。建議先從一個使用者或資料夾和一個工作進程開始。請查看 Preview Generator 專案的 README 檔案和命令選項，並在 Nextcloud 應用程式商店中選擇與您的 Nextcloud 版本相容的版本。

1. 確認這是正確的修復方案

首先確定 CPU 使用率何時上升。如果是在使用者開啟包含大量照片的資料夾或需要預覽的文件時發生，預覽產生器可以將大部分工作轉移到排程任務。如果 CPU 使用率在無人瀏覽時仍然很高，或者峰值出現在其他服務期間，預覽產生器可能無法解決問題。更改設定前，請檢查進程監視器和 Nextcloud 日誌。

預覽產生器會記錄已新增或已變更的文件，並在背景作業中處理它們。現有的預覽可以降低後續請求的成本，但即使缺少預覽，也可以在規劃作業處理之前按需產生。這意味著當佇列處理完畢後，應用程式可以減少用戶端的突發流量；但它無法保證 CPU 使用率零峰值。此外，它還會佔用一些儲存空間來換取更快的預覽交付速度。對於瀏覽頻率不高的小型圖書館來說，Nextcloud 的按需處理機制可能就足夠了。

2. 安裝相容的應用程式版本

通用雲端管理頁面，帶有圖像預覽應用程式卡，並且啟用開關已開啟。 — 通用雲端管理頁面顯示一個已開啟的映像預覽應用程式卡片，用於演示安裝和啟用步驟；佈局不是特定版本的螢幕截圖。

以 Nextcloud 管理員身份登錄，開啟「應用」區域，找到Preview Generator，然後安裝並啟用它。在繼續操作之前，請確認 App Store 中是否有與您已安裝的 Nextcloud 主要版本相容的穩定版本。請勿手動將最新的應用程式資料夾複製到 App Store 標記為不相容的版本。

擁有 shell 存取權限的管理員可以透過以下命令檢查或啟用該應用程式occ。典型的軟體包安裝命令如下所示；請將 PHP 二進位檔案和 Nextcloud 路徑替換為您的主機路徑。對於 Docker 或 AIO，請改用該部署支援的容器指令或排程器指令。

sudo -u www-data php /var/www/nextcloud/occ app:enable previewgenerator

3. 將 Nextcloud 的後台任務設定為 Cron 任務

在 Nextcloud 管理設定中，選擇Cron作為背景任務模式，並確認 Nextcloud 系統自帶的 cron 任務正在執行。該應用的 README 文件指出，其內建的預覽後台任務需要 Cron 模式；Webcron 和 AJAX 模式不支援該長時間運行的任務。如果您的系統自帶 cron 任務發生故障，僅安裝此應用程式無法使任務佇列恢復運作。

請勿將 Nextcloud 的常規 cron.php 排程任務與應用程式可選的專用preview:pre-generate排程任務混淆。兩者是不同的機制。您可以使用應用程式內建的背景任務或專用的系統 cron 命令。如果您選擇專用指令，專案建議停用其內建的預覽後台任務，以避免對相同佇列執行兩種不同的任務路徑。

通用調度程序頁面，包含一個活動的重複性任務，點擊後會開啟命令視窗並顯示縮圖結果。 — 調度程序頁面顯示一個正在執行的重複性任務，該任務會將預覽工作傳送到命令視窗並傳回縮圖結果。

4. 在首次批次運作之前降低預覽工作負載

通用配置面板，上方有類似程式碼的設置，用於控制預覽大小和處理器使用量。 — 通用配置面板將類似程式碼的設定與影像大小和處理器控制相結合，說明了管理員應該調整的兩個限制。

對於 CPU 密集型預覽創建，請減少同時運行的新預覽數量。在 Nextcloud 35 的設定參考中，preview_concurrency_new可控制並發新預覽的產生數量；文件中記錄的預設值為 4，手冊建議將其設定為不超過 CPU 核心數。在小型主機上，可以嘗試使用 2 這樣的值，如果伺服器無回應，則可嘗試使用 1。這可以限制並發任務，但單一大型影像或視訊仍然會消耗大量 CPU 資源。

預覽尺寸也很重要。 Nextcloud 35 文件預設的最大寬度和高度均為 4096 像素。降低這preview_max_x兩個preview_max_y值config/config.php可以減少處理和記憶體需求，但代價是預覽尺寸會變小。備份設定檔並將設定合併到其現有的 PHP 陣列中；不要用程式碼片段取代該檔案。例如，管理員可以將這兩個值都設為 2048，並在「檔案」和「照片」視圖中測試預覽品質。

該應用還可以產生多種尺寸變體。其 README 文件提供了一個針對常用文件、照片和活動用途的縮小尺寸配置文件：正方形尺寸64 256、全寬高尺寸256 4096以及空白尺寸。widthSizes若要heightSizes跳過這些變體群組，請僅當這些設定符合使用者所依賴的應用程式時才使用這些設定；「回憶」時間軸或其他應用程式可能需要其他尺寸。該項目指出，預覽尺寸必須符合其認可的尺寸規則，且不得超過配置的最大值。請查看 Nextcloud 的預覽尺寸和品質設定以及特定版本的配置參考。

5. 先小批量產生現有預覽

套用啟用並設定限制後，請針對測試資料夾或單一使用者執行初始產生器，而不是針對整個實例。該應用程式支援按使用者 ID 或路徑進行篩選，並且該命令接受工作進程數。為確保初始結果的保守性，建議使用單一工作流程。

sudo -u www-data php /var/www/nextcloud/occ preview:generate-all --workers=1 --path="/alice/files/Photos"

已選擇排程任務選項的通用背景作業設定畫面。 — 後台作業設定頁面會顯示已選取的排程任務選項；特定的標籤和可用選項會因 Nextcloud 版本而異。

請將 `<path>`、`<user>` 和 `<user>`替換alice為伺服器上的實際路徑。 `<path>` 選項的格式為 `<path>` /[username]/files/[folder path]。如果省略路徑和使用者篩選條件，則該指令可能會遍歷整個程式庫。請在使用者活動較少時執行此批次處理，並監控 CPU、記憶體和磁碟空間的使用。如果伺服器變得不穩定，請停止運作並重新評估。在評估其效果之前，請勿為了加快完成速度而增加工作進程數。

6. 安排新增或變更的文件

測試批次運行正常後，將其新增preview:pre-generate至系統 cron 排程任務。應用程式的 README 文件中以每十分鐘一次為例，但這並非強制要求。請選擇一個與上傳量和可用空閒時間相符的間隔。例如，Web 伺服器帳戶的 crontab 檔案可以包含以下行，並根據安裝情況調整路徑：

*/10 * * * * cd /var/www/nextcloud && /usr/bin/php -f occ preview:pre-generate

終端風格的面板，帶有資料夾圖標，圖標後面跟著生成的圖像縮圖。 — 終端風格的視窗顯示選定的資料夾，然後顯示影像縮圖，表示單一工作進程對有限路徑的初步處理。

如果您使用此專用系統定時任務，請依照專案建議停用應用程式內建的預覽後台作業。文件中記錄的應用程式設定如下：

sudo -u www-data php /var/www/nextcloud/occ config:app:set --value=true --type=boolean previewgenerator job_disabled

保持 Nextcloud 的常規 cron.php 任務啟用狀態。對於容器和託管平台，請使用平台支援的調度器，而不是將主機路徑新增至容器 cron 條目。如果應用程式已啟用加密，請停止操作並諮詢您的管理員或主機服務提供者；該專案目前已將該配置列為不支援。

7. 監控排隊狀況並確認改善情況。

通用監控介面，包含 CPU 使用率圖表和兩個佇列進度條。 — 通用監控面板將 CPU 圖表與佇列進度條結合起來，用於比較伺服器負載和預覽積壓。

執行此命令occ preview:queue-stats以檢查預生成佇列和過期預覽。如果佇列在兩次排程運行之間縮小，則表示工作進程正在趕工。如果佇列持續成長，則表示使用者新增檔案的速度超過了配置的作業處理速度；在確認額外的 CPU 負載可以接受後，請謹慎地增加執行頻率或允許的作業數量限制。該應用程式會公開作業執行時間和每次執行預覽數量的限制。其 README 檔案中指出零表示無限制，因此在資源受限的主機上不要隨意選擇零值。

在相似的時間段內，比較部署前後 CPU 峰值，然後以普通使用者身分開啟一個具有代表性的照片資料夾和一個文件預覽。確認縮圖顯示正常、頁面回應流暢，且在計畫批次處理完成後 CPU 使用率趨於穩定。白天 CPU 使用率曲線趨於平緩且佇列進度良好是一個理想的結果；如果積壓任務持續成長或使用者會話速度變慢，則需要重新評估排程、任務大小或底層預覽提供者。

雲端文件庫，以資料夾視圖顯示六個影像縮圖。 — 文件風格的圖庫顯示圖像縮圖，以視覺檢查請求的預覽是否已載入。

重要限制和安全清理

某些預覽類型依賴伺服器端程式：Nextcloud 手冊列出了用於視訊預覽的 FFmpeg 和用於辦公室文件預覽的 LibreOffice。這些格式的行為可能與普通圖像縮圖有所不同，並且對它們的支援取決於服務提供者的配置。在更換服務提供者或添加服務之前，請先降低並發量並測試少量文件。

如果您變更了預覽尺寸或支援的檔案類型，並且需要丟棄快取的預覽，Nextcloud 31 及更高版本提供了occ preview:cleanup此功能（根據專案 README 文件）。它會刪除所有產生的預覽文件，之後 Nextcloud 會在使用者存取文件時按需建立預覽。這可能會暫時恢復您試圖降低的 CPU 使用率高峰。因此，請在適當情況下進行備份，並有計劃地安排清理工作，同時避免在例行調優中手動刪除 appdata 預覽目錄。預覽產生器 README 文件也介紹了一種.nomedia在適當情況下跳過某個資料夾及其子資料夾的方法。

盾牌旁邊有一個帶鎖的資料夾和隱藏文件圖示。 — 盾牌和鎖旁邊會出現一個資料夾和一個隱藏檔案符號，表示加密限制以及可以跳過資料夾的選項。

實際上，當按需預覽速度慢導致明顯的峰值負載，您可以安排後台運行，並且有足夠的磁碟空間來快取預覽大小時，預覽生成器是一個不錯的選擇。建議搭配適度的並發限制、與實際顯示需求相符的預覽尺寸，以及先進行測試再批量運行。如果執行個體已加密、未進行 shell 排程管理，或因與預覽要求無關的原因導致 CPU 密集型，請在部署前調查這些限制因素。