🕸️

Apinfy Lab

self-host 액터 기반 크롤링 SaaS 커널

조직·API키 RBAC가 내장된 단일 노드 크롤링 플랫폼 커널. 액터(재사용 크롤링 유닛)를 버전 관리로 등록하고, 실행마다 dataset·KV·요청 큐를 격리해 동시 실행을 안전하게 처리합니다. 스케줄·웹훅·프록시 풀·재시도까지 SaaS 계약을 갖춰 분산 워커로 확장할 기초를 만든 레퍼런스 구현입니다.

GitHub

Case

문제 → 해결 → 결과

Problem: 크롤러를 하나 늘릴 때마다 스케줄·동시성·격리·재시도를 매번 새로 짜야 했고, 여러 크롤러가 한 노드에서 결과·상태·요청을 섞어 충돌했습니다. 진짜 걸림돌은 "실행 단위가 재사용·격리되지 않는다"였고, 나중에 분산 워커(Docker/k8s)로 키우려면 그 토대부터 필요했습니다.
AX Intervention: 확장 가능한 실행 토대가 목표라, 세 가지를 설계 원칙으로 잡았습니다. ① 액터를 코드가 아니라 선언식 메타데이터(진입점·입출력 스키마·CPU/메모리/타임아웃)로 추상화해 컴파일 없이 추가·버전 관리되게 했습니다. ② 실행(run)마다 dataset·KV·요청 큐를 즉시 격리 프로비저닝하고, 동시성은 DB 유니크 제약으로 lock-free 처리해 run 간 결과가 섞이지 않게 했습니다. ③ Local·Docker 실행기를 같은 인터페이스의 전략 패턴으로 두어, 개발은 in-process·운영은 컨테이너로 바꾸고 향후 k8s 실행기를 코드 변경 최소로 붙일 확장점을 고정했습니다.
Outcome: 단일 노드에서 멀티테넌시·동시성·스케줄·웹훅·재시도·프록시 풀을 갖춘, 분산 크롤링 플랫폼의 레퍼런스 구현으로 만들었습니다.

Tech Stack

PythonFastAPISQLAlchemy asyncDockercurl_cffi

Features

주요 기능

액터 실행 모델 — 진입점(파이썬 모듈/Docker 이미지)·입출력 스키마·CPU/메모리/타임아웃을 선언식으로 저장하고 버전별 관리

org_id 기반 멀티테넌시로 테넌트 간 행 수준(RLS) 격리

croniter cron 스케줄로 due 판정·자동 큐잉

실행마다 dataset·KV·요청 큐 자동 프로비저닝으로 run 간 격리

요청 큐 unique_key 제약으로 lock-free 중복 제거·재시도

실패 시 자동 재시도(최대 2회)와 버전별 타임아웃 적용

웹훅 이벤트(queued/running/failed/succeeded) HMAC-SHA256 서명 전달

Bright Data 등 프록시 세션 풀(usable/exhausted 상태) 관리

Local/Docker 실행기 전략 패턴으로 개발↔프로덕션 전환과 향후 k8s 확장 대비

하이라이트

액터 모델 + 실행 격리 — 확장 가능한 크롤링 커널

2026