Antigravity Agent
154 lines
4.4 KiB
Markdown
154 lines
4.4 KiB
Markdown
---
|
|
id: backend-cron-patterns
|
|
title: Cron / Scheduled Jobs — 분산 / 멱등 / 락
|
|
category: Coding
|
|
status: draft
|
|
source_trust_level: B
|
|
verification_status: conceptual
|
|
created_at: 2026-05-09
|
|
updated_at: 2026-05-09
|
|
tags: [backend, cron, scheduler, idempotency, vibe-coding]
|
|
tech_stack: { language: "TS / SQL / Redis", applicable_to: ["Backend"] }
|
|
applied_in: []
|
|
aliases: [scheduled job, periodic, cron expression, distributed lock, leader election]
|
|
---
|
|
|
|
# Cron / Scheduled Jobs
|
|
|
|
> 분산 환경 cron = **leader 락 + 멱등** 안 하면 N대 서버에 N번 실행. **DB row lock / Redis lock / Kubernetes CronJob / 클라우드 매니지드 스케줄러** 중 1개. 매 실행 멱등.
|
|
|
|
## 📖 핵심 개념
|
|
- Single instance: 한 시점에 한 곳만 실행.
|
|
- Idempotent: 두 번 실행돼도 결과 동일.
|
|
- Catch-up: 시간 지나가면 늦게라도 실행할지 / skip 할지.
|
|
- At-least-once: 보통 OK, 단 멱등 보장 필요.
|
|
|
|
## 💻 코드 패턴
|
|
|
|
### node-cron / BullMQ repeat
|
|
```ts
|
|
import { Queue } from 'bullmq';
|
|
|
|
const q = new Queue('reports');
|
|
await q.add('daily', {}, {
|
|
repeat: { pattern: '0 9 * * *', tz: 'America/New_York' }, // 매일 9시 NY
|
|
jobId: 'daily-report', // 같은 jobId = 중복 등록 방지
|
|
});
|
|
```
|
|
|
|
### DB-based lock
|
|
```sql
|
|
-- locks 테이블
|
|
CREATE TABLE job_locks (
|
|
name TEXT PRIMARY KEY,
|
|
locked_by TEXT,
|
|
locked_at TIMESTAMPTZ,
|
|
expires_at TIMESTAMPTZ
|
|
);
|
|
|
|
-- 시도
|
|
INSERT INTO job_locks (name, locked_by, locked_at, expires_at)
|
|
VALUES ('daily-report', $hostname, NOW(), NOW() + INTERVAL '10 minutes')
|
|
ON CONFLICT (name) DO UPDATE
|
|
SET locked_by = $hostname, locked_at = NOW(), expires_at = NOW() + INTERVAL '10 minutes'
|
|
WHERE job_locks.expires_at < NOW()
|
|
RETURNING *;
|
|
```
|
|
|
|
```ts
|
|
async function runWithLock(name: string, fn: () => Promise<void>) {
|
|
const got = await db.tryLock(name, hostname());
|
|
if (!got) return; // 다른 노드가 잡음
|
|
try { await fn(); } finally { await db.releaseLock(name); }
|
|
}
|
|
```
|
|
|
|
### Redis-based lock (Redlock)
|
|
```ts
|
|
import Redlock from 'redlock';
|
|
|
|
const lock = await redlock.acquire(['locks:daily-report'], 60_000);
|
|
try { await runDaily(); } finally { await lock.release(); }
|
|
```
|
|
|
|
### Idempotency
|
|
```ts
|
|
async function dailyReport(date: string) {
|
|
const id = `report:${date}`;
|
|
if (await db.exists(id)) return; // 이미 만들어짐
|
|
const r = await build(date);
|
|
await db.put(id, r);
|
|
}
|
|
```
|
|
|
|
### Catch-up
|
|
```ts
|
|
// 마지막 실행 시간 저장 → 차이만큼 반복
|
|
const last = await db.get('cursor:reports');
|
|
for (let d = nextDay(last); d <= today(); d = nextDay(d)) {
|
|
await dailyReport(d);
|
|
await db.put('cursor:reports', d);
|
|
}
|
|
```
|
|
|
|
### Kubernetes CronJob
|
|
```yaml
|
|
apiVersion: batch/v1
|
|
kind: CronJob
|
|
metadata:
|
|
name: daily-report
|
|
spec:
|
|
schedule: "0 9 * * *"
|
|
concurrencyPolicy: Forbid # 이전 job 안 끝났으면 새거 skip
|
|
successfulJobsHistoryLimit: 3
|
|
failedJobsHistoryLimit: 5
|
|
startingDeadlineSeconds: 600 # 10분 안에 시작 안되면 skip
|
|
jobTemplate:
|
|
spec:
|
|
backoffLimit: 2
|
|
template:
|
|
spec:
|
|
containers:
|
|
- name: report
|
|
image: app:latest
|
|
args: ["node", "dist/jobs/daily-report.js"]
|
|
restartPolicy: OnFailure
|
|
```
|
|
|
|
### Cron expression (UTC vs local)
|
|
```
|
|
0 9 * * * # 매일 9:00 UTC (서버 타임존이 UTC면)
|
|
0 9 * * 1-5 # 평일 9시
|
|
*/15 * * * * # 15분마다
|
|
0 0 1 * * # 매월 1일
|
|
```
|
|
|
|
## 🤔 의사결정 기준
|
|
| 환경 | 추천 |
|
|
|---|---|
|
|
| Vercel / Cloudflare | Vercel Cron / CF Cron |
|
|
| AWS | EventBridge → Lambda |
|
|
| K8s | CronJob + concurrencyPolicy: Forbid |
|
|
| 단일 Node | node-cron + DB lock |
|
|
| 큐 기반 | BullMQ repeat / Sidekiq |
|
|
| 정확한 시간 보장 X | drift 감수 또는 클라우드 |
|
|
|
|
## ❌ 안티패턴
|
|
- **N대 서버에 cron 동시 실행**: 단일 락 또는 leader 만.
|
|
- **Idempotency 미보장**: 재실행 시 데이터 망가짐.
|
|
- **타임존 confusion**: UTC 명시 또는 cron expression 에 tz.
|
|
- **Long-running job 크론에서**: 다음 실행 충돌. 큐로 보내기.
|
|
- **Catch-up 무한**: 24시간 정지 후 돌아오면 1440번 실행.
|
|
- **Job 결과 남기지 않음**: 실패 추적 불가.
|
|
- **At-most-once 가정**: 분산 = 항상 at-least-once.
|
|
|
|
## 🤖 LLM 활용 힌트
|
|
- 항상 멱등 + 락 + 결과 기록.
|
|
- K8s CronJob = concurrencyPolicy: Forbid.
|
|
- 시간 = UTC 또는 명시 tz.
|
|
|
|
## 🔗 관련 문서
|
|
- [[Backend_Job_Queue_Patterns]]
|
|
- [[Idempotency_Patterns]]
|
|
- [[Distributed_Locking_Patterns]]
|