XiaoYouChR/Ghost-Downloader-3 딥다이브
— IDM식 멀티스레드 다운로더를 Python·Qt로 다시 쓴 오픈소스

1프로젝트 한 줄 요약

Ghost Downloader 3은 "파일을 여러 조각으로 나눠 동시에 받아 속도를 끌어올리고, HTTP뿐 아니라 토렌트·FTP·M3U8·유튜브·비리비리까지 한 창에서 처리하는 크로스플랫폼 다운로드 관리자"다. 저자 XiaoYouChR가 "내 첫 Python 프로젝트"라고 README에 적어둔, 취미로 시작해 별 6.5천 개까지 자란 프로그램이다.

이름의 숫자 "3"은 3세대라는 뜻이다. 초기 버전들은 순수 다운로드 기능에 가까웠고, 지금의 3세대(내부 버전 4.x)는 플러그인 구조·브라우저 확장·안드로이드 앱·aria2 호환 API까지 갖춘 하나의 플랫폼으로 커졌다. 저장소를 클론해 보면 크게 네 덩어리로 나뉜다.

Python·Qt 소스만 약 22만 줄(라이브러리 포함) 규모이고, 라이선스는 GPL v3.0이다. 무료·완전 오픈소스이며 상용 IDM을 대체하려는 성격이 뚜렷하다.

2왜 지금 주목받는가

다운로더는 흔한 소프트웨어다. 그런데도 GD3가 주목받는 건 흔한 기능을 흔하지 않게 구현했기 때문이다. 세 가지가 핵심이다.

① 무병합(no-merge) 분할 — "받고 나서 합치기"를 없앴다

대부분의 멀티스레드 다운로더는 조각을 file.part1, file.part2처럼 따로 받아뒀다가 마지막에 하나로 이어 붙인다(병합). 큰 파일이면 이 병합만으로도 디스크를 통째로 한 번 더 읽고 쓴다. GD3는 받는 즉시 각 조각을 최종 파일의 정확한 오프셋(offset)에 직접 써넣어 병합 단계를 통째로 없앴다. 리눅스/맥의 pwrite(위치 지정 쓰기)를 그대로 쓰기 때문에 가능한 설계다.

② AI 스마트 가속 — 조각 수를 실시간으로 스스로 조절

"AI"라는 단어에 거창한 신경망을 떠올리기 쉽지만, 여기서는 속도를 초당 재면서 "조각을 더 쪼개면 실제로 빨라지는지"를 통계적으로 판단하는 자동 튜닝 루프를 말한다. 서버가 연결당 속도를 제한하는 경우(대역폭 throttling)에는 조각을 늘릴수록 총속도가 오른다. GD3는 5초간 속도를 지켜본 뒤 조각을 4개 추가로 쪼개고, "조각을 N% 늘렸는데 속도가 그만큼(0.8배 이상) 안 올랐다"면 더는 이득이 없다고 보고 가속을 멈춘다. 뒤(4장)에서 실제 코드를 뜯어본다.

③ TLS 지문 위장 — 봇 차단을 피하는 다운로더

요즘 서버는 접속자가 "진짜 크롬 브라우저"인지 "스크립트/봇"인지를 TLS 지문(fingerprint)으로 구분해 차단한다. GD3는 wreq 라이브러리로 실제 크롬·파이어폭스의 TLS 악수(handshake) 지문을 흉내 내, 다운로더가 보내는 요청을 브라우저 요청처럼 보이게 만든다. 이건 일반 다운로더에는 거의 없는 기능이다.

여기에 브라우저 확장으로 스트리밍 미디어를 낚아채고, aria2 호환 RPC로 외부 도구가 작업을 밀어 넣게 하고, 같은 엔진으로 안드로이드까지 지원하는 넓은 커버리지가 더해진다. "기능이 많다"가 아니라 "각 기능을 제대로 만들었다"가 트렌딩의 실질적 이유다.

3기술 스택 전체 지도

GD3는 "GUI 앱"이지만 속을 보면 비동기 네트워크 엔진 + Qt 화면 + 12개의 프로토콜 플러그인이 겹쳐진 구조다. 계층별로 어떤 도구를 쓰는지 지도를 그려보자.

런타임 · 언어 기반

UI 계층 (화면)

네트워크 · 프로토콜

주변 시스템

4아키텍처 심화 분석 — 액터와 무병합 다운로드

GD3의 아키텍처는 CONTEXT.md에 아주 정밀하게 문서화돼 있다. 핵심은 두 가지 축이다 — (A) "액터(actor)"로 나눈 서비스 계층과 (B) HTTP 조각 병렬 수신 엔진. 순서대로 뜯어본다.

4-1. 전체 시스템 구조도

이 그림에서 반드시 챙길 두 규칙:

① 단일 공개 창구(single public door). 화면이든 브라우저든 작업을 만들거나 멈추려면 무조건 taskService를 거친다. 작업 목록(TaskStore)과 실행 큐(TaskQueue)는 taskService 안쪽에 숨겨져 있어 아무도 직접 못 만진다. "누가 상태를 바꿀 수 있는가"를 딱 한 곳으로 좁힌 설계다.

② 의존성은 한 방향(leaf → top)으로만 흐른다. coroutineRunner와 speedMeter는 "Task"가 뭔지조차 모른다. 그저 "비동기 작업을 돌려라", "바이트를 세라"는 일반 기능만 한다. 반대로 View는 모든 걸 알고 시그널로 엮는다. 이렇게 하면 아래 계층을 독립적으로 테스트할 수 있다.

4-2. 작업 하나가 태어나는 경로 — 파서 우선순위 체인

URL을 붙여넣으면 featureService.parse(options)가 등록된 파서들을 우선순위 낮은 것부터 훑으며 "이 URL 내가 처리할게"라고 처음 손드는 파서에게 맡긴다. 구체적인 것일수록 번호가 작아 먼저 검사되고, 무엇에도 안 걸리면 마지막의 HTTP 파서(100)가 받는다.

재미있는 지점: GitHubParser는 스스로 다운로드하지 않는다. URL을 프록시 주소로 바꾼 뒤 featureService.parse()를 다시 호출한다. 프록시 URL은 더 이상 github 호스트가 아니므로 HTTP 파서가 받는다 — "위임으로 기능을 조합"하는 깔끔한 패턴이다. 무한 재귀도 자연스럽게 피한다.

4-3. 무병합 조각 병렬 수신 — 실제 엔진 코드

이제 심장부다. HTTP 파일 하나를 어떻게 8조각으로 나눠 병합 없이 받는지, 실제 features/http_pack/task.py를 보자. 먼저 파일을 조각(Subworker)으로 나누는 부분:

# 파일 크기를 subworkerCount(기본 8)만큼 균등 분할
count = min(self.subworkerCount, self.fileSize)
subworkers = []
for i in range(count - 1):
    start = i * chunkSize
    end   = start + chunkSize - 1
    subworkers.append(HttpSubworker(index=i, start=start, end=end))
# 마지막 조각은 파일 끝까지 담당
subworkers.append(HttpSubworker(index=count-1, start=start, end=self.fileSize-1))

각 HttpSubworker는 start(담당 시작 바이트), end(끝 바이트), receivedBytes(지금까지 받은 양)만 든 작은 값이다. position = start + receivedBytes가 "다음에 써야 할 위치"다. 그리고 각 조각을 실제로 받는 _runSubworker는 HTTP Range 요청으로 자기 구간만 달라고 하고, 받은 조각을 pwrite로 파일의 정확한 위치에 바로 쓴다:

# 서버에 "이 바이트 구간만 줘"라고 요청 (Range 헤더)
headers = {**self._effectiveHeaders,
           "range": f"bytes={subworker.position}-{subworker.end}"}
async for chunk in response.stream():
    # 받은 조각을 "그 위치에" 바로 써넣음 → 병합 불필요
    pwrite(fd, chunk, subworker.position)   # ← 핵심 한 줄
    subworker.receivedBytes += len(chunk)
    speedMeter.addSpeed(len(chunk))          # 속도계에 바이트 보고
    await speedMeter.waitForSpeedLimit()      # 전역 속도제한 준수

4-4. "AI 스마트 가속"의 실제 정체

2장에서 예고한 자동 가속 루프의 실제 코드다. 1초마다 도는 감시자(_supervise)가 _autoSpeedUp()을 호출한다. 로직을 우리말로 풀면:

# 1) 최근 5초 속도를 모아 평균과 변동폭 계산
if maxDeviation > 0.15:   # 속도가 15% 넘게 출렁이면 판단 보류 (불안정)
    return

# 2) 첫 판단: 기준 속도/조각수 기록하고 조각 4개 추가 분할
if self._accelCheckTime == 0:
    self._accelInitialWorkers = len(self.subworkers)
    self._accelInitialSpeed   = avgSpeed
    for _ in range(4):
        self._reassignSubworker()      # 가장 느린 조각을 반으로 쪼갬
else:
    # 3) 5초 뒤 재평가: 조각을 N% 늘렸는데 속도는 얼마나 올랐나?
    workerRatio = (지금조각수 - 초기조각수) / 초기조각수
    speedRatio  = (지금속도  - 초기속도)  / 초기속도
    if speedRatio < 0.8 * workerRatio:
        self.isAccelerated = True     # 효과 없음 → 가속 종료
    else:
        self._accelCheckTime = 0        # 효과 있음 → 다음 라운드 계속

여기서 _reassignSubworker()는 "남은 양이 가장 많은(=가장 느린) 조각"을 찾아 그 구간을 반으로 쪼개고, 새 조각을 TaskGroup에 즉시 던져 넣는다. 즉 느린 조각을 실시간으로 더 잘게 나눠 병렬성을 높이는 방식이다. "AI"라는 이름과 달리 신경망은 없지만, 피드백을 측정해 스스로 파라미터를 조절하는 제어 루프라는 점에서 자동화된 튜닝이 맞다.

4-5. 재개(resume)는 어떻게 — .ghd 진행 파일

다운로드를 껐다 켜도 이어받으려면 "어디까지 받았는지"를 디스크에 남겨야 한다. GD3는 감시자가 1초마다 각 조각의 (start, position, end) 삼중값을 이진 형식(struct.pack, 리틀엔디안 64비트)으로 파일명.ghd에 덮어쓴다. 다시 켜면 이 .ghd를 읽어 각 조각을 멈춘 지점부터 되살린다. 텍스트 JSON이 아니라 고정폭 이진이라 쓰기가 빠르고 파싱이 단순하다.

5디렉토리 구조 해부

구조에서 읽어야 할 것: 플랫폼 공용 로직(app)과 프로토콜별 확장(features)이 확실히 분리돼 있고, 팩마다 manifest.toml이 있어 "이 팩이 무엇을 의존하고 무엇을 제공하는가"를 선언한다. featureService.load()가 이 매니페스트들을 읽어 의존성 순서대로(위상 정렬) 임포트한다. 새 프로토콜을 추가하려면 features/ 아래 폴더 하나만 만들면 되는 구조다.

6학습 포인트 — 기술별 배울 것

① asyncio와 GUI(Qt)를 안전하게 잇는 법

GUI 앱의 고질적 난제 — 무거운 네트워크 작업을 하면 화면이 멈춘다. GD3는 coroutineRunner가 별도 QThread에서 asyncio 루프를 돌리고, 결과만 Qt 메인 스레드로 콜백을 넘겨 화면 갱신을 안전하게 한다. "이벤트 루프 두 개(asyncio + Qt)를 어떻게 공존시키나"의 실전 정답지다.

② HTTP Range·pwrite로 병렬 다운로드 직접 구현

4장의 무병합 엔진은 그 자체로 훌륭한 학습 주제다. Range 헤더로 구간을 요청하고 os.pwrite로 오프셋에 쓰는 것만 알면, 100줄 안팎의 미니 병렬 다운로더를 스스로 만들 수 있다. 서버가 Range를 지원하지 않을 때(단일 스트림)의 폴백 처리까지 보면 실전 감각이 완성된다.

③ 액터 아키텍처와 "단일 작성자" 규율

CONTEXT.md는 그 자체로 대규모 앱을 어떻게 층으로 나누고, 상태 소유권을 어떻게 못 박는지에 대한 교과서다. "매니저·컨트롤러·프로바이더 같은 구조적 이름을 쓰지 말고, 도메인 개념으로 이름 지어라(taskService, speedMeter)" 같은 명명 철학까지 담겨 있다. 협업 코드의 이름 짓기로 고민해 본 개발자에게 특히 값지다.

④ 플러그인 시스템 설계

매니페스트 선언 → 위상 정렬 → 우선순위 기반 라우팅으로 이어지는 featureService는 "확장 가능한 앱"의 표본이다. 파서가 스스로 하지 않고 parse()를 재귀 호출해 위임하는 GitHubParser·MergeParser의 조합 패턴도 눈여겨볼 만하다.

⑤ 브라우저 확장(MV3)과 데스크톱 앱의 통신

확장은 WebSocket 프로토콜 v3(hello → hello_ack → subscribe → snapshot)로 앱과 대화하고, 연결이 끊기면 작업을 큐에 쌓아뒀다 재연결 시 흘려보낸다. "브라우저 ↔ 네이티브 앱"을 잇는 실전 아키텍처를 통째로 읽을 수 있다.

7시스템 · 실행 요구사항

사용자 — 미리 빌드된 앱 설치

개발자 — 소스에서 실행

# 1) uv 설치 후 저장소 클론
git clone https://github.com/XiaoYouChR/Ghost-Downloader-3.git
cd Ghost-Downloader-3

# 2) uv가 pyproject.toml/uv.lock 보고 가상환경+의존성 자동 구성
uv sync

# 3) 데스크톱 진입점 실행
uv run python Ghost-Downloader-3.py

플랫폼 조건부 의존성이 자동 처리된다 — 윈도우면 winloop·libtorrent-windows-dll, 맥/리눅스면 uvloop, 맥이면 pyobjc가 각각 설치된다. 배포판을 직접 만들려면 nuitka로 컴파일하며, FFmpeg·N_m3u8DL-RE 같은 외부 바이너리는 앱이 필요할 때 Binary Runtime으로 내려받아 설치한다.

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

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

여력이 되면 보너스로 TLS 지문(JA3/JA4)과 비트토렌트 프로토콜(libtorrent 세션·트래커·조각 교환)을 각각 하루씩 파보면, GD3가 왜 그렇게 많은 라이브러리를 조합했는지 전모가 보인다.

10핵심 키워드 사전

11참고 링크