cron 스케줄러 걸었더니 같은 작업이 두 번… 멱등성 때문이었습니다
cron 스케줄러 걸었더니 같은 작업이 두 번… 멱등성 때문이었습니다
자동화를 굴리다 보면 흔히 있는 상황인데, 5분마다 도는 동기화 작업이 어느 날 갑자기 7분씩 걸리기 시작하면서 같은 데이터를 두 번 처리했다는 사고를 주변에서 자주 듣습니다.
오늘은 스케줄러를 붙일 때 왜 멱등성부터 잡아야 하는지, 실제로 쓸 수 있는 방법까지 정리해 봅니다.
저도 처음엔 스케줄러 설정을 잘못 만진 줄 알았는데, 알고 보니 작업 자체의 설계 문제였습니다.
스케줄러는 "정확히 한 번"을 보장하지 않습니다
그런데 이 문제는 제 서버만의 이야기가 아니었습니다.
cron은 이전 실행이 끝났는지 확인하지 않습니다. 주기보다 실행 시간이 길어지는 순간 두 인스턴스가 동시에 같은 데이터를 만집니다.
심지어 관리형도 다르지 않습니다. Google Cloud Scheduler 공식 문서는 at-least-once delivery를 명시하면서, 같은 스케줄에 대해 작업이 여러 번 실행될 수 있으니 핸들러가 멱등이어야 한다고 요구합니다.
대신 Cloud Scheduler는 요청에 X-CloudScheduler-JobName과 X-CloudScheduler-ScheduleTime 헤더를 실어 보냅니다. 재시도 사이에도 원래 스케줄 시각이 그대로 유지되므로, 이 두 값을 키로 쓰면 핸들러에서 중복 요청을 걸러낼 수 있습니다.
스케줄러는 "정확히 한 번"을 보장하지 않습니다 다이어그램
락은 횟수를 줄이고, 멱등성은 결과를 지킵니다
막는 방법은 크게 두 갈래인데, 저는 이 둘의 역할이 다르다는 걸 뒤늦게 알았습니다.
가장 간단한 건 flock입니다. util-linux 기본 유틸이라 설치가 필요 없고, crontab에 */5 * * * * flock -n /tmp/job.lock /path/to/job.sh 한 줄이면 이전 실행이 살아있을 때 새 실행을 건너뜁니다. 프로세스가 죽어도 커널이 잠금을 풀어주니 stale PID 파일 문제도 없습니다.
다만 flock은 같은 파일을 공유하는 실행끼리만 유효해서, 서버가 두 대 이상이면 무력합니다. 이때부터는 DB 리스나 분산 락이 필요합니다.
| 방법 | 막아주는 것 | 남는 숙제 |
|---|---|---|
flock -n 잠금 | 같은 서버의 중복 실행 | 멀티 서버 무효, 실행 자체는 여전히 위험 |
| 멱등성 키 헤더 | API 중복 호출 | 키 생성·보관은 호출자 설계 |
| 클레임 테이블 + upsert | 재실행의 중복 쓰기 | 리스 만료·펜싱 관리 필요 |
| dedup 헤더 | 재시도 요청 식별 | 비교 로직을 핸들러가 구현 |
표를 보시면 아시겠지만 락은 '몇 번 도는가'를 줄일 뿐입니다. 진짜 멱등성은 두 번 실행돼도 결과가 같도록 작업을 바꾸는 데 있습니다.
제가 실제로 적용하는 순서는 이렇습니다.
- ▸작업의 부수효과를 전부 적습니다. DB 쓰기, 파일 이동, 메일 발송, 외부 API 호출까지.
- ▸각 항목에 "이게 두 번 일어나면?"을 묻고, append는 unique key upsert로 교체합니다.
- ▸실행 전
2026-10-23같은 기간 키로 클레임을 원자적으로 기록해 두 번째 실행을 스킵합니다. - ▸
timeout이나activeDeadlineSeconds로 실행 상한을 걸어 잠금이 영원히 잡히는 걸 막습니다. - ▸외부 API에는 멱등성 키를 붙입니다. Stripe는 255자 이내 UUID를 받고 같은 키의 재시도에 저장된 응답을 돌려줍니다.
비용도 부담이 없습니다. Cloud Scheduler는 실행 횟수가 아니라 job 정의당 $0.10/31일이고 계정당 3개는 무료입니다. 다만 일시중지한 job도 과금되니 안 쓰는 건 삭제하는 게 맞습니다. flock은 공짜입니다.
정리하면, 스케줄러는 '최소 한 번'만 약속하고 결과의 동일성은 우리 작업이 책임져야 합니다. 시작하려면 오늘 crontab에서 제일 오래 도는 작업 하나를 골라 flock -n 한 줄부터 붙여 보시길 권합니다.
락은 횟수를 줄이고, 멱등성은 결과를 지킵니다 다이어그램
※ 이 글은 개인적인 자동화 경험과 공개된 정보를 바탕으로 작성했습니다. 도구·서비스의 기능은 변경될 수 있습니다.