e610a45fcf
- Backend: FastAPI + Telethon v2 WebSocket server - Frontend: React + TypeScript + Vite + Zustand - Features: Phone auth, 2FA, real-time bot chat - Fix: Use chats= instead of from_users= to sync messages from all devices - Config: BOT_USERNAME=AnvilForgeBot Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
4.5 KiB
4.5 KiB
Telegram Web Client
웹소켓을 이용해 Telegram 봇(telegram-bot-workers)과 대화하는 웹 앱
Stack
- Backend: Python + Telethon v2 + FastAPI WebSocket
- Frontend: React + TypeScript + Vite + Zustand
- Infrastructure: Incus 컨테이너 (Debian 13) on jp1
Setup
1. Telegram API 자격증명 획득
- https://my.telegram.org 접속
- "API development tools" 클릭
API_ID와API_HASH복사
2. 환경 변수 설정
# 컨테이너에 접속
incus exec jp1:telegram-web-client -- bash
# .env 파일 생성
cd /opt/telegram-web-client/backend
cp .env.example .env
# 편집
vi .env
# TELEGRAM_API_ID=your_api_id
# TELEGRAM_API_HASH=your_api_hash
# BOT_USERNAME=telegram_summary_bot
3. 서비스 시작
# systemd 서비스 등록
incus file push telegram-web-client.service jp1:telegram-web-client/etc/systemd/system/
# 서비스 활성화 및 시작
incus exec jp1:telegram-web-client -- systemctl daemon-reload
incus exec jp1:telegram-web-client -- systemctl enable telegram-web-client
incus exec jp1:telegram-web-client -- systemctl start telegram-web-client
# 상태 확인
incus exec jp1:telegram-web-client -- systemctl status telegram-web-client
4. 프론트엔드 빌드
# 컨테이너 내에서
cd /opt/telegram-web-client/frontend
npm install
npm run build
Development
로컬 개발 (macOS)
# Backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your credentials
uvicorn main:app --reload --port 8000
# Frontend (별도 터미널)
cd frontend
npm install
npm run dev
컨테이너 접속
incus exec jp1:telegram-web-client -- bash
로그 확인
incus exec jp1:telegram-web-client -- journalctl -u telegram-web-client -f
Architecture
┌─────────────────┐ WebSocket ┌─────────────────────────────┐
│ React Frontend │◄──────────────────►│ FastAPI Backend (Debian) │
│ (브라우저) │ │ │
└─────────────────┘ │ ┌─────────────────────┐ │
│ │ Telethon v2 Client │ │
│ │ (MTProto) │ │
│ └──────────┬──────────┘ │
└─────────────┼───────────────┘
│
▼
┌─────────────────────────────┐
│ Telegram API (MTProto) │
│ ↔ telegram-bot-workers 봇 │
└─────────────────────────────┘
WebSocket Messages
Client → Server
| Type | Data | Description |
|---|---|---|
check_auth |
{} |
인증 상태 확인 |
send_code |
{phone} |
인증 코드 전송 요청 |
verify_code |
{phone, code, phone_code_hash} |
코드 검증 |
verify_password |
{password} |
2FA 비밀번호 검증 |
send_message |
{text} |
메시지 전송 |
get_history |
{} |
채팅 기록 조회 |
Server → Client
| Type | Data | Description |
|---|---|---|
connected |
{session_id} |
연결 완료 |
auth_status |
{authenticated, user_id, ...} |
인증 상태 |
code_sent |
{phone, phone_code_hash} |
코드 전송됨 |
need_password |
{message} |
2FA 필요 |
auth_success |
{user_id, username, ...} |
인증 성공 |
auth_error |
{message} |
인증 실패 |
history |
{messages} |
채팅 기록 |
message_sent |
{id, text, date, ...} |
메시지 전송됨 |
new_message |
{id, text, date, ...} |
새 메시지 수신 |
Container Info
- Name:
jp1:telegram-web-client - IP:
incus exec jp1:telegram-web-client -- ip a - Port: 8000 (Backend API/WebSocket)