[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,153 @@
+---
+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]]