telegram-web-relay - Telegram Web을 내 서버 뒤에 두고 싶었다
Telegram은 거의 모든 곳에서 쓴다. 모바일 앱도 좋고, 데스크톱 앱도 좋고, 웹 클라이언트도 잘 만들어져 있다.
그런데 개인 자동화와 메신저 기반 도구를 많이 만들다 보니 한 가지 필요가 생겼다.
브라우저가 Telegram에 직접 붙는 대신, 내가 관리하는 서버가 Telegram 세션을 갖고 브라우저는 그 서버하고만 이야기하면 어떨까?
처음부터 공개 프로젝트를 만들 생각은 아니었다. 내 환경에서 쓸 self-hosted Telegram Web 구조가 필요했고, 그 실험으로 telegram-web-relay를 만들었다.
왜 relay가 필요했나
Telegram Web은 잘 만들어진 클라이언트다. 하지만 일반적인 웹 클라이언트 구조에서는 브라우저가 Telegram 쪽 연결을 직접 책임진다.
내가 원했던 것은 조금 달랐다.
- Telegram 세션은 내가 관리하는 서버에 둔다
- 브라우저는 relay 서버에만 연결한다
- TDLib 세션 데이터와 다운로드 파일은 서버에서 관리한다
- 웹 UI는 HTTP와 Socket.IO로 relay와 통신한다
- 필요하면 chat archive 같은 서버 측 기능을 붙인다
즉, 핵심은 "웹 UI"와 "Telegram 세션"을 분리하는 것이다.
구조는 단순하다.
Browser UI --HTTP + Socket.IO--> telegram-web-relay --TDLib/MTProto--> Telegram
브라우저는 Telegram 프로토콜을 직접 알 필요가 없다. relay가 TDLib와 Telegram 연결을 맡고, 브라우저 친화적인 API와 이벤트 스트림만 제공한다.
만들다 보니 repo를 나눠야 했다
처음에는 server와 client가 한 덩어리처럼 보였다. 하지만 정리하다 보니 둘은 역할도, 라이선스도, 관리 방식도 달랐다.
그래서 공개를 준비하면서 repo를 나눴다.
| Repository | Role | License |
|---|---|---|
| telegram-web-relay | Node.js TDLib relay server | MIT |
| telegram-web-relay-client | Browser UI adapted for Socket.IO relay transport | GPL-3.0-or-later |
클라이언트는 Telegram-tt 기반이라 GPL 계열을 유지해야 하고, relay 서버는 독립 서버로 MIT 라이선스를 적용했다. 두 프로젝트는 네트워크로만 통신한다.
열어두기 위해 정리한 것
개인 환경에서 돌아가던 코드를 그대로 열 수는 없었다. 최소한 누군가가 읽고 실행해볼 수 있는 형태로 정리해야 했다.
.env.example기반 설정- TDLib 세션과 다운로드 파일 보관 위치 정리
- Dockerfile과
docker-compose.yml - README의 quickstart
- 보안 주의사항
- 서버와 클라이언트 repo 분리
설치 흐름
relay 쪽 기본 실행은 이렇게 잡았다.
git clone https://github.com/lisyoen/telegram-web-relay.git
cd telegram-web-relay
cp .env.example .env
.env에는 Telegram API credential과 세션 secret을 넣는다.
TELEGRAM_API_ID=123456
TELEGRAM_API_HASH=your_api_hash
SESSION_SECRET=replace-this
PORT=9087
Docker로 실행하면 된다.
docker compose up -d
브라우저 UI를 함께 쓰려면 client repo를 빌드한 뒤 relay의 V2_DIST_PATH로 연결한다.
보안 기준
이 프로젝트에서 제일 중요한 부분은 보안이다. relay는 Telegram 인증 세션을 가진다. 즉, 단순한 프록시가 아니라 개인 메시징 세션을 보관하는 백엔드다.
공개 서버로 운영하려면 HTTPS, 접근 제어, 강한 SESSION_SECRET, TDLib 데이터 백업/삭제 정책이 필요하다.
README에도 이 점을 명시했다. 이 프로젝트는 누군가의 공개 SaaS가 아니라, 자기 계정과 자기 서버를 직접 책임지는 self-hosted 도구에 가깝다.
왜 열었나
개인적으로 필요해서 만든 도구지만, 비슷한 필요를 가진 사람이 있을 수 있다고 봤다.
- Telegram Web을 self-hosted 구조로 실험하고 싶은 사람
- TDLib 세션을 서버 쪽에 두고 싶은 사람
- Telegram Web UI와 서버 relay를 분리해서 연구하고 싶은 사람
- Socket.IO 기반으로 메시징 클라이언트를 붙여보고 싶은 사람
아직 완성형 제품은 아니다. 하지만 "브라우저 클라이언트와 Telegram 세션을 분리한다"는 실험의 출발점으로는 충분하다고 생각했다.
그래서 개인 도구로만 묻어두지 않고, 실행 가능한 형태로 정리해서 열어두기로 했다.
Repository: