TMD 설치 안내

TMD는 telegrammediadownloader를 가리킨다. 설정에 따라 Telegram 대화의 미디어를 내려받을 수 있고, 웹 페이지와 선택적 봇 제어 기능도 제공한다.

나는 Telegram 앱 자격 증명을 신청할 때 한 번 막혔고, 여러 네트워크를 시도했으며, 나중에는 지인의 도움도 받았다. 이 과정은 개인 기록으로 남겨두지만, 신청 실패를 무조건 "IP가 깨끗하지 않아서"라고 단정할 수는 없고, 남의 api_id와 api_hash를 빌려 쓰는 것도 권하지 않는다.

먼저 세 가지 자격 증명을 구분하자

api_id는 Telegram 앱의 숫자 ID이고, api_hash는 같은 앱의 해시다. 둘 다 my.telegram.org/apps에서 발급받는다. bot_token은 BotFather로 봇을 만든 뒤 받는 것으로, 선택적 봇 기능에만 쓴다.

api_id, api_hash와 BotFather가 주는 bot_token을 혼동하지 말자. 자신의 앱 자격 증명, 로그인 인증 코드, 세션 파일은 모두 남에게 보내거나 공개 저장소에 올리면 안 된다.

디렉터리와 설정 준비

먼저 공식 설정 예시에서 전체 설정을 복사한 뒤 필요한 필드를 수정한다. 아래는 관련 필드만 발췌한 것이므로, 전체 파일로 그대로 덮어써서는 안 된다:

api_id: 123456
api_hash: YOUR_OWN_API_HASH
save_path: /app/downloads
web_host: 0.0.0.0
web_port: 5000
web_login_secret: REPLACE_WITH_A_LONG_RANDOM_SECRET
allowed_user_ids:
  - me

api_id의 숫자도 예시일 뿐이다. 봇 제어가 필요하면 자신의 bot_token과 이를 사용할 계정을 추가로 설정한다. 다운로드 대상, 저장 경로, 미디어 유형은 전체 템플릿에 맞춰 설정하되, 자신이 접근하고 저장할 권리가 있는 콘텐츠만 내려받자.

Docker Compose 사용

프로젝트 이미지를 그대로 쓴다면 build: .를 함께 쓸 필요가 없다. 이 옵션은 로컬에 빌드 컨텍스트가 있어야 하는데, 튜토리얼에서 compose 파일만 복사한 경우에는 보통 존재하지 않는다.

services:
  telegram_media_downloader:
    image: tangyoha/telegram_media_downloader:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8066:5000"
    volumes:
      - ./config.yaml:/app/config.yaml
      - ./data.yaml:/app/data.yaml
      - ./downloads:/app/downloads
      - ./sessions:/app/sessions
      - ./temp:/app/temp
      - ./log:/app/log

실행 전에 프로젝트 예시에 맞춰 실제 config.yaml과 data.yaml 파일을 준비해야 하며, Docker가 같은 이름의 디렉터리로 자동 생성하게 두면 안 된다. 다운로드 디렉터리, 세션 디렉터리, 로그 디렉터리에도 컨테이너 사용자에게 올바른 읽기/쓰기 권한을 줘야 한다.

여기서는 호스트 진입점을 127.0.0.1로 제한했으며, 전체 공용 인터넷에 개방한 것이 아니다. 다른 컴퓨터에서 쓰려면 SSH 포워딩으로 접속하거나, 신뢰할 수 있는 내부망에서 인증이 걸린 리버스 프록시 뒤에 배포하자.

최초 로그인과 백그라운드 실행

처음에는 계정과 인증 코드를 대화형으로 입력해야 하므로, 먼저 다음을 실행한다:

docker compose run --rm telegram_media_downloader

터미널에서 프로젝트 안내에 따라 로그인을 마치고, 세션이 영속 디렉터리에 기록되는지 확인한 뒤 이번 포그라운드 실행을 중지하고 백그라운드 서비스를 시작한다:

docker compose up -d
docker compose logs --tail=100 telegram_media_downloader

최초 실행 시 만들어진 세션 파일은 잃어버리면 안 된다. 그렇지 않으면 컨테이너를 다시 만든 뒤에도 다시 로그인해야 할 수 있다. "일단 돌아가게" 하려고 임시로 만든 세션을 비워질 디렉터리에 마운트하지 말자.

원격 서버라면 자신의 컴퓨터에서 아래 포워딩을 실행한 뒤 http://127.0.0.1:8066을 열면 된다. your-server는 실제 서버 주소로 바꾼다:

ssh -L 8066:127.0.0.1:8066 your-user@your-server

문제가 생기면 어느 계층을 볼까

로그인 실패는 먼저 자신의 앱 자격 증명, 계정 상태, 인증 코드 흐름을 확인한다. 웹 페이지가 열리지 않으면 컨테이너가 5000 포트를 리슨하는지, 포트 매핑과 SSH 포워딩을 확인한다. 다운로드 결과가 없으면 세션 설정, 파일 유형, 대상 권한, 로그를 확인한다. 이들은 같은 종류의 장애가 아니다.

Rclone은 다운로드가 끝난 뒤 선택적으로 쓰는 전송 도구다. 먼저 로컬 다운로드와 영속화가 정상 동작하게 만든 다음, 원격과 마운트 경로를 따로 설정하자. 서버의 $HOME과 컨테이너 내부 경로를 같은 것으로 착각하면 안 된다.

참고: 프로젝트 설명, Compose 예시. 이 글은 설정 점검까지만 다루며, 여러분의 Telegram 계정에 로그인하거나 실제로 미디어를 내려받지는 않았다.