크론 작업
정해진 시간마다 앱의 경로를 자동으로 호출합니다.
크론 작업은 "매일 새벽 5시에 /api/cleanup 호출"처럼 정해진 시간마다 앱의 경로로 GET 요청을 보내는 기능입니다. 콘솔이나 크론 작업 API로 등록하거나, 배포 루트의 nitroship.json(또는 vercel.json)에 선언할 수 있습니다.
{
"crons": [
{"path": "/api/cron?source=scheduled", "schedule": "0 5 * * *"}
]
}이 예시는 매일 UTC 05:00(한국 시간 14:00)에 /api/cron?source=scheduled를 호출합니다.
프로덕션 배포에서만 실행됩니다
크론은 현재 준비된 프로덕션 배포로만 요청을 보냅니다. 프리뷰 배포에서는 실행되지 않습니다. nitroship.json 변경은 프로덕션 배포가 필요하지만, 콘솔·API 변경은 배포 없이 즉시 적용됩니다.
콘솔에서 크론 관리하기
앱의 App Settings > Cron Jobs에서 작업을 추가·수정·삭제한 뒤 목록을 저장하세요. 현재 프로덕션 배포에 즉시 적용됩니다. PUT /v1/apps/{appId}/crons로 목록 전체를 교체할 수도 있으며, {"crons": []}를 보내면 모든 작업을 삭제합니다.
nitroship.json에 크론이 선언되어 있어도 콘솔·API 수정은 언제든 가능합니다. 저장한 목록은 다음에 crons를 선언한 프로덕션 배포가 나올 때까지 우선합니다. 그런 배포를 할 때마다 파일의 목록이 다시 콘솔·API 설정보다 우선합니다. 크론을 선언한 배포로 재배포·승격·롤백해도 해당 배포의 목록이 다시 적용됩니다.
- 명시적인
"crons": []도 빈 목록의 선언이므로 콘솔 작업보다 우선합니다. crons를 선언하지 않은 배포는 저장된 콘솔 목록을 사용합니다.- 콘솔에서 계속 관리하려면
nitroship.json의crons키를 지우고 배포하세요. 콘솔에서만 작업을 삭제해도 파일에서는 삭제되지 않습니다.
vercel.json도 같은 규칙을 따릅니다. 첫 프로덕션 배포 전에도 작업을 저장할 수 있지만, 준비된 프로덕션 배포가 있어야 실행됩니다.
일정(schedule) 쓰는 법
시간대는 항상 UTC이고, 다섯 칸(분 시 일 월 요일)으로 씁니다.
| 예시 | 뜻 |
|---|---|
0 5 * * * | 매일 05:00 |
*/10 * * * * | 10분마다 |
0 9 * * 1-5 | 평일 09:00 |
0 0 1,15 * * | 매달 1일과 15일 00:00 |
- 숫자,
*, 범위(1-5), 목록(1,15), 간격(*/10)을 쓸 수 있습니다. MON·JAN같은 이름,@daily같은 별칭, 초를 포함한 6칸 형식은 지원하지 않습니다.- 일과 요일을 동시에 지정할 수 없습니다. 둘 중 하나는
*여야 합니다.
path는 /로 시작해야 하며 쿼리 문자열을 넣을 수 있습니다. 한 앱에 최대 100개까지 등록할 수 있습니다.
실행에 실패하면
정해진 시각에 실행하지 못하면 그 회차는 건너뛰고, 자동으로 다시 시도하지 않습니다. 꼭 실행되어야 하는 작업이라면 앱 쪽에서 밀린 작업을 처리하도록 만드세요.
크론 요청만 받도록 막기
크론 경로는 공개 주소라 누구나 호출할 수 있습니다. 크론에서 온 요청인지 확인하려면:
- 프로덕션 환경 변수에
CRON_SECRET을 추가합니다. - 새로 배포합니다.
- 이제 크론 요청에는
Authorization: Bearer <CRON_SECRET>헤더가 붙습니다. 엔드포인트에서 이 값을 검사하세요.
요청의 User-Agent는 nitroship-cron/1.0이지만, 누구나 흉내 낼 수 있으므로 인증 용도로 쓰지 마세요.
등록된 일정 확인
GET /v1/apps/{appId}/crons API로 실제 적용된 일정, 다음 실행 시각과 마지막 실행, 그리고 출처(source)가 "config", "console", "none" 중 무엇인지 볼 수 있습니다. configDeclared는 콘솔 수정이 현재 우선하더라도 프로덕션 배포에 크론이 선언되어 있는지 알려 줍니다. 자세한 내용은 크론 작업 API 문서를 참고하세요.