MediaCrawler 심층 분석: 7대 플랫폼을 지원하는 올인원 오픈소스 소셜미디어 데이터 크롤러

1. MediaCrawler란?

MediaCrawler는 중국 소셜미디어 플랫폼을 지원하는 가장 포괄적인 오픈소스 크롤러 도구로, GitHub에서 64,000개 이상의 스타를 받으며 개발자 NanmiCoder에 의해 유지보수되고 있습니다. Python + Playwright 브라우저 자동화 프레임워크를 기반으로 하며, 로그인 상태를 유지한 채 플랫폼 API를 직접 호출하는 방식을 사용하여 복잡한 JS 암호화 알고리즘을 리버스 엔지니어링할 필요가 없어 기술적 진입 장벽을 크게 낮췄습니다.

핵심 포지셔닝: 데이터 분석가, 여론 연구원, 콘텐츠 운영자를 위한 학습 도구로, 7대 중국 소셜미디어 플랫폼의 공개 콘텐츠 데이터를 원클릭으로 수집할 수 있습니다.

Crawl4AI와 같은 범용 웹 크롤러와 달리, MediaCrawler는 중국 소셜미디어 플랫폼에 특화되어 있으며, 각 플랫폼의 서명 로직과 데이터 파싱 규칙이 내장되어 있어 바로 사용할 수 있습니다. 해외 플랫폼 데이터 수집이 필요하다면 Wiseflow 심층 분석을 참고하세요.

2. 지원 7대 플랫폼 및 기능 매트릭스

7개 플랫폼 모두 동일한 기능을 제공합니다 — 이것이 MediaCrawler의 가장 큰 아키텍처적 장점입니다: 통합 인터페이스 설계로 플랫폼 전환은 단 하나의 파라미터만 변경하면 됩니다.

3. 기술 아키텍처 분석

MediaCrawler의 기술 스택은 "반탐지 위험 감소"를 중심으로 설계되었습니다:

┌─────────────────────────────────────────────┐
│           MediaCrawler 아키텍처              │
├─────────────────────────────────────────────┤
│  사용자 계층    CLI 커맨드라인 / WebUI        │
├─────────────────────────────────────────────┤
│  스케줄링 계층   플랫폼 스케줄러 → 통합 크롤러 인터페이스 │
├─────────────────────────────────────────────┤
│  실행 계층      Playwright (CDP 모드)         │
│           ├─ 로그인 상태 관리 (QR/전화/Cookie) │
│           ├─ JS 서명 계산 (브라우저 컨텍스트 재사용) │
│           └─ 반탐지 (실제 브라우저 핑거프린트)   │
├─────────────────────────────────────────────┤
│  데이터 계층    CSV / JSON / JSONL / Excel    │
│           SQLite / MySQL / PostgreSQL         │
└─────────────────────────────────────────────┘

핵심 기술 원리:

1. CDP 모드(권장): Chrome DevTools Protocol을 통해 기존 Chrome 브라우저에 연결하여 실제 브라우저의 Cookie, 확장 프로그램, 검색 기록을 재사용하여 최적의 반탐지 효과 달성
2. 서명 재사용: 로그인 상태가 유지되는 브라우저 컨텍스트 환경을 활용하여 JS 표현식으로 플랫폼 서명 파라미터를 직접 획득, 암호화 알고리즘 리버스 엔지니어링 불필요
3. 로그인 상태 캐시: 첫 QR 코드 로그인 후 Cookie를 저장하고, 이후 실행 시 자동으로 재사용하여 재로그인 불필요

4. 설치 및 빠른 시작

4.1 환경 준비

# 1. uv 설치 (권장 Python 패키지 매니저)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Node.js >= 16 확인 (더우인과 즈후 서명에 필요)
node --version

# 3. 프로젝트 클론
git clone https://github.com/NanmiCoder/MediaCrawler.git
cd MediaCrawler

# 4. 의존성 설치 (uv가 Python 버전과 의존성을 자동 처리)
uv sync

4.2 Chrome 브라우저 설정 (CDP 모드)

MediaCrawler는 기본적으로 CDP 모드를 사용하므로 Chrome 설정이 필요합니다:

1. Chrome >= 144 설치
2. 주소창에 chrome://inspect/#remote-debugging 입력
3. "Allow remote debugging for this browser instance" 체크
4. Server running at: 127.0.0.1:9222 표시 확인

CDP 모드를 사용하지 않으려면 config/base_config.py에서 ENABLE_CDP_MODE = False로 설정하세요.

4.3 첫 실행

# 소홍서 키워드 검색 (기본 15개 노트 수집)
uv run main.py --platform xhs --lt qrcode --type search

# 첫 실행 시 QR 코드가 표시되면 소홍서 앱으로 스캔하여 로그인
# 로그인 상태는 자동 캐시되어 이후 재스캔 불필요

5. 주요 설정 상세

config/base_config.py가 핵심 설정 파일입니다. 다음은 자주 사용하는 설정 항목입니다:

# 대상 플랫폼: xhs | dy | ks | bili | wb | tieba | zhihu
PLATFORM = "xhs"

# 검색 키워드 (영문 쉼표로 구분)
KEYWORDS = "Python 튜토리얼,프로그래밍 부업,AI 도구 추천"

# 로그인 방식: qrcode (QR 코드) | phone (휴대폰) | cookie (수동 입력)
LOGIN_TYPE = "qrcode"

# 크롤 타입: search (키워드 검색) | detail (지정 게시물) | creator (크리에이터 페이지)
CRAWLER_TYPE = "search"

# 데이터 저장 형식: csv | db | json | jsonl | sqlite | excel | postgres
SAVE_DATA_OPTION = "jsonl"

# 키워드당 최대 수집 노트 수
CRAWLER_MAX_NOTES_COUNT = 15

# 동시 실행 수 (1로 유지하여 리스크 제어 회피)
MAX_CONCURRENCY_NUM = 1

# 댓글 수집 활성화
ENABLE_GET_COMMENTS = True

# 2단계 댓글 활성화
ENABLE_GET_SUB_COMMENTS = False

# IP 프록시 설정
ENABLE_IP_PROXY = False
IP_PROXY_PROVIDER_NAME = "kuaidaili"

6. 플랫폼별 데이터 수집 실전

6.1 소홍서 수집

# 키워드로 노트 검색
uv run main.py --platform xhs --lt qrcode --type search

# 지정 노트 ID의 상세 정보 수집
uv run main.py --platform xhs --lt qrcode --type detail

# 크리에이터 페이지의 모든 노트 수집
uv run main.py --platform xhs --lt qrcode --type creator

소홍서 데이터 필드: 노트 제목, 본문 내용, 이미지 목록, 좋아요 수, 즐겨찾기 수, 댓글 수, 작성자 정보, 게시 시간 등.

6.2 더우인 수집

# 동영상 검색
uv run main.py --platform dy --lt qrcode --type search

# 지정 동영상 ID
uv run main.py --platform dy --lt qrcode --type detail

더우인 수집에는 서명 계산에 Node.js 환경이 필요합니다. 데이터 필드: 동영상 제목, 재생 URL, 커버 이미지, 좋아요 수, 댓글 수, 공유 수 등.

6.3 Bilibili 수집

# 동영상 검색
uv run main.py --platform bili --lt qrcode --type search

# 지정 동영상 (BV 번호)
uv run main.py --platform bili --lt qrcode --type detail

Bilibili 데이터: 동영상 제목, BV 번호, 재생수, 탄막 수, 좋아요/코인/즐겨찾기 수, UP 주 정보 등.

6.4 웨이보 / 바이두 타이바 / 즈후 / 콰이쇼우

# 웨이보
uv run main.py --platform wb --lt qrcode --type search

# 바이두 타이바
uv run main.py --platform tieba --lt qrcode --type search

# 즈후
uv run main.py --platform zhihu --lt qrcode --type search

# 콰이쇼우
uv run main.py --platform ks --lt qrcode --type search

모든 플랫폼에서 명령어 형식이 동일하며, --platform 파라미터만 변경하면 됩니다.

7. 데이터 저장 및 내보내기

MediaCrawler는 7가지 데이터 저장 형식을 지원하며, 데이터는 기본적으로 data/ 디렉토리에 저장됩니다:

# MySQL 저장으로 전환
SAVE_DATA_OPTION = "db"

# db_config.py에서 연결 정보 설정
DB_HOST = "localhost"
DB_PORT = 3306
DB_USER = "root"
DB_PASSWORD = "your_password"
DB_NAME = "media_crawler"

8. 고급 사용법

8.1 WebUI 시각적 조작

# 터미널 1: 백엔드 API 시작
uv run uvicorn api.main:app --port 8080 --reload

# 터미널 2: 프론트엔드 시작 (개발 모드)
cd webui && npm install && npm run dev
# http://localhost:5173/ 접속

# 또는 프로덕션 빌드
cd webui && npm install && npm run build
# API 서버만 시작하고 http://localhost:8080 접속

WebUI는 시각적 설정 인터페이스를 제공하여 커맨드라인 없이 크롤러를 조작할 수 있습니다.

8.2 IP 프록시 풀 설정

대규모 수집 시 프록시 풀 활성화를 권장합니다:

ENABLE_IP_PROXY = True
IP_PROXY_POOL_COUNT = 2
IP_PROXY_PROVIDER_NAME = "kuaidaili"  # kuaidaili | wandouhttp | static 지원

# 정적 프록시 설정
IP_PROXY_PROVIDER_NAME = "static"
STATIC_PROXY_URL = "http://user:password@your_proxy:port"

8.3 동시 실행 및 빈도 제어

# 동시 실행 수 (신중하게 설정, 너무 높으면 리스크 제어 작동)
MAX_CONCURRENCY_NUM = 1

# 키워드당 최대 수집 수
CRAWLER_MAX_NOTES_COUNT = 50

# 페이지네이션 시작 위치
START_PAGE = 1

8.4 댓글 워드클라우드 생성

MediaCrawler에는 댓글 워드클라우드 기능이 내장되어 있어 시각적 워드클라우드를 자동 생성할 수 있습니다:

# base_config.py에서 활성화
# wordcloud 등 의존성 사전 설치 필요
ENABLE_WORD_CLOUD = True

9. 컴플라이언스 및 법적 리스크

중요 안내: MediaCrawler 사용 전 다음 리스크를 반드시 확인하세요:

1. 법적 준수: 사이버보안법, 데이터보안법, 개인정보보호법을 준수하며 상업적 용도 금지
2. 플랫폼 규칙: 각 플랫폼의 robots.txt와 이용약관을 존중하고 대규모 크롤 회피
3. 빈도 제어: 요청 빈도를 적절히 제어하여 플랫폼에 부담을 주지 않음
4. 데이터 용도: 학습 및 연구 목적만 사용, 불법 용도 금지
5. 개인정보 보호: 타인의 개인정보를 수집 및 유포하지 않음

참고: 크롤러 관련 위법 사례 모음

10. 다른 도구와의 비교

범용 웹 크롤 기능이 필요하다면 Crawl4AI를, 정보 피드 모니터링과 AI 요약이 필요하다면 Wiseflow를 추천합니다. MediaCrawler의 고유한 가치는 중국 소셜미디어에 대한 심층 적응에 있습니다.

11. 자주 묻는 질문 (FAQ)

MediaCrawler는 어떤 Python 버전을 지원하나요?

Python 3.11을 권장합니다. 이는 프로젝트 의존성 패키지의 주요 테스트 버전입니다. uv를 사용하면 올바른 Python 버전이 자동으로 선택됩니다.

QR 코드 로그인 실패 시 어떻게 해야 하나요?

CDP 모드를 사용하는 경우, Chrome 버전 >= 144이고 원격 디버깅이 활성화되어 있는지 확인하세요. QR 코드를 반복해서 요구하면 브라우저를 닫고 원격 디버깅을 다시 활성화하세요. HEADLESS = False로 전환하여 슬라이드 검증을 수동으로 통과할 수도 있습니다.

여러 플랫폼에서 동시에 크롤할 수 있나요?

가능하지만 순차 실행을 권장합니다. 실행마다 하나의 --platform 파라미터를 지정한 후 완료되면 다음 플랫폼으로 전환하세요. 여러 플랫폼의 병렬 실행은 리스크 제어를 트리거하기 쉽습니다.

데이터는 어디에 저장되나요?

기본적으로 프로젝트 루트 디렉토리의 data/ 폴더에 저장되며, 플랫폼 이름별 하위 디렉토리가 생성됩니다. SAVE_DATA_PATH로 저장 경로를 커스터마이징할 수 있습니다.

MediaCrawler를 상업적으로 사용할 수 있나요?

사용할 수 없습니다. 이 프로젝트는 비상업적 학습 라이선스(NON-COMMERCIAL LEARNING LICENSE 1.1)를 채택하고 있으며 상업적 용도를 명시적으로 금지하고 있습니다. 상업적 사용이 필요한 경우 저자에게 연락하여 라이선스를 취득하세요.

12. 요약

MediaCrawler는 현재 가장 완성도 높은 중국 소셜미디어 데이터 수집 오픈소스 도구이며, 64,000개 이상의 GitHub 스타가 그 실용성을 증명하고 있습니다. 주요 장점:

• 넓은 커버리지: 7대 플랫폼 통합 인터페이스, 전환 비용 제로
• 강력한 반탐지: CDP 모드로 실제 브라우저 환경 재사용
• 쉬운 시작: uv로 원클릭 설치, 설정 후 바로 사용
• 유연한 저장: 7가지 데이터 형식으로 다양한 시나리오 대응
• 활발한 커뮤니티: 지속적 업데이트, 빠른 문제 대응

데이터 분석가, 여론 연구원, 콘텐츠 운영자에게 MediaCrawler는 소셜미디어 데이터 수집 기술을 배우기 위한 최적의 출발점입니다. 단, 법규를 준수하고 플랫폼 규칙과 사용자 프라이버시를 존중하며 사용하시기 바랍니다.