使用定時佇列來控制 Nextcloud 預覽版 CPU 峰值

如果 Nextcloud 伺服器在創建預覽時 CPU 使用率飆升，通常是由於工作負載集中爆發造成的：用戶打開了大量圖片資料夾、正在索引大型圖庫，或者預覽任務嘗試產生超出用戶實際需求的圖片尺寸。安裝 Nextcloud 的預覽生成器應用，讓它按計劃處理新增和已更改的文件，並裁剪掉不必要的預覽圖片尺寸。這樣可以將工作從繁忙的瀏覽會話中轉移出來；但並不能完全消除圖片轉換或初始追趕工作負載。

這些步驟遵循預覽產生器自述文件和 Nextcloud 35 文件（2026 年 10 月 10 日更新）。請在 Nextcloud 應用程式商店中確認您的版本是否相容。自述文件中列出了不支援的加密文件。

為什麼預覽生成會佔用大量 CPU 資源？

Nextcloud 會在使用者要求時建立縮圖，除非已有預覽圖。影像解碼、調整大小和轉換（尤其對於尺寸較大的原始影像或多種目標尺寸）會消耗 CPU 和記憶體。請求高峰期會使這些工作在使用者互動的同時可見。

預覽生成器會將新建或修改的檔案加入後台處理佇列。現有預覽的載入成本更低，但缺少的預覽仍會使用 Nextcloud 的按需載入方式。該應用程式會將部分工作轉移到流量較低的時段；但它無法減少總處理量，也無法解決其他瓶頸問題，例如視訊轉換或儲存速度慢。

建立受控預覽隊列

1. 檢查後台任務模式和應用相容性

在管理設定中，檢查後台任務。預覽產生器的內建任務需要 Cron 模式；其 README 檔案指出，AJAX 和 Webcron 不支援此類長時間運行的任務。 Nextcloud 建議使用系統 Cron。請確認管理頁面顯示 Cron 已啟用。

從「應用」畫面安裝預覽產生器；或者，如果您的部署使用 OCC 並允許安裝應用程式，請從 Nextcloud 安裝目錄執行以下命令。在 Debian 或 Ubuntu 系統上，Web 伺服器帳號通常為 `<username>` www-data；請使用您主機上的實際 HTTP 使用者和 PHP CLI 版本：

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

如果已安裝，請跳過第一個命令。檢查狀態和可用指令：

sudo -u www-data php /var/www/nextcloud/occ app:list
sudo -u www-data php /var/www/nextcloud/occ list preview

以 HTTP 使用者身分執行 OCC，以確保檔案所有權一致。路徑和使用者因部署而異。請參閱Nextcloud 的 OCC 文件。

2. 在開始大規模生成運行之前，減少預覽變體的數量

預覽產生器可以建立正方形縮圖和按配置尺寸縮放的預覽圖。其自述文件指出，尺寸必須是 4 的冪，如果值為空，則會跳過該預覽類別。下面展示了一個針對負載較重伺服器的精簡初始配置。它保留了小正方形圖塊和兩種縮放比例，同時跳過了僅寬度和僅高度的單獨變體：

sudo -u www-data php /var/www/nextcloud/occ config:app:set --value="64 256" previewgenerator squareSizes
sudo -u www-data php /var/www/nextcloud/occ config:app:set --value="256 1024" previewgenerator fillWidthHeightSizes
sudo -u www-data php /var/www/nextcloud/occ config:app:set --value="" previewgenerator widthSizes
sudo -u www-data php /var/www/nextcloud/occ config:app:set --value="" previewgenerator heightSizes

這種低負載配置並非適用於所有應用：應用程式可能需要更大的預覽圖或其他尺寸。如果縮圖缺失或模糊，請確定所需的視圖並僅添加其尺寸。更大的尺寸會增加處理能力和快取使用量。 README 文件中建議的「檔案」、「照片」和「活動」應用程式的最小尺寸設定使用了更大的 4096 像素；請根據您的硬體配置評估這種權衡。另請參閱官方預覽產生器的 README 檔案；它使用了更大的 4096 像素寬高比，因此也請根據您的硬體配置評估這種權衡。

這些設定限制了整體像素上限。編輯前請備份文件，並確保其與所選應用尺寸相容。停用預覽會移除所有應用程式的縮圖preview_max_x。preview_max_yconfig/config.php

3. 安排應用程式的預生成命令，而無需複製其工作進程。

對於小型伺服器，一旦啟用 Cron 模式，內建佇列工作進程就足夠用了。其預設任務每次執行時間限制為最多五分鐘，應用程式會提供佇列統計資料以供監控。如果您需要一個可預測的非尖峰時段，請改用系統 Cron 中的專用 OCC 指令。使用該自訂計劃時，請停用應用程式的預設佇列任務，以避免兩種機制相互衝突。

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

然後編輯 Web 伺服器使用者的 crontab 檔案（sudo crontab -u www-data -e），並新增一個範例規劃任務，例如：

*/10 * * * * php -f /var/www/nextcloud/occ preview:pre-generate

十分鐘只是一個範例。請根據您的流量和容量選擇合適的頻率和時間視窗；確認您的 PHP 和 OCC 路徑。不要在其他位置也安排該命令。保留 Nextcloud 的常規cron.php任務，它會執行其他後台任務。請參閱Nextcloud 後台任務指南，以了解系統 cron 設定的相關文件。

4. 避免首次追趕跑失控。

安裝後， README 文件建議preview:generate-all覆蓋現有文件。對於大型函式庫，這種追趕式運作可能會導致 CPU 使用率大幅飆升。避免在繁忙的伺服器上執行過多工作進程。建議在伺服器空閒時，先使用一個使用者或一個路徑，並監控 CPU、記憶體、磁碟吞吐量和可用空間。此指令支援使用者 ID、路徑和工作進程數；建議先使用一個工作進程。如有必要，可將掃描過程拆分到多個視窗中執行。

確認負載是否變成可預測

命令運行完畢後，檢查佇列：

sudo -u www-data php /var/www/nextcloud/occ preview:queue-stats

隊列統計資訊包含過期的預覽。積壓任務減少以及 CPU 高峰在排程任務結束後結束，表示佇列正在處理中。打開一個代表性資料夾以確認縮圖，然後觀察正常的瀏覽情況。比較類似流量水準下的 CPU 使用率；CPU 使用率不會降至零。

如果佇列沒有縮小，請檢查 cron 日誌，並preview:pre-generate -vv在受控視窗中執行以查看已處理的檔案。如果佇列清空後 CPU 使用率仍然很高，請檢查其他 PHP 工作進程、作業或媒體服務。如果預覽佔用過多磁碟空間，請移除未使用的大小或降低尺寸。驗證剩餘的預覽是否滿足使用者所需的視圖。

官方參考資料

• 預覽生成器 README 和 OCC 命令
• Nextcloud 後台作業與系統定時任務
• Nextcloud 預覽配置
• 預覽生成器相容性和版本