Gaon12: 새 문서. 정리 스크립트와 비동기 작업(Queue) 실행 방법

2026-08-21T05:59:29Z

새 문서. 정리 스크립트와 비동기 작업(Queue) 실행 방법

새 문서

{{틀:상위문서|라이믹스/매뉴얼}}

== 개요 ==
[[라이믹스]]에서 cron을 사용하는 경우는 크게 두 가지이다.

# '''정리 스크립트''' — 쌓인 불필요한 데이터를 정기적으로 지운다. 하루 한 번 정도 실행한다.
# '''비동기 작업(Queue) 실행''' — 메일 발송이나 푸시 알림을 백그라운드에서 처리한다. 1분 간격 등 짧은 주기로 실행한다.

공식 매뉴얼의 Crontab 설정 방법 문서는 앞쪽만 다루므로,<ref name="crontab">[https://rhymix.org/manual/misc/crontab Crontab 설정 방법 - 라이믹스 매뉴얼]</ref> 이 문서에서는 두 가지를 함께 정리한다.

윈도우 서버는 지원하지 않는다.<ref name="crontab" />

== 정리 스크립트 ==
사이트를 운영하다 보면 탈퇴한 회원의 정보, 삭제된 사진의 섬네일, 확인하지 않은 알림 같은 불필요한 데이터가 쌓인다. 이런 데이터를 정기적으로 지우면 디스크 공간을 아끼고 서버를 쾌적하게 유지할 수 있다.<ref name="crontab" />

라이믹스는 이를 위한 PHP-CLI 스크립트를 제공한다. 다량의 데이터를 지우는 데 시간이 오래 걸릴 수 있어 '''웹에서는 실행할 수 없다.'''<ref name="crontab" />

=== 실행 방법 ===
스크립트는 각 모듈의 <code>scripts</code> 폴더에 있으며, 라이믹스 설치 경로에서 다음 형식으로 실행한다.<ref name="crontab" />

<syntaxhighlight lang="console">
php index.php 모듈명.스크립트명 [변수]
</syntaxhighlight>

예를 들어 60일 이상 지난 알림을 지우려면 다음과 같이 실행한다.

<syntaxhighlight lang="console">
php index.php ncenterlite.cleanNotifications 60
</syntaxhighlight>

=== 스크립트 목록 ===
{| class="wikitable"
! 스크립트 !! 하는 일 !! 기본값
|-
| <code>file.cleanGarbageFiles</code>
| 파일만 올리고 글 작성을 취소하여 남은 파일, 대용량 업로드가 중단되어 남은 파일 등을 지운다
| 10일
|-
| <code>file.cleanThumbnails</code>
| 오래된 섬네일 이미지를 지운다
| 90일
|-
| <code>module.cleanMiscLogs</code>
| 메일·SMS 발송 로그, 푸시 발송 로그, 스팸필터 로그 등 여러 모듈이 만드는 잡다한 로그를 일괄 삭제한다
| 30일
|-
| <code>ncenterlite.cleanNotifications</code>
| 오래된 알림을 지운다
|
|-
| <code>file.cleanEmptyDirs</code>
| 첨부파일·회원정보·섬네일 폴더에 남은 빈 폴더를 지운다
|
|}

'''<code>file.cleanThumbnails</code>는 주의해야 한다.''' 오래된 글의 섬네일도 보여줘야 하는 웹진형 게시판을 운영한다면 쓰지 말자. 지운 섬네일을 다시 만드는 데 더 많은 서버 자원이 든다.<ref name="crontab" />

<code>file.cleanGarbageFiles</code>도 주의가 필요하다. 일부 서드파티 자료는 파일 업로드 후 문서에 정상적으로 연결하지 않고 <code>isvalid=N</code> 상태로 방치하는데, 이런 파일이 삭제될 수 있다.<ref name="crontab" />

=== crontab 설정 예제 ===
여러 스크립트를 동시에 실행하면 과부하가 걸릴 수 있으므로, 방문자가 적은 시간대에 시간차를 두고 실행하자. 매일 정해진 시각에 백업한다면 백업 직전에 정리하는 것이 편하다.<ref name="crontab" />

'''빈 폴더를 지우는 스크립트를 맨 마지막에 실행하면 효과적이다.''' 앞선 스크립트들이 파일을 지우면서 빈 폴더가 생기기 때문이다.

<syntaxhighlight lang="text">
05 05 * * * php /설치경로/index.php file.cleanGarbageFiles >> /설치경로/files/cron.log 2>&1
10 05 * * * php /설치경로/index.php file.cleanThumbnails >> /설치경로/files/cron.log 2>&1
15 05 * * * php /설치경로/index.php module.cleanMiscLogs >> /설치경로/files/cron.log 2>&1
15 05 * * * php /설치경로/index.php ncenterlite.cleanNotifications >> /설치경로/files/cron.log 2>&1
20 05 * * * php /설치경로/index.php file.cleanEmptyDirs >> /설치경로/files/cron.log 2>&1
</syntaxhighlight>

== 비동기 작업 실행 ==
라이믹스는 메일 발송, 푸시 알림처럼 시간이 오래 걸리거나 외부 서비스와 연동하는 작업을 비동기로 처리하여 응답 속도를 개선하는 기능을 제공한다. 관리자 화면의 <code>비동기 작업</code> 항목에서 설정한다.

:※ 관리자 화면은 이 기능을 '''실험적인 기능'''으로 안내하고 있다. 호스팅 환경에 따라서는 안정적으로 작동하지 않을 수도 있다.

'''이 기능을 켜기만 해서는 동작하지 않는다.''' 외부 스케줄러가 일정한 주기로 처리 스크립트를 호출해 주어야 한다.

=== 관리자 설정 항목 ===
{| class="wikitable"
! 항목 !! 설명
|-
| 비동기 작업 사용 || 체크를 해제하면 더 이상 작업을 접수하지 않는다
|-
| 비동기 드라이버 || 작업을 관리할 방법. Redis 등 일부 드라이버는 서버에 해당 기능이 설치되어 있어야 한다
|-
| 호출 간격 || 스크립트를 호출할 주기(분). 모든 작업은 호출 간격과 무관하게 실시간으로 처리되지만, 간격이 짧으면 장애 발생 시 빠르게 복구된다
|-
| 프로세스 갯수 || 여러 프로세스를 동시에 실행해 처리 용량을 늘린다. 고성능 단독 서버가 아니라면 1을 유지하는 것이 권장된다
|-
| 웹크론 오류 표시 || 에러 로그를 확인하기 어려운 환경에서 웹크론 오류를 화면에 표시한다
|}

=== crontab으로 실행 ===
처리 스크립트는 <code>common/scripts/cron.php</code>이며, CLI에서는 <code>common.cron</code>이라는 이름으로 호출한다.

<syntaxhighlight lang="text">
* * * * * php /설치경로/index.php common.cron
</syntaxhighlight>

호출 간격을 1분으로 설정했다면 위와 같이 매분 실행한다. 스크립트는 설정한 호출 간격만큼 실행된 뒤 스스로 종료되므로, 앞선 실행이 끝나기 전에 다음 실행이 겹치지 않는다.

=== systemd timer로 실행 ===
crontab 대신 systemd timer를 사용해도 된다. 관리자 화면의 안내도 crontab, systemd timer, 웹크론을 나란히 제시하고 있다.

=== 웹크론으로 실행 ===
SSH를 쓸 수 없는 웹호스팅 환경에서는 외부 웹크론 서비스로 URL을 호출하는 방법을 쓸 수 있다. 정리 스크립트와 달리 이 스크립트는 네트워크를 통한 직접 호출을 지원한다.

<syntaxhighlight lang="text">
https://사이트주소/common/scripts/cron.php?key=발급된키
</syntaxhighlight>

<code>key</code> 값은 관리자 화면의 비동기 작업 설정에서 확인할 수 있다. 키가 맞지 않으면 <code>403 Forbidden</code>과 함께 <code>Invalid key</code>가 반환된다. 정상적으로 처리되면 <code>OK</code>가 출력된다.

웹크론을 쓸 때는 다음을 유의해야 한다.

* '''호출 간격이 php.ini의 실행 시간 제한(<code>max_execution_time</code>)을 넘지 않도록''' 해야 한다. 서버의 현재 값은 관리자 화면에 표시된다.
* '''웹크론으로 호출한 경우에는 멀티프로세싱을 지원하지 않는다.''' 프로세스 갯수를 2 이상으로 설정해도 하나만 실행된다.

== 실행 계정 ==
'''평소 웹서버를 실행하는 계정으로 crontab을 설정해야 한다.''' 보통 <code>apache</code>, <code>nginx</code>, <code>www-data</code> 등이다.<ref name="crontab" />

다른 계정이나 <code>root</code>로 실행하면 나중에 사이트에서 퍼미션 문제가 생기거나 캐시 파일이 꼬일 수 있다. 어느 계정을 써야 할지 모르겠다면 <code>files/config/config.php</code> 파일이나 <code>files/cache</code> 폴더의 소유자를 확인하자.<ref name="crontab" />

<syntaxhighlight lang="console">
ls -l files/config/config.php
</syntaxhighlight>

== 로그 확인 ==
위 예제를 따르면 실행 결과가 <code>files/cron.log</code>에 기록된다. '''crontab 설정 후 며칠간은 이 파일을 확인하며 정상 작동 여부를 점검하자.'''<ref name="crontab" />

<syntaxhighlight lang="console">
tail -f /설치경로/files/cron.log
</syntaxhighlight>

로그 파일이 무한정 커지지 않도록 logrotate를 함께 설정해 두면 좋다.

== 그 밖의 스크립트 ==
<code>common/scripts</code> 폴더에는 예전 이름의 스크립트 파일들(<code>clean_old_thumbnails.php</code> 등)도 남아 있다. 공식 매뉴얼의 일부 설명은 아직 이 이름을 사용한다.

또한 <code>module.updateAllModules</code> 스크립트가 있는데, 이는 모든 모듈의 업데이트를 수행하는 것으로 정기 실행용이 아니다. cron에 등록하지 말자.

== 같이 보기 ==

* [[라이믹스/매뉴얼]]
* [[라이믹스/매뉴얼/라이믹스 프레임워크]] — Queue 클래스
* [[라이믹스/설치]]
* [[라이믹스/매뉴얼/설치 환경]]

== 출처 ==
이 문서의 정리 스크립트 부분은 라이믹스 공식 매뉴얼의 [https://rhymix.org/manual/misc/crontab Crontab 설정 방법] 문서를 바탕으로 작성되었다. 공식 매뉴얼은 CC BY-SA 4.0 라이선스로 배포된다.<ref name="docs-license">[https://github.com/rhymix/rhymix-docs rhymix-docs 저장소] README에 "이 매뉴얼은 CC-BY-SA 4.0 라이선스에 따라 배포됩니다"라고 명시되어 있다.</ref>

비동기 작업 부분은 라이믹스 코어 소스([https://github.com/rhymix/rhymix/blob/master/common/scripts/cron.php common/scripts/cron.php], <code>common/framework/Queue.php</code>, <code>modules/admin/lang/ko.php</code>)를 확인하여 작성하였다.

== 각주 ==
<references />


[[분류:라이믹스]] [[분류:라이믹스/매뉴얼]]

라이믹스/매뉴얼/Crontab 설정 방법 - 편집 역사

Gaon12: 새 문서. 정리 스크립트와 비동기 작업(Queue) 실행 방법