any4ai/anycrawl 딥다이브
— "웹사이트를 LLM 먹이로" 바꾸는 오픈소스 크롤링 SaaS 백엔드

1프로젝트 한 줄 요약

README만 보면 "스크래핑 라이브러리"처럼 읽히지만, 실제 저장소 구조는 완전한 SaaS 백엔드의 모양을 하고 있다. API 키 발급·크레딧 차감(billingLedger), 웹훅 구독/재전송, cron 기반 예약 작업(scheduledTasks), 그리고 웹페이지 변경 감지(모니터)까지 DB 스키마 레벨에 1급 시민으로 존재한다. 즉 anycrawl.dev가 파는 호스팅 서비스와 자가 호스팅용 오픈소스가 같은 코드베이스다 — Docker Compose 한 줄로 로컬에 그대로 띄울 수 있다.

2왜 주목받는가 — Firecrawl·Crawl4AI와 뭐가 다른가

2026년 "LLM을 위한 웹 크롤러" 카테고리는 이미 붐비는 시장이다 — 호스팅 중심의 Firecrawl, 파이썬 진영의 Crawl4AI, 그리고 AnyCrawl이 나란히 언급된다. AnyCrawl의 GitHub 소개 문구조차 "Google/Bing/Baidu 등에서 구조화된 SERP를 추출한다"고 홍보하지만, 실제 오픈소스로 공개된 packages/search를 열어보면 직접 구현된 건 Google(cheerio로 google.com/search HTML을 직접 파싱)과 SearXNG(자체 호스팅 메타서치, 운영자가 붙여둔 엔진에 따라 Bing·DuckDuckGo 등을 간접 커버) 클라이언트뿐이고, Bing·Baidu 자체 파서는 없다 — 대신 ACEngine.ts라는 호스팅형 멀티 엔진 백엔드로 위임하는 얇은 HTTP 클라이언트가 있다. README를 그대로 믿지 않고 소스로 확인해야 하는 대표적인 사례다.

기존 도구와의 결정적 차이

주목 포인트 4가지

① 엔진 3종 + 자동판별. engine: "auto"로 보내면 서버가 먼저 가벼운 HTTP GET으로 HTML을 5초 안에 받아 "JS가 꼭 필요한가"를 채점한 뒤 cheerio/Playwright 중 하나로 라우팅한다(4장에서 코드로 확인). README에는 나오지 않는, 소스에만 있는 기능이다.

② 진짜로 동작하는 안티봇 대응. Cloudflare Turnstile을 CDP로 감지하고 2captcha로 풀며, 성공한 cf_clearance 쿠키를 캐싱해 재사용한다. 프록시도 "일반(base)"과 "스텔스(stealth)" 두 단계로 나눠 자동/수동 승급시킨다.

③ "스크래퍼"를 넘어선 제품 범위. 예약 작업(cron)·웹훅 구독·모니터(주기적으로 재방문해 변경분만 diff)·사용자 커스텀 스크립트를 위한 샌드박스까지 — Firecrawl이 최근 붙이기 시작한 기능들을 처음부터 DB 스키마 레벨에서 준비해 뒀다.

④ MCP 서버 지원. anycrawl-mcp라는 별도 패키지(npx -y anycrawl-mcp)와 호스팅 엔드포인트(mcp.anycrawl.dev/{API_KEY}/mcp)로 Claude Desktop·Cursor·VS Code에서 바로 크롤링 도구를 쓸 수 있다 — 단, 이 MCP 서버 자체의 소스코드는 이 모노레포 안에 없고 문서(apps/docs)만 존재한다는 점은 분석 중 확인한 사실이다.

3기술 스택 전체 지도

저장소는 pnpm + Turborepo 모노레포다. 앱은 2개(apps/api, apps/docs), 패키지는 9개(packages/*)로 나뉘어 있고, TypeScript 소스만 221개 파일·테스트를 제외하고도 약 5.6만 줄에 달한다.

① 백엔드 API (apps/api)

② 크롤링 엔진 (packages/scrape) — 이 레포의 핵심

③ AI 추출 레이어 (packages/ai)

Vercel AI SDK(ai v5) 위에 generateObject·streamObject로 구조화 추출을 구현했다. @ai-sdk/openai·@ai-sdk/openai-compatible·@openrouter/ai-sdk-provider를 함께 등록해 두어, OpenAI뿐 아니라 OpenAI 호환 엔드포인트(Atlas Cloud의 DeepSeek 등)·OpenRouter 모델을 DEFAULT_LLM_MODEL=atlascloud/deepseek-v3 같은 환경변수 한 줄로 바꿔 낄 수 있다. 토큰 계산에는 tiktoken을 쓰고, 긴 페이지는 TextChunker로 분할한다.

④ 데이터 계층 (packages/db)

Drizzle ORM으로 SQLite(자가 호스팅 기본값, 서버 설치 불필요)와 PostgreSQL(docker-compose.pg.yml, 스케일용) 스키마를 나란히 관리한다. 테이블은 jobs·jobResults·billingLedger·templates·scheduledTasks·taskExecutions·webhookSubscriptions·webhookDeliveries·pageCache·mapCache·monitors·monitorSnapshots·monitorChanges 등 16개.

⑤ 인프라 / 배포

4아키텍처 심화 — 큐·엔진·안티봇·프록시

AnyCrawl의 설계를 이해하려면 요청 하나의 여정을 따라가 보는 게 가장 빠르다. POST /v1/scrape가 들어오면 무슨 일이 벌어지는가?

(A) 왜 큐를 엔진별·작업유형별로 쪼갰나

EngineQueueManager는 cheerio·playwright·puppeteer 각각에 대해 독립된 BullMQ 큐 + 워커를 만든다. scrape-*와 crawl-*도 따로 나뉜다. 이렇게 쪼개는 이유는 배포 유연성 때문이다 — docker-compose.yml을 보면 scrape-cheerio·scrape-playwright·scrape-puppeteer가 각각 별도 컨테이너(각자 다른 Dockerfile.cheerio/.playwright/.puppeteer)로 뜬다. 브라우저가 필요없는 cheerio 컨테이너는 이미지가 훨씬 가볍고, 무거운 Playwright/Puppeteer 워커만 따로 스케일아웃할 수 있다.

// managers/Worker.ts — BullMQ Worker는 그냥 이름+핸들러+concurrency
new Worker(name, async (job) => { return await jobHandler(job); }, {
    connection: Utils.getInstance().getRedisConnection(),
    concurrency: 50,
});

(B) 엔진 팩토리 + 레지스트리 패턴

engines/EngineFactory.ts는 BaseEngineFactory 추상 클래스 하나로 3개 엔진 팩토리(cheerio/playwright/puppeteer)의 공통 로직(기본 옵션 병합, 프록시 설정 주입, launchContext 병합)을 통일한다. 각 구체 팩토리는 "어느 모듈에서 어느 클래스를 동적 import할지"만 다르다.

export class EngineFactoryRegistry {
    private static factories = new Map();
    static {
        this.register('cheerio', new CheerioEngineFactory());
        this.register('playwright', new PlaywrightEngineFactory());
        this.register('puppeteer', new PuppeteerEngineFactory());
    }
    static async createEngine(engineType, queue, options) {
        const factory = this.factories.get(engineType);
        if (!factory) throw new Error(`No factory registered for engine type: ${engineType}`);
        return factory.createEngine(queue, options);
    }
}

새 엔진(예: 자체 HTTP/2 클라이언트)을 추가하려면 BaseEngine을 상속하고 팩토리를 하나 더 등록하면 끝이다 — 클라이언트 코드(컨트롤러·워커)는 엔진 타입 문자열만 알면 된다.

(C) engine:"auto" — HTML을 5초만 보고 JS 필요 여부를 채점한다

utils/autoEngine.ts는 README에는 없는, 소스를 읽어야만 보이는 기능이다. 가벼운 HTTP GET으로 HTML을 받아 다음과 같은 점수를 매긴다.

// 강한 신호(+3): 비어있는 루트 div, 본문 텍스트가 100자 미만인데 HTML은 2000자 초과,
// noscript 안에 의미있는 폴백 콘텐츠가 있음
if (/id=["'](?:root|app|__next|__nuxt)["'][^>]*>\s*<\/div>/i.test(rawHtml)) score += 3;

// 중간 신호(+1~2): __NEXT_DATA__ · __NUXT__ · data-reactroot 같은 프레임워크 흔적,
// script 태그가 10개 넘는데 보이는 텍스트는 500자 미만

// 상쇄 신호(-1~-3): 본문 텍스트가 이미 1000자 넘게 존재하면 오히려 JS가 필요없다고 판단

const engine = analysis.jsRequired ? "playwright" : "cheerio";
cache.set(domain, { engine }); // 도메인 단위로 캐싱 — 같은 사이트는 다음부터 재판별 안 함

즉 "이 페이지가 React/Vue SPA 껍데기인가, 이미 서버에서 렌더링된 페이지인가"를 휴리스틱 점수로 판정해 불필요한 브라우저 실행을 피한다. 실무에서 그대로 가져다 쓸 수 있는 실용적인 알고리즘이다.

(D) 안티봇 파이프라인 — Cloudflare Turnstile을 CDP로 뚫기

ChallengePlugin 인터페이스(onPreNavigation 훅 하나)를 구현한 CloudflareChallengeHandler가 실제로 하는 일:

1. 프록시 모드가 stealth일 때만 동작(일반 모드는 그냥 통과)
2. 세션에 저장된 cf_clearance 쿠키가 있으면 페이지 컨텍스트에 먼저 주입해 재도전 자체를 생략
3. 그래도 Turnstile 위젯이 뜨면 CDPTurnstileSolver가 CDP로 challenge 파라미터를 추출해 2captcha API에 풀이를 요청
4. 풀이에 성공하면 그 결과 쿠키를 캐시에 저장해 같은 도메인의 다음 요청부터 재사용

(E) 프록시 티어링 — base와 stealth를 자동으로 오간다

resolveProxyModeWithFallback은 요청의 proxy 값에 따라 "시도할 프록시 풀의 순서"를 배열의 배열로 반환한다.

if (proxyValue === 'auto') {
    // 1티어: 저렴한 base 프록시 먼저 시도, 실패하면 2티어: stealth로 자동 승급
    if (baseProxyUrls.length > 0) {
        return stealthProxyUrls.length > 0
            ? [baseProxyUrls, stealthProxyUrls]
            : [baseProxyUrls];
    }
}

stealth로 명시하면 반대로 스텔스 프록시를 먼저 쓰고 실패 시 base로 내려간다. 여기에 도메인 단위 캐시(ProxyCacheManager)를 얹어, 한 번 stealth가 필요하다고 판정된 도메인은 이후 요청에서 바로 stealth로 시작한다 — 매번 재시도-실패-승급을 반복하지 않는다.

(F) CDP 레벨 리소스 차단 — DOM이 그려지기 전에 광고를 끊는다

브라우저 엔진(Playwright/Puppeteer)은 페이지마다 CDP 세션을 열어 Network.setBlockedURLs로 광고 도메인을 차단하고, Fetch.enable로 이미지·미디어·폰트 요청을 가로챈다. 스크린샷 포맷이 필요한 요청이면 이미지는 통과시키고 미디어만 막는 식으로 요청 목적에 따라 차단 규칙을 동적으로 바꾼다. 이 모든 처리가 페이지가 실제로 리소스를 내려받기 전에 CDP 레벨에서 끝나므로, "다운로드 후 DOM에서 숨기기"보다 훨씬 적은 대역폭을 쓴다(BandwidthTracker가 실제 절감량을 잡별로 기록한다).

핵심 설계 패턴 정리

• 팩토리+레지스트리로 엔진을 플러그인처럼 등록/교체
• 합성(composition) 우선 — BaseEngine은 상속 트리를 깊게 파지 않고 DataExtractor·JobManager 같은 전담 클래스를 필드로 들고 위임한다
• 플러그인 인터페이스로 안티봇 챌린지를 확장 가능하게(ChallengePlugin) 설계
• 계층형 폴백 배열(string[][])로 프록시 승급을 표현 — 상태머신 대신 "시도할 순서 목록"으로 단순화
• 큐 분리 = 배포 단위 분리 — 논리적 큐 구분이 그대로 컨테이너 경계가 된다

5디렉토리 구조 해부

6학습 포인트 — 여기서 훔쳐올 설계

7하드웨어 / 시스템 요구사항

cheerio 엔진만 쓸 거라면 노트북 한 대로 충분하다. Playwright/Puppeteer 엔진을 실제로 돌리려면 Chromium 프로세스가 페이지마다(또는 컨텍스트마다) 뜨는 만큼 메모리 여유가 필요하다.

배포 형태는 두 가지다. ① All-in-One 단일 컨테이너(루트 Dockerfile) — supervisord가 Redis·API·워커를 한 컨테이너 안에서 관리해 빠르게 체험하기 좋다. ② docker-compose 다중 컨테이너 — API/Redis/엔진별 워커가 각자 컨테이너로 분리돼 실제 운영 스케일링에 맞다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

1주차 — Crawlee와 엔진 추상화

Crawlee 공식 문서로 CheerioCrawler/PlaywrightCrawler/PuppeteerCrawler의 요청 큐·세션 풀·재시도 모델을 익히고, packages/scrape/src/engines/Base.ts의 createCommonHandlers를 줄 단위로 읽는다. "여러 엔진을 하나의 인터페이스로 감싸는 법"이 이번 주 목표.

2주차 — 분산 큐/워커 아키텍처

BullMQ 공식 문서로 Producer/Consumer 분리, 재시도·백오프, repeatable job(cron) 개념을 익히고, managers/Queue.ts·managers/Scheduler.ts를 대조하며 읽는다. Redis 자료구조(Sorted Set 기반 지연 큐)가 왜 큐 라이브러리에 적합한지도 함께 살펴본다.

3주차 — 안티봇과 프록시 전략

Cloudflare Turnstile의 동작 원리, CDP(Chrome DevTools Protocol)의 Network/Fetch 도메인, 2captcha 같은 캡차 해결 서비스의 API 흐름을 익힌다. challenges/와 managers/Proxy.ts를 함께 읽으며 "언제 어떤 방어가 필요한가"를 판단하는 감각을 기른다.

4주차 — LLM 추출 파이프라인

Vercel AI SDK의 generateObject/streamObject, JSON Schema ↔ Zod 변환, 비전 모델 기반 OCR을 packages/ai/src/agents/로 실습한다. 토큰 계산(tiktoken)과 긴 문서 청킹 전략(TextChunker)도 함께 본다.

5주차 — 샌드박스 보안과 스키마 우선 설계

Node.js vm 모듈의 격리 한계(진짜 보안 경계가 아니라는 점 포함)를 학습하고, template-client의 정적 검사+런타임 화이트리스트 조합을 분석한다. 마지막으로 Zod → OpenAPI 자동 생성(zod-openapi, fumadocs-openapi) 흐름을 apps/docs에서 확인하며 스키마 우선 API 설계를 정리한다.

10핵심 키워드 사전

11참고 링크

프로젝트

• any4ai/anycrawl — 저장소(모노레포)
• docs.anycrawl.dev — 공식 문서(12개 언어, 한국어 포함)
• anycrawl.dev/playground — API 테스트 플레이그라운드
• @anycrawl/js-sdk · anycrawl-mcp — 공식 SDK/MCP 패키지

핵심 소스(먼저 읽을 파일)

• engines/EngineFactory.ts — 엔진 팩토리+레지스트리
• utils/autoEngine.ts — engine:"auto" 휴리스틱
• challenges/cloudflare/CloudflareChallengeHandler.ts — Turnstile 대응
• managers/Proxy.ts — 프록시 티어링
• template-client/src/sandbox — 사용자 스크립트 샌드박스

기반 기술

• Crawlee · BullMQ — 크롤링 프레임워크와 작업 큐
• Drizzle ORM · Fumadocs — DB ORM과 문서 프레임워크
• Vercel AI SDK — generateObject 구조화 추출
• Chrome DevTools Protocol · 2captcha API — 안티봇 대응 배경 지식
• SearXNG — 자체 호스팅 메타서치 엔진
• Firecrawl · Crawl4AI — 비교 대상 경쟁 프로젝트