예약 대기열을 사용하여 Nextcloud 미리보기의 CPU 사용량 급증을 제어하세요

Nextcloud 서버에서 미리보기 생성 중에 CPU 사용량이 급증하는 경우, 이는 대개 작업 부하가 갑자기 몰리는 현상 때문입니다. 예를 들어 사용자들이 이미지가 많은 폴더를 열거나, 대규모 라이브러리를 색인화하거나, 미리보기 작업이 필요 이상으로 많은 크기의 이미지를 생성하려고 할 때 발생할 수 있습니다. Nextcloud의 미리보기 생성기 앱을 설치하고, 지정된 일정에 따라 새 파일과 변경된 파일을 처리하도록 설정하면 불필요한 미리보기 크기를 줄일 수 있습니다. 이렇게 하면 사용량이 많은 브라우징 세션에서 작업 부하를 줄일 수 있지만, 이미지 변환이 완전히 무료가 되거나 초기 처리량 증가로 인한 작업량 증가를 막지는 못합니다.

이 단계는 2026년 10월 10일에 확인된 미리 보기 생성기 README 및 Nextcloud 35 문서를 따릅니다. Nextcloud 앱 스토어에서 사용 중인 릴리스의 호환성을 확인하십시오. README에는 암호화된 파일이 지원되지 않는 것으로 명시되어 있습니다.

미리보기 이미지 생성이 CPU 사용량을 높이는 이유는 무엇입니까?

Nextcloud는 미리보기 이미지가 이미 존재하는 경우를 제외하고 사용자가 요청할 때마다 썸네일 이미지를 생성합니다. 이미지 디코딩, 크기 조정 및 변환, 특히 원본 크기가 크거나 대상 크기가 여러 개인 경우 CPU와 메모리를 많이 소모할 수 있습니다. 요청이 폭주하면 이러한 작업이 사용자의 상호 작용과 동시에 눈에 띄게 나타납니다.

미리보기 생성기는 새롭거나 수정된 ​​파일을 백그라운드 처리를 위해 대기열에 추가합니다. 기존 미리보기는 처리 비용이 저렴하지만, 누락된 미리보기는 여전히 Nextcloud의 온디맨드 방식을 사용합니다. 이 앱은 일부 작업을 사용량이 적은 시간대로 옮기지만, 전체 처리량을 줄이거나 비디오 변환 또는 느린 스토리지와 같은 다른 병목 현상을 해결할 수는 없습니다.

제어된 미리보기 대기열을 설정하세요

1. 백그라운드 작업 모드와 앱 호환성을 확인하세요.

관리자 설정에서 백그라운드 작업을 확인하세요. Preview Generator의 내장 작업은 Cron 모드를 필요로 하며, 해당 README 파일에는 AJAX 및 Webcron이 이 장시간 실행 작업에 지원되지 않는다고 명시되어 있습니다. Nextcloud는 시스템 cron 사용을 권장합니다. 관리자 페이지에 Cron이 표시되는지 확인하세요.

앱 화면에서 Preview Generator를 설치하거나, ​​OCC를 사용하는 배포 환경에서 앱 설치가 허용되는 경우 Nextcloud 설치 디렉터리에서 다음 명령을 실행하세요. Debian 또는 Ubuntu에서는 웹 서버 계정이 일반적으로 입니다. 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

파일 소유권이 일관되게 유지되도록 OCC를 HTTP 사용자 권한으로 실행하십시오. 경로 및 사용자는 배포 환경에 따라 다를 수 있습니다. Nextcloud의 OCC 설명서를 참조하십시오 .

2. 대규모 생성 실행을 시작하기 전에 미리 보기 변형 수를 줄이세요.

Preview Generator는 설정된 크기의 정사각형 썸네일과 가로세로 비율의 미리보기 이미지를 생성할 수 있습니다. README 파일에 따르면 크기는 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 모드가 활성화되면 내장 큐 워커만으로도 충분할 수 있습니다. 기본 작업은 실행 시간이 최대 5분으로 제한되며, 앱은 모니터링을 위한 큐 통계를 제공합니다. 예측 가능한 비피크 시간대가 필요한 경우, 시스템 cron에서 전용 OCC 명령을 사용하십시오. 사용자 지정 스케줄을 사용할 때는 두 메커니즘이 충돌하지 않도록 앱의 기본 큐 작업을 비활성화해야 합니다.

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

그런 다음 웹 서버 사용자( sudo crontab -u www-data -e)의 crontab을 편집하고 다음과 같은 예시 일정을 추가합니다.

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

10분은 단지 예시일 뿐입니다. 트래픽과 용량에 맞춰 실행 주기와 시간 간격을 선택하고, PHP 및 OCC 경로를 확인하세요. 해당 명령어를 다른 곳에 중복해서 예약하지 마세요. cron.php다른 백그라운드 작업을 실행하는 Nextcloud의 정기적인 cron 작업은 그대로 유지해야 합니다 . 시스템 cron 설정에 대한 자세한 내용은 Nextcloud 백그라운드 작업 가이드 문서를 참조하세요.

4. 통제되지 않은 첫 번째 따라잡기 주행을 피하십시오.

README 파일 preview:generate-all에는 설치 후 기존 파일을 덮어쓰도록 권장되어 있습니다. 대규모 라이브러리의 경우, 이 덮어쓰기 실행으로 인해 CPU 사용량이 급증할 수 있습니다. 사용량이 많은 서버에서는 많은 워커를 실행하지 마십시오. 사용량이 적은 시간대에 사용자 한 명 또는 경로 한 개로 시작하여 CPU, 메모리, 디스크 처리량 및 여유 공간을 모니터링하십시오. 이 명령은 사용자 ID, 경로 및 워커 수를 지원합니다. 처음에는 워커 한 개로 시작하십시오. 필요한 경우 스캔을 여러 창으로 분할하십시오.

부하가 예측 가능해지고 있는지 확인하십시오.

명령 실행 후 대기열을 확인하세요.

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

대기열 통계에는 오래된 미리보기가 포함됩니다. 백로그 감소와 예약된 작업으로 끝나는 CPU 피크는 대기열이 진행 중임을 나타냅니다. 대표 폴더를 열어 썸네일 표시를 확인한 다음 일반적인 탐색을 관찰하십시오. 비슷한 트래픽 수준에서 CPU 사용량을 비교해 보면 0에 도달하지 않습니다.

큐가 줄어들지 않으면 cron 로그를 확인하고, preview:pre-generate -vv처리된 파일을 볼 수 있도록 제한된 시간 동안 실행해 보세요. 큐가 비워진 후에도 CPU 사용률이 높게 유지되면 다른 PHP 워커, 작업 또는 미디어 서비스를 점검하세요. 미리보기가 디스크 공간을 너무 많이 사용하는 경우, 사용하지 않는 크기를 제거하거나 크기를 줄이세요. 남은 미리보기가 사용자가 필요로 하는 보기를 지원하는지 확인하세요.

공식 참조

• 미리보기 생성기 README 및 OCC 명령
• Nextcloud 백그라운드 작업 및 시스템 cron
• Nextcloud 미리 보기 구성
• 미리보기 생성기 호환성 및 릴리스