douyin-downloader 딥다이브
— Python CLI와 데스크톱 배포를 구분해 읽는 "웹 스크래핑 엔지니어링"의 교과서

1프로젝트 한줄 요약

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

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

Python CLI 선언 버전은 2.0.0이며 REST 서버 모드도 포함한다. 공개 코드는 MIT다. 별도로 안내하는 Douzy 데스크톱은 플러그인·로컬 구성과 활성화 조건을 갖추며 CLI와 지원 범위를 구분한다.

2026-10-29 확인한 다운로드 범위와 한계

현재 README는 CLI가 Douyin만 지원한다고 명시한다. 개별 영상·사진, 컬렉션·음악·좋아요·즐겨찾기는 요청 검증 때문에 막히며, 쿠키 갱신이나 단순 재시도로 해결되지 않는다고 안내한다. 프로필 게시물은 Playwright 경로를 시도할 수 있으나 성공을 보장하지 않는다. 아래 모드·팩토리 설명은 코드가 가진 분기 구조이며 현재 모든 다운로드가 동작한다는 뜻은 아니다.

Douzy 데스크톱은 Douyin·TikTok·YouTube·Telegram·X를 안내한다. Telegram은 구성·로그인, X는 계정 쿠키가 필요하며 플러그인·로컬 구성과 활성화 조건이 따로 있다. 이를 무료 다중 플랫폼 CLI로 소개하지 않는다.

증분 설정 increase.post: true는 이미 받은 항목을 건너뛰고, false는 선택 범위의 파일을 다시 받아 덮어쓴다. redownload_missing_files는 기본 true이며 실제 주 미디어 파일의 존재·비어 있지 않음을 확인한다. 다시 받기 위해 DB 전체를 지우는 방식은 필요하지 않다.

core/user_modes/post_strategy.py는 목록이 잘렸을 때 incomplete_reason을 남기고 브라우저가 실제 새 항목을 추가했는지 확인한다. core/live_downloader.py는 HLS 소스일 때 재생 가능한 영상 대신 m3u8 목록만 저장한다고 경고한다. 라이브 녹화는 실험 기능이다.

2왜 주목받는가

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

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

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

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

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

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

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

③ 로컬 실행과 외부 연결 범위

Python CLI는 로컬에서 실행하지만 플랫폼 요청은 외부로 나가며 선택한 전사 API·알림 채널도 외부 서비스를 사용한다. 로컬 실행을 데이터가 전혀 외부로 전송되지 않는다는 뜻으로 읽으면 안 된다. 실제 다운로드 가능 범위와 선택 기능의 연결 대상을 먼저 확인한다.

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참고 링크

2026-10-29 재검토: 공식 소스 커밋 ed863617aa52353821aca8fdebcfad4e916ebff5. 아래 초판 기록과 현재 소스 개정 내용을 구분한다.

더 파고들 곳.