웹 앱에서 백그라운드 작업 실행하는 법: 큐, 스케줄러, cron

웹 앱에서 백그라운드 작업을 실행하려면 먼저 작업을 두 종류로 나누세요. 트리거형 작업(환영 이메일 발송, 업로드 처리)은 작업 큐, 보통 데이터베이스의 테이블에 저장해 두고, 재시도 기능이 있는 워커가 처리할 수 있습니다. 예약형 작업(야간 보고서, 15분마다 알림)은 정해진 시간에 실행될 무언가가 필요합니다. 호스트의 cron 기능이나, 앱의 보호된 엔드포인트를 호출하는 외부 스케줄러가 그것입니다. 작업은 항상 두 번 실행되어도 안전하게 만들고, 실패를 기록하고, 잠들거나 재시작할 수 있는 서버 안의 타이머에 의존하지 마세요.

이 가이드는 각 선택지가 언제 맞는지, 그리고 0으로 스케일링하는 호스트를 포함해 AI 앱 빌더로 어떻게 설정하는지 설명합니다.

백그라운드 작업에 해당하는 것

사용자의 즉각적인 응답에 필요하지 않은, 느리거나 불안정하거나 중요하지 않은 모든 작업입니다.

• 이메일, 알림, 영수증 발송
• 이미지 크기 조정, 동영상 변환, PDF 생성
• 느린 제3자 API 호출. 긴 작업을 위한 AI 모델 호출 포함
• 다른 시스템의 데이터 가져오기 또는 동기화
• 야간 정리, 보고서, 리마인더

이 작업들을 요청 안에서 처리하면 페이지가 느려지고 취약해집니다. 이메일 제공업체가 다운되면 사용자의 가입도 실패합니다. 백그라운드로 옮기면 사용자는 즉시 응답을 받고, 작업은 재시도될 수 있습니다.

선택지

정답은 하나가 아닙니다. 작은 앱에는 데이터베이스 큐와 외부 스케줄러 조합이면 충분한 경우가 많습니다.

0으로 스케일링하는 호스트에서 달라지는 점

많은 최신 호스트는 아무도 앱을 쓰지 않을 때 앱을 재우고, 다음 요청에 깨웁니다. 이는 돈을 아껴 주지만, 잠든 서버는 어떤 코드도 실행하지 않습니다. 타이머는 울리지 않고, 워커는 폴링하지 않습니다. 이런 호스트에서 예약 작업은 들어오는 요청에서 시작되어야 하며, 가장 쉬운 요청 출처는 외부 스케줄러입니다. 호출할 때마다 앱(그리고 종종 데이터베이스)이 깨어나므로, 1분마다 호출하는 것은 15분마다 호출하는 것보다 비쌉니다. 필요를 충족하는 가장 느린 일정을 고르세요.

패턴 1: 데이터베이스 작업 큐

트리거형 작업을 위한 방법입니다.

1. jobs 테이블을 만드세요. 유형, 페이로드(JSON), 상태(pending, running, done, failed), 시도 횟수, run_after, last_error, 타임스탬프를 넣습니다.
2. 무언가 일어나면, 그 변화를 일으킨 것과 같은 트랜잭션에서 작업 행을 삽입하세요. 그래야 함께 성공하거나 함께 실패합니다.
3. 워커가 실행 시점이 된 작업을 가져와 running으로 표시하고, 작업을 수행한 뒤 done으로 표시합니다.
4. 실패하면 시도 횟수를 늘리고, run_after를 더 뒤로 설정하고(예: 1분, 5분, 30분 뒤), 오류를 저장하세요. 최대 횟수를 넘으면 failed로 표시하고 누군가에게 알립니다.

워커가 여러 개 동시에 돌 수 있다면 작업을 안전하게 가져가야 합니다. Postgres에서는 SELECT ... FOR UPDATE SKIP LOCKED를 쓰면 각 워커가 서로 충돌하지 않고 다른 행을 가져갈 수 있습니다.

워커는 무엇이 실행하나요? 항상 켜져 있는 서버라면 별도 프로세스의 루프입니다. 0으로 스케일링하는 호스트에서는 패턴 2의 예약 엔드포인트가 호출될 때마다 실행 시점이 된 작업을 한 묶음 처리할 수 있습니다.

패턴 2: 앱을 호출하는 외부 스케줄러

예약형 작업을 위한 방법입니다.

1. POST /api/cron/send-reminders 같은 엔드포인트를 추가하세요.
2. 보호하세요. 헤더에 비밀 토큰을 요구하고, 양쪽에 비밀 값으로 저장하며, 그 밖의 모든 요청은 거부하세요.
3. 멱등하게 만드세요. 같은 분에 두 번 실행해도 리마인더가 두 번 나가면 안 됩니다. 무엇을 보냈는지 기록하세요.
4. 각 호출은 짧게 유지하세요. 한 묶음(예: 100개)을 처리하고, 나머지는 다음 호출이 맡게 합니다.
5. 스케줄러를 여기에 연결하세요.

스케줄러 선택지는 다음과 같습니다.

• GitHub Actions 예약 워크플로. GitHub 사용량 한도 안에서 무료입니다. GitHub 문서에 따르면 2026년 9월 기준 가장 짧은 간격은 5분에 한 번이며, 사용량이 많을 때(특히 매시 정각) 실행이 지연될 수 있고, 기본적으로 일정은 UTC를 사용하며, 공개 저장소의 예약 워크플로는 저장소 활동이 60일 동안 없으면 비활성화됩니다.
• 호스팅 cron 서비스. 일정에 따라 URL을 호출하는 것만 하는 서비스가 많이 있습니다. 의존하기 전에 안정성, 최소 간격, 알림 기능을 확인하세요.
• 클라우드 제공업체의 스케줄러. 이미 대형 클라우드 제공업체를 쓰고 있다면, HTTPS 엔드포인트를 호출할 수 있는 관리형 스케줄러가 있을 것입니다.
• 호스팅 작업 또는 워크플로 서비스. 스케줄링, 큐, 재시도를 합친 서비스로, 각 단계마다 엔드포인트를 호출합니다. 가격과 한도는 각 공급업체 사이트에서 비교하세요.

패턴 3: 제공업체에 맡기기

때로는 가장 좋은 백그라운드 작업이 아예 없는 것입니다.

• 결제. Stripe는 실패한 구독 결제를 재시도하고 웹훅을 보냅니다. 폴링하지 말고 그 결과에 반응하세요. 웹훅이란 무엇인가를 보세요.
• 이메일. 메시지를 넘겨주면 제공업체가 배달을 큐에 넣고 재시도합니다.
• 대량 AI 작업. OpenAI와 Anthropic은 긴급하지 않은 요청을 제출하고 나중에 결과를 받을 수 있는 배치 API를 제공합니다.

AI 빌더에 줄 프롬프트

큐를 만들 때:

데이터베이스에 jobs 테이블을 사용한 백그라운드 작업 큐를 추가해 줘(유형, 페이로드 JSON, 상태, 시도 횟수, run_after, last_error). 사용자가 가입하면 인라인으로 이메일을 보내는 대신 같은 트랜잭션에서 send_welcome_email 작업을 삽입해 줘. processJobs(limit) 함수를 추가하고, SELECT ... FOR UPDATE SKIP LOCKED로 실행 시점이 된 작업을 가져와 실행하게 해 줘. 실패하면 1분, 5분, 30분 뒤에 재시도하고, 4번 시도 후에는 failed로 표시해 줘.

예약 트리거를 만들 때:

비밀 CRON_SECRET의 베어러 토큰으로 보호되는 POST /api/cron/tick을 추가해 줘. 토큰이 없는 요청은 모두 거부해. 호출될 때마다 processJobs(100)을 실행하고, 앞으로 24시간 안에 있고 아직 보내지 않은 예약 알림을 보내 줘. 보낸 알림은 기록해서 두 번 보내지 않게 하고, 무엇이 실행되었는지 요약한 JSON을 반환해 줘. 그다음 이 엔드포인트를 15분마다 호출하는 GitHub Actions 워크플로를 작성하되, URL과 토큰은 저장소 시크릿에서 읽게 해 줘.

흔한 실수

• setInterval에 의존하기. 서버가 잠들거나 재시작하면 조용히 멈추고, 복사본이 둘 이상 돌면 중복 실행됩니다.
• 보호되지 않은 cron 엔드포인트. 누구든 찾으면 작업을 트리거할 수 있고, 이메일 요금도 그 사람이 만들 수 있습니다.
• 멱등하지 않은 작업. 재시도와 중복 스케줄러 호출은 반드시 일어납니다. 그것을 고려해 설계하세요.
• 실패가 보이지 않음. 일주일 동안 조용히 실패하는 작업은 큰 소리로 실패하는 작업보다 나쁩니다. 오류를 기록하고, 반복 실패에 알림을 설정하세요.
• 요청 하나에 긴 작업 몰아넣기. 요청은 시간 초과됩니다. 묶음으로 처리하세요.
• 너무 자주 예약하기. 0으로 스케일링하는 호스트에서는 호출마다 앱이 깨어나 요금이 발생합니다. 간격을 실제 필요에 맞추세요.
• 시간대. "오전 9시"는 스케줄러(보통 UTC)와 사용자에게 다른 의미입니다. 시간은 UTC로 저장하고, 사용자별로 변환하세요.
• 워크플로 파일에 비밀 값 넣기. 토큰은 스케줄러의 비밀 저장소에 보관하세요. API 키를 안전하게 보관하는 법을 보세요.

체크리스트

• 느린 작업을 사용자 요청에서 분리했다
• 작업은 메모리에만 있지 않고 내구성 있게 저장된다
• 재시도에는 점점 길어지는 지연과 최대 횟수가 있다
• 모든 작업은 두 번 실행해도 안전하다
• 예약 엔드포인트는 비밀 토큰으로 보호된다
• 각 실행은 경계가 있는 묶음만 처리한다
• 실패한 작업은 눈에 보이고, 알림이 있다
• 예약 간격은 호스팅 비용을 고려해 골랐다
• 시간은 UTC로 저장된다

Mythex에서 백그라운드 작업

Mythex 문서에는 예약 작업이나 cron 작업이 설명되어 있지 않고, 게시된 앱과 데이터베이스는 유휴 상태일 때 잠들었다가 다음 요청에 깨어납니다(호스팅 한도 참고). 그러니 앱 안의 타이머에 의존하지 마세요. 효과가 있는 방법은 위에서 설명한 방식입니다. 에이전트에게 jobs 테이블과 토큰으로 보호된 엔드포인트를 만들어 달라고 요청하고, 외부 스케줄러가 게시된 URL을 가리키게 하세요. 토큰은 프로젝트 시크릿으로 저장하고, 깨어날 때마다 앱과 데이터베이스가 깨어 있던 시간만큼 크레딧이 쓰인다는 점을 기억해서 합리적인 간격을 고르세요. 이를 위해 API 백엔드가 필요하다면 REST API 백엔드 레시피가 출발점이 되고, 엔드포인트 설계는 REST API 만드는 법에서 다룹니다. 제품의 핵심이 상시 실행되는 워커나 봇이라면, 지속적으로 실행되는 프로세스에 맞춘 호스트가 더 적합할 수 있습니다.

자주 묻는 질문