ADR-0017: 정비 뉴스 크롤러 실행을 GitHub Actions 에서 Vercel Cron(서울 리전 icn1)으로 옮긴다
- Status: Accepted
- Date: 2026-10-07
- 관련: HMH-9743 (이 ADR) · HMH-9561 (코어 API 국외 IP 차단) · ADR-0006 (파이프라인 설계 — 실행 위치만 이 ADR 로 개정) · ADR-0001 (데이터 소유 경계)
Context
ADR-0006 은 정비 뉴스 크롤 파이프라인을 GitHub Actions 스케줄에서 돌리기로 했다. 그 결정의 “실행 위치” 축에서 Vercel Cron 을 탈락시킨 이유는 단 하나 — 크롤 N건 + LLM 요약이 당시 함수 타임아웃(~300s대)에 걸리기 쉬웠기 때문이다.
그 전제가 두 가지로 바뀌었다.
- 외부 제약(HMH-9561): 코어 API 국외 IP 차단. 코어 API ALB 가
/admin/*와/api/v*/dashboard/*를 KR IP 에서만 허용하도록 바뀐다. 크롤러는 요약 결과를POST /admin/v1/news-brief/*로 적재하므로, 앞으로는 KR egress IP 에서 실행돼야 한다. 그런데 GitHub Actions 러너는 미국(Azure)의 로테이팅 IP 라 allowlist 에 고정할 수 없다 — GA 유지는 사실상 불가능해진다. - 타임아웃 전제 완화. Vercel Pro 의 fluid compute 로 함수
maxDuration을 800s 까지 늘릴 수 있고, 요약을 병렬화하면 실행시간이 더 짧아진다.
측정(GA 실제 런, 예: Actions run 37562976843): 세팅 ~405s + crawl 스텝 ~842s. crawl 스텝 내부는 수집 ~108s, Claude 요약 ~558s(9.3분, 지배적 병목), POST ~29s. 즉 병목은 요약 호출이고 수집·게시는 작다 — 이게 아래 “어댑터별 분리로는 단축 안 됨” 판단의 근거다.
검토한 대안
| 대안 | 채택 안 한 이유 |
|---|---|
| GA 유지 + 고정 KR IP 프록시/NAT 게이트웨이 | KR 고정 IP 인프라를 새로 운영·관측해야 하고, GA→프록시→백엔드로 홉이 늘어 실패 지점이 추가된다. KR egress 가 필요한 것뿐이라면 Vercel 서울 리전(icn1)이 이미 그 자리에 있다 |
| 어댑터별 크론 분리(소스마다 별도 라우트) | 교차 소스 중복판정(dedup)과 N→M 토픽 병합이 한 런 안에서 일어나야 하는데 분리하면 깨진다. 게다가 병목은 공유 단계인 요약이라, 소스를 쪼개도 전체 실행시간이 줄지 않는다(측정 근거 위) |
| Vercel Edge 런타임 / 다른 리전 | 백엔드가 KR IP 만 허용하므로 서울(icn1)이 강제된다. Edge 런타임은 Node API(node:crypto·Neon 드라이버·스트리밍 요약)에 제약이 있어 Node 런타임이 필요하다 |
Decision
크롤 파이프라인(ADR-0006 의 crawl → dedup(Neon) → 배치 요약(Claude) → 적재)은 그대로 두고, 실행 위치만 GitHub Actions → Vercel Cron(서울 리전 icn1) 으로 옮긴다.
- 단일 라우트:
apps/api/src/app/cron/news-crawler/route.ts—runtime=nodejs,preferredRegion='icn1'(= KR egress IP, HMH-9561 대응의 핵심),maxDuration=800,CRON_SECRETBearer 를 timing-safe 로 검증. 이 라우트가runCrawl()을 호출한다. - 파이프라인 함수화:
packages/news-crawler/src/run.ts의 CLImain()을export runCrawl()로 추출(요약 결과 요약치를 반환). tsx CLI 는import.meta.url === argv[1]가드로 직접 실행될 때만 돈다(라우트가 import 해도 파이프라인이 돌거나process.exit가 불리지 않게). db 는 모듈 최상위 await 대신runCrawl실행 시 동적 import 로 1회 로드(Next/webpack 번들에서 TLA 취약성 회피). - 요약 배치 병렬화:
SUMMARIZE_CONCURRENCY(기본 3)로 요약 호출만 동시에 돌리고, 결과는 입력 순서대로 순차 처리(DB 쓰기·병합). 이때 배치 간(런 내) placeholder 중복방지는 포기한다 — 같은 사안 기사는 보통 한 배치에 모이고 일반 런은 단일 배치라 영향이 작다. cross-run 중복방지와 merge(직전 런 브리프 대상)는 그대로 유지된다. - 스케줄:
apps/api/vercel.json의 crons 2개 —10 2 * * *(02:10 UTC = 11:10 KST,?slot=morning),10 9 * * *(09:10 UTC = 18:10 KST,?slot=evening).?slot쿼리는 Vercel 크론 path 유니크 + 관측 라벨일 뿐이고, 푸시 여부는resolvePushSlot(KST)이 정한다 — 점심 런은 목록만, 저녁 런만 EVENING 푸시(기존 GA 스케줄 동작과 동일). - 프롬프트 인라인: 편집 규칙 전문을
news-brief-prompt.md(런타임readFileSync) →news-brief-prompt.ts상수로 인라인한다. 번들에서import.meta.url기반 경로가 깨지는 문제를 원천 제거(단일 소스 유지). - 번들 포함: news-crawler 는 ESM raw-TS 워크스페이스 패키지라
apps/api/next.config.ts의transpilePackages에 추가한다.
이관 기간: 안전을 위해 GitHub Actions 스케줄을 당분간 유지(Vercel 과 병행 검증)하고, Vercel 쪽이 정상 적재·푸시를 내는 걸 확인한 뒤 GA 스케줄을 제거한다. 병행 중 실 데이터는 GA 가 쌓고, Vercel 크론은 dry-run 으로 동작·데이터 흐름만 확인한다 — runCrawl({dryRun}) 은 수집·중복조회(read)·요약(Claude)까지는 실제로 돌려 “무엇이 적재될지”를 로그로 미리보되 DB write·백엔드 POST 를 전혀 하지 않는다. 켜는 법: env NEWS_CRAWLER_DRY_RUN=1(스케줄 런 전체) 또는 쿼리 ?dry=1(수동 curl 단건). GA 는 그 env 가 없어 늘 실 적재. 라이브 전환 = Vercel 의 NEWS_CRAWLER_DRY_RUN 제거 + GA 스케줄 삭제.
이관 완료(2026-10-07): 프로덕션 dry-run 검증(저녁 크론 정시 실행·DB 쓰기 0건·토픽 GA 동등) 후 GA schedule 트리거를 제거(HMH-9766) — news-brief-crawl.yml 은 수동 workflow_dispatch 만 남긴다.
워크플로 제거(2026-10-20, HMH-10103): 그 수동 workflow_dispatch 워크플로(news-brief-crawl.yml)도 삭제했다 — GA 러너는 미국 IP 라 HMH-9561(코어 API 국외 IP 차단)로 /admin/v1/news-brief 적재가 막혀 수동 실행도 실효가 없었다(백필은 Vercel /cron/news-crawler?dry=). 정기 실행(Vercel Cron)은 그대로다.
런 내 중복방지 완화(2026-10-20, HMH-10111): 아래 “감수하는 것”의 배치 간(런 내) 중복방지 포기 가 뉴스 많은 날엔 실제로 중복 브리프를 냈다(2026-10-20 저녁 런: 29기사→28브리프, 토큰 장애 백로그 플러시로 평소 2배 → 모아주택 조합설립 1억·목동10단지 시공사·여의도 시범 시공사 3클러스터). 배치 병렬화는 유지하되, 게시 직전에 이번 런 브리프를 한 번 더 LLM 으로 묶는 consolidation 패스(consolidate.ts)를 run.ts 3.4 단계로 넣어 같은 사안을 대표 1개로 접는다(나머지 매체 references·멤버 기사 id 를 대표로 이전). placeholder 순차 주입(원래 포기한 방식)을 되살리지 않아 병렬화 이득은 그대로이고, cross-run merge(직전 런 대상)와도 역할이 분리된다.
⚠️ 안전 전환 순서(실 적재 공백 방지) — GA
schedule제거는 ①의 후행이어야 한다: ① VercelNEWS_CRAWLER_DRY_RUN제거(실 적재 전환, 머지 전 필수) → ② Vercel 실 적재 1회 확인 → ③ GAschedule제거(HMH-9766) 머지. GA 제거를 ①보다 먼저 하면NEWS_CRAWLER_DRY_RUN이 남은 동안 Vercel 정기 실행도 DB write·POST 를 안 해 아무도 실 적재를 안 하는 공백이 난다. 전환 완료 후 HMH-9561 담당자에게 국외 IP 차단(BLOCK) 통지.
Consequences
좋아지는 것
- 크롤러가 KR IP(icn1) 에서
/admin을 호출 → HMH-9561 국외 차단의 영향을 받지 않는다 - 실행 표면이 Vercel 로 통합된다 — ADR-0006 이 “감수하는 것”으로 적었던 “Vercel 밖 GitHub Actions 실행 표면이 하나 늘었다” 가 해소된다(시크릿·관측이 Vercel 한 곳)
- 요약 병렬화로 다배치 런의 실행시간이 줄어든다
감수하는 것
- Vercel 함수 타임아웃에 묶인다(
maxDuration=800, fluid compute 전제). 대형 백필은 한 번에 못 돌 수 있어 분할/수동 실행이 필요하다 - 배치 간(런 내) placeholder 중복방지를 포기한다(영향은 작음 — 위 Decision). → 뉴스 많은 날엔 중복이 실제로 나, 게시 전 consolidation 패스로 완화했다(위 HMH-10111 노트)
- 운영 셋업: 시크릿 5종(DATABASE_URL·ANTHROPIC_API_KEY·FIRECRAWL_API_KEY·NEWS_BOT_ADMIN_TOKEN·HOWMUCHHOME_API_URL)과
CRON_SECRET을 Vercel front-api env 로 옮겨야 한다 - front-api 번들에 크롤러 의존성(@anthropic-ai/sdk·cheerio 등)이 포함된다(해당 라우트 lambda 한정)
이 결정을 다시 열어야 할 때
- 백필 등으로
maxDuration=800을 넘기면 → 큐/워커로 분리하거나 분할 실행 - HMH-9561 이 철회되거나, 백엔드가 IP 대신 서버-투-서버 토큰 기반 허용으로 바뀌면 → 실행 위치를 다시 열어도 된다
- Anthropic rate limit 이
SUMMARIZE_CONCURRENCY=3에서 막히면 → 동시성·배치 크기 재조정