NanmiCoder/MediaCrawler 딥다이브
— JS 역공학 없이 7개 중국 SNS를 한 방에 긁는 Playwright 크롤러

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

2왜 주목받는가

트렌딩 이유 · JS 역공학 대신 브라우저를 통째로 빌리는 영리함.

중국 SNS 플랫폼들은 API 요청에 복잡한 암호화 서명을 붙인다. 소홍서의 X-S 헤더, 더우인의 _signature 파라미터 등이 대표적이다. 이를 분석(역공학)하려면 JavaScript 난독화 해제, 알고리즘 재구현이 필요하고, 플랫폼이 업데이트할 때마다 다시 해야 한다. MediaCrawler는 이 문제를 우회한다 — 브라우저가 서명을 만들어 주니까 코드가 만들 필요가 없다.

또 다른 주목 이유는 통일된 아키텍처다. 7개 플랫폼이 모두 AbstractCrawler, AbstractLogin, AbstractStore라는 동일한 ABC(Abstract Base Class) 인터페이스를 구현한다. 새 플랫폼을 추가할 때 인터페이스만 보고 작성하면 된다. 저장 방식도 CSV·JSON·JSONL·MySQL·SQLite·MongoDB·Excel 7가지를 팩토리 패턴으로 지원한다.

3기술 스택 전체 지도

백엔드·브라우저 자동화·저장소·인프라 각 레이어 상세.

핵심 언어 · 런타임

브라우저 자동화

HTTP · 네트워크

저장소 (Storage) — 팩토리 패턴으로 7가지 동적 선택

데이터 처리 · 분석

프록시 · IP 풀

플랫폼 어댑터 (media_platform/)

4아키텍처 심화 분석

브라우저 → CDP → API 가로채기 → 파서 → 저장 흐름 + 핵심 설계 패턴.

시스템 구조도

핵심 설계 패턴 3가지

1. 추상 클래스 + 팩토리 패턴 (Strategy + Factory)

모든 플랫폼 크롤러는 AbstractCrawler를 상속받아 start(), search(), launch_browser()를 반드시 구현해야 한다. CrawlerFactory가 플랫폼 문자열(예: "xhs")을 받아 해당 클래스 인스턴스를 반환한다. 저장소도 XhsStoreFactory가 동일한 패턴으로 7가지 백엔드 중 하나를 선택한다.

# CrawlerFactory 구조 (main.py)
class CrawlerFactory:
    CRAWLERS: dict[str, Type[AbstractCrawler]] = {
        "xhs": XiaoHongShuCrawler,
        "dy": DouYinCrawler,
        "ks": KuaishouCrawler,
        "bili": BilibiliCrawler,
        "wb": WeiboCrawler,
        "tieba": TieBaCrawler,
        "zhihu": ZhihuCrawler,
    }
    @staticmethod
    def create_crawler(platform: str) -> AbstractCrawler:
        crawler_class = CrawlerFactory.CRAWLERS.get(platform)
        return crawler_class()

2. 브라우저 컨텍스트를 통한 서명 주입

플랫폼의 JS 서명 함수는 역공학하지 않는다. 대신 Playwright의 page.evaluate()로 브라우저 내 JS 환경에서 직접 서명 함수를 호출한다. 소홍서를 예로 들면 브라우저 안에서 실행되는 window._webmsxyw 같은 내부 함수를 그대로 불러 서명값을 뽑아낸다.

3. 비동기 세마포어 기반 동시성 제어

asyncio의 Semaphore로 동시 요청 수를 MAX_CONCURRENCY_NUM으로 제한한다. 크롤러가 플랫폼 서버에 과부하를 주지 않도록 CRAWLER_MAX_SLEEP_SEC 기반 랜덤 슬립도 삽입된다. tenacity의 @retry 데코레이터로 네트워크 오류를 투명하게 재시도한다.

5디렉토리 구조 해부

각 폴더가 어떤 역할을 맡는가.

6학습 포인트

브라우저 자동화 · 비동기 Python · 크롤링 윤리에서 배울 것.

1. Playwright 브라우저 자동화 심화

이 레포는 Playwright의 고급 기능을 실전으로 배울 수 있는 좋은 예시다. 단순한 클릭/입력을 넘어 BrowserContext 저장과 복원, page.evaluate()로 JS 함수 직접 호출, CDP 프로토콜 연결, init_script로 감지 방지 JS 삽입까지 다룬다.

base_crawler.py의 launch_browser_with_cdp()와 tools/cdp_browser.py의 CDPBrowserManager를 함께 보면 로컬 Chrome 프로세스를 찾아 실행하고 CDP 포트로 연결하는 전 과정을 이해할 수 있다.

2. Python 비동기 프로그래밍 (asyncio)

이 레포 전체가 async/await로 작성되어 있다. 배울 수 있는 패턴:

3. 디자인 패턴: ABC + Factory + Mixin

base/base_crawler.py의 ABC 설계를 보면 인터페이스 분리, 의존성 역전 원칙(DIP)을 실제로 어떻게 적용하는지 볼 수 있다. proxy/proxy_mixin.py의 Mixin 패턴도 Python 다중 상속을 활용한 기능 합성의 좋은 예다.

4. 크롤링 윤리와 법적 한계

5. 실습 아이디어

실제 플랫폼 크롤링 대신 안전하게 배우는 방법: 공개 API가 있는 서비스(Hacker News API, Reddit Public API, Wikipedia API)를 대상으로 같은 추상 클래스 구조를 직접 구현해보는 것이 좋다. 서명 로직이 없으므로 아키텍처 학습에 집중할 수 있다.

7시스템 요구사항 · 설치

요구사항 · uv / pip 설치 · playwright install 명령.

방법 A: uv 사용 (권장)

# 1. uv 설치 (없는 경우)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 레포 클론
git clone https://github.com/NanmiCoder/MediaCrawler.git
cd MediaCrawler

# 3. 가상환경 생성 + 의존성 설치 (uv가 자동으로 Python 3.11 관리)
uv sync

# 4. Playwright 브라우저 바이너리 설치
uv run playwright install chromium

# 5. 환경변수 설정
cp .env.example .env
# .env 파일에 DB 연결, 쿠키 등 필요 항목 채우기

방법 B: pip 사용

# Python 3.11+ 가상환경 생성
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -r requirements.txt
playwright install chromium

기본 실행

# config/__init__.py 또는 .env에서 설정 후:
# PLATFORM=xhs, KEYWORDS=파이썬, CRAWLER_TYPE=search

uv run python main.py
# 처음 실행 시 QR코드가 터미널에 표시됨 → 소홍서 앱으로 스캔
# 이후 세션이 저장되어 재로그인 불필요

DB 초기화 (MySQL/PostgreSQL 사용 시)

# SAVE_DATA_OPTION=db 또는 postgres인 경우
uv run python main.py --init-db mysql
# 또는
uv run python main.py --init-db sqlite

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

난이도별 3~5개 실습 — 실제 플랫폼 크롤링보다 구조 이해에 집중.

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

이 레포를 기반으로 확장할 수 있는 주차별 학습 경로.

10핵심 키워드 사전

이 레포를 이해하는 데 필요한 핵심 개념 정리.

11참고 링크 · 법적·윤리적 주의

출처 · 정리 기준일 2026-06-27 · 솔직한 caveat.