douyin-downloader 딥다이브
— 무수익 오픈소스가 보여주는 "웹 스크래핑 엔지니어링"의 교과서

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

douyin-downloader는 抖音(Douyin, 중국 본토판 TikTok)의 콘텐츠를 터미널 명령 한 줄 또는 설정 파일 하나로 대량 수집하는 파이썬 도구다. 단일 영상부터 특정 크리에이터의 전체 게시물·좋아요·컬렉션·음악·즐겨찾기까지, 그리고 라이브 방송 녹화까지 다룬다.

버전은 2.0.0이며, CLI 도구 + REST API 서버 모드 + (베타) 데스크톱 GUI(Douzy) 세 형태를 같은 파이썬 백엔드로 공유한다. 라이선스는 관대한 MIT. 저자는 README에 "무료! 무료! 무료!"를 반복하며 상업적 의도가 없음을 강조한다.

2왜 주목받는가

트렌딩 이유와, 흔한 "다운로더 스크립트"와의 결정적 차이.

① 단순 스크립트가 아니라 "제대로 설계된 애플리케이션"

GitHub에 널린 다운로더 대부분은 requests.get() 한 뭉치의 스파게티 스크립트다. 이 프로젝트는 다르다. 109개 파이썬 파일이 core / control / storage / auth / config / utils로 계층 분리돼 있고, 60개 이상의 테스트 파일(property-based 테스트 포함)과 GitHub Actions CI, Docker, 심지어 각 폴더마다 AGENTS.md(AI 코딩 에이전트용 규칙서)까지 있다.

② "안티봇 vs 스크래퍼" 공방을 실물로 보여준다

더우인 서버는 자동화 요청을 막으려고 요청마다 X-Bogus·A-Bogus라는 서명 파라미터를 요구한다. 브라우저가 자바스크립트로 만들어 붙이는 값인데, 이 프로젝트는 그 알고리즘을 파이썬으로 포팅(이식)해 두었다(utils/xbogus.py, utils/abogus.py). 여기에 더해:

• User-Agent 로테이션 — 여러 브라우저인 척 위장
• ms_token / cookie 관리 — 세션 토큰 자동 갱신, 만료 시 재로그인
• 브라우저 폴백 — API 페이지네이션이 막히면 Playwright로 실제 브라우저를 띄워 사람이 CAPTCHA를 풀게 함

즉, "서버가 막으면 어떻게 우회하나"의 여러 계층을 한 코드베이스에서 관찰할 수 있다.

③ 무료·자기호스팅·프라이버시

비슷한 상용 서비스는 유료 구독이거나, 사용자의 링크를 자기네 서버로 보낸다. 이 도구는 내 컴퓨터에서 로컬 실행되어 데이터가 밖으로 안 나간다. 자기호스팅(Self-hosted)·프라이버시 선호 흐름과 맞물려 TrendShift 상위권에 올랐다. 중국어권 개발자 커뮤니티(linux.do 등)에서의 화제성도 모멘텀에 기여했다.

3기술 스택 전체 지도

무엇으로 만들어졌나 — 계층별로.

핵심 런타임 / 비동기

서명 위조 / 인증

제어 계층 (안정성)

저장 / 미디어 / 부가

4아키텍처 심화 분석

데이터가 링크 한 줄에서 파일까지 흐르는 전 과정.

전체 파이프라인 (한 눈에)

핵심 설계 패턴 ① — 팩토리(Factory)

DownloaderFactory.create(url_type, ...)가 URL 종류에 따라 알맞은 다운로더 객체를 만들어 돌려준다. 호출부(cli/main.py)는 "어떤 다운로더가 필요한지" 몰라도 되고, 새 종류(예: 라이브)를 추가할 때 팩토리에 분기 한 줄만 더하면 된다.

# core/downloader_factory.py — 타입 → 객체 매핑 (핵심만)
if url_type == "video":   return VideoDownloader(**common_args)
elif url_type == "user":    return UserDownloader(**common_args)
elif url_type == "collection": return MixDownloader(**common_args)
elif url_type == "music":   return MusicDownloader(**common_args)
elif url_type == "live":    return LiveDownloader(**common_args)
# common_args = config·api_client·file_manager·database·
#               rate_limiter·retry_handler·queue_manager ... (의존성 주입)

핵심 설계 패턴 ② — 전략(Strategy) : 유저 모드 분리

한 크리에이터를 긁을 때도 게시물(post) · 좋아요(like) · 컬렉션(mix) · 음악(music) · 즐겨찾기(collect)는 API 엔드포인트와 페이지네이션 규칙이 제각각이다. 이걸 core/user_modes/ 아래 전략 클래스로 하나씩 떼어냈다. base_strategy.py가 공통 뼈대, 각 *_strategy.py가 모드별 차이만 구현한다.

핵심 설계 패턴 ③ — 의존성 주입(DI)으로 "공유 도구" 재사용

APIClient·RateLimiter·RetryHandler·Database 같은 무거운 객체는 한 번 만들어 모든 다운로더에 주입한다. 덕분에 속도 제한이 전체에 일관 적용되고, DB 커넥션도 공유된다. common_args 딕셔너리가 그 주입 통로다.

안정성 3종 세트가 맞물리는 방식

# control/rate_limiter.py — 지터가 "락 안"에 있는 이유
async with self._lock:
    # 최소 간격(1/2초) 못 채웠으면 그만큼 대기
    if time_since_last < self.min_interval:
        await asyncio.sleep(self.min_interval - time_since_last)
    # 지터도 락 안에서 — 다음 요청이 "실제 발사 시각" 기준으로 대기하도록
    await asyncio.sleep(random.uniform(0, 0.5))
    self.last_request = time.time()

로그인 필요 감지 → 자동 재로그인

더우인이 status_code == 2483(또는 "请先登录=먼저 로그인하세요")를 주면 LoginRequiredError가 발생하고, cli/main.py의 _run_with_relogin 래퍼가 이를 잡아 대화형 재로그인 후 자동 재시도한다. 긴 배치 작업 중 세션이 끊겨도 멈추지 않게 하는 실전 배려다(docs/superpowers/specs/2026-06-25-auto-relogin-design.md에 설계 문서까지 있음).

5디렉토리 구조 해부

폴더 이름만 봐도 책임이 보이도록 나눴다.

주목할 관례: 폴더마다 AGENTS.md가 있어 Claude Code 같은 AI 에이전트가 그 폴더를 수정할 때 지켜야 할 규칙을 명시한다. 또 CLAUDE.md는 이 CLI가 데스크톱 앱과 백엔드 코드를 공유하니 "공유 로직을 고치면 양쪽에 똑같이 반영하라"고 지시한다. "사람+AI 협업"을 전제로 설계된 최신 리포의 전형.

6학습 포인트 (기술별)

이 코드에서 구체적으로 무엇을 훔쳐 배울 수 있나.

① 비동기(asyncio) 실전

튜토리얼의 asyncio.sleep 예제를 넘어, 실제 네트워크·파일·DB를 전부 async로 엮은 코드를 볼 수 있다. aiohttp(요청)·aiofiles(디스크)·aiosqlite(DB)가 한 이벤트 루프 위에서 협력한다. asyncio.Lock으로 공유 상태(마지막 요청 시각)를 보호하는 법도 rate_limiter에서 배운다.

② 안티봇 우회의 원리

utils/xbogus.py는 커스텀 문자셋("Dkdpgh4ZKsQB80/Mfvw...")과 자체 base64·해시로 서명을 조립한다. "브라우저 JS가 하는 일을 서버 언어로 재현"하는 리버스 엔지니어링의 살아있는 예다. (이 파일은 Evil0ctal의 Douyin_TikTok_Download_API 프로젝트에서 온 Apache-2.0 코드다.)

③ 견고한 네트워크 클라이언트 만들기

실서비스 스크래퍼가 반드시 갖춰야 할 속도 제한 + 지수 백오프 재시도 + 동시성 제한 + 지터를 각각 독립 모듈로 구현한 참고서. 이 패턴은 더우인뿐 아니라 어떤 API 클라이언트에도 그대로 이식 가능하다.

④ 테스트 가능한 설계

팩토리·전략·DI 덕에 각 부품을 가짜(mock)로 갈아끼워 단위 테스트할 수 있다. tests/의 60여 개 파일, 특히 hypothesis 기반 속성 기반 테스트(무작위 입력 수천 개로 불변식 검증) — test_notifier_redactor_property.py(민감정보 마스킹이 항상 성립하는가), test_proxy_validator_parity.py 등을 읽어볼 것.

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

돌리는 데 뭐가 필요한가.

핵심은 무겁지 않다는 것. GPU도, 대용량 RAM도 기본 사용엔 불필요하다. 병목은 오직 네트워크 대역폭과 서버의 속도 제한이다 — 그래서 코드가 속도제한·재시도에 그토록 공을 들인다.

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

난이도별로 — 코드를 읽고 손대며 배우기. (합법적 범위: 본인 콘텐츠·공개 학습용 소규모로)

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

이 레포를 발판 삼아 어디로 뻗어갈까 — 4주 코스.

10핵심 키워드 사전

이 문서에 나온 용어 총정리.

11참고 링크

더 파고들 곳.