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>
143 lines
4.5 KiB
Markdown
143 lines
4.5 KiB
Markdown
# 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 자격증명 획득
|
|
|
|
1. https://my.telegram.org 접속
|
|
2. "API development tools" 클릭
|
|
3. `API_ID`와 `API_HASH` 복사
|
|
|
|
### 2. 환경 변수 설정
|
|
|
|
```bash
|
|
# 컨테이너에 접속
|
|
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. 서비스 시작
|
|
|
|
```bash
|
|
# 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. 프론트엔드 빌드
|
|
|
|
```bash
|
|
# 컨테이너 내에서
|
|
cd /opt/telegram-web-client/frontend
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## Development
|
|
|
|
### 로컬 개발 (macOS)
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
### 컨테이너 접속
|
|
|
|
```bash
|
|
incus exec jp1:telegram-web-client -- bash
|
|
```
|
|
|
|
### 로그 확인
|
|
|
|
```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)
|