feat: add telegram-cli web chat interface and /api/chat endpoint
- Add telegram-cli Worker with web chat UI for browser-based bot testing - Add POST /api/chat authenticated endpoint (Bearer token, production enabled) - Fix ENVIRONMENT to production in wrangler.toml (was blocking Service Binding) - Add Service Binding (BOT_WORKER) for Worker-to-Worker communication - Add cloud-db-schema.sql for local development telegram-cli features: - Web UI at GET / with dark theme - JSON API at POST /api/chat - Service Binding to telegram-summary-bot Worker Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
kappa
324
telegram-cli/README.md
Normal file
324
telegram-cli/README.md
Normal file
@@ -0,0 +1,324 @@
|
||||
# Telegram Bot Web Chat UI
|
||||
|
||||
Cloudflare Worker로 변환된 웹 채팅 인터페이스 및 API 엔드포인트
|
||||
|
||||
## 기능
|
||||
|
||||
- **웹 채팅 UI** (GET /): 브라우저에서 봇과 대화
|
||||
- **JSON API** (POST /api/chat): Claude나 curl로 사용 가능
|
||||
- **Health Check** (GET /health): 상태 확인
|
||||
|
||||
## 배포 방법
|
||||
|
||||
### 1. 의존성 설치
|
||||
|
||||
```bash
|
||||
cd telegram-cli
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Secrets 설정
|
||||
|
||||
```bash
|
||||
# BOT_TOKEN 설정 (실제로는 사용하지 않지만 필수 변수)
|
||||
wrangler secret put BOT_TOKEN
|
||||
|
||||
# WEBHOOK_SECRET 설정 (Bot Worker /api/test 인증용)
|
||||
wrangler secret put WEBHOOK_SECRET
|
||||
```
|
||||
|
||||
**Vault에서 가져오기:**
|
||||
```bash
|
||||
vault kv get secret/telegram-bot
|
||||
```
|
||||
|
||||
### 3. 로컬 테스트
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
브라우저에서 http://localhost:8787 접속
|
||||
|
||||
### 4. 배포
|
||||
|
||||
```bash
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
배포 후 URL: https://telegram-cli-web.your-subdomain.workers.dev
|
||||
|
||||
## 엔드포인트
|
||||
|
||||
### GET /
|
||||
|
||||
웹 채팅 UI (HTML/CSS/JS 인라인)
|
||||
|
||||
**특징:**
|
||||
- 다크 테마
|
||||
- 실시간 응답 시간 표시
|
||||
- 로딩 상태 표시
|
||||
- Enter로 메시지 전송
|
||||
- 자동 스크롤
|
||||
|
||||
**사용법:**
|
||||
1. 브라우저에서 Worker URL 접속
|
||||
2. 메시지 입력창에 텍스트 입력
|
||||
3. Enter 키 또는 "전송" 버튼 클릭
|
||||
4. 봇 응답 대기 (응답 시간 표시됨)
|
||||
|
||||
### POST /api/chat
|
||||
|
||||
JSON API 엔드포인트
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"message": "서버 추천해줘"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"response": "봇 응답 내용...",
|
||||
"time_ms": 1234
|
||||
}
|
||||
```
|
||||
|
||||
**curl 예시:**
|
||||
```bash
|
||||
curl -X POST https://telegram-cli-web.your-subdomain.workers.dev/api/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "서버 추천해줘"}'
|
||||
```
|
||||
|
||||
**Claude가 사용하는 경우:**
|
||||
```bash
|
||||
# Claude는 이 API를 호출하여 봇과 대화할 수 있습니다
|
||||
curl -X POST https://telegram-cli-web.your-subdomain.workers.dev/api/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "날씨 알려줘"}'
|
||||
```
|
||||
|
||||
### GET /health
|
||||
|
||||
Health check 엔드포인트
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"timestamp": "2026-01-26T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 환경변수
|
||||
|
||||
### Secrets (wrangler secret put)
|
||||
|
||||
| 변수 | 설명 | 필수 |
|
||||
|------|------|------|
|
||||
| `BOT_TOKEN` | Telegram Bot Token (실제로는 미사용) | ✅ |
|
||||
| `WEBHOOK_SECRET` | Bot Worker /api/test 인증용 | ✅ |
|
||||
|
||||
### Variables (wrangler.toml)
|
||||
|
||||
| 변수 | 기본값 | 설명 |
|
||||
|------|--------|------|
|
||||
| `CHAT_ID` | `821596605` | Telegram Chat ID |
|
||||
| `BOT_WORKER_URL` | `https://telegram-summary-bot...` | Bot Worker URL |
|
||||
|
||||
**변경 방법:**
|
||||
```toml
|
||||
# wrangler.toml
|
||||
[vars]
|
||||
CHAT_ID = "YOUR_TELEGRAM_ID"
|
||||
BOT_WORKER_URL = "https://your-bot-worker.workers.dev"
|
||||
```
|
||||
|
||||
## 아키텍처
|
||||
|
||||
```
|
||||
브라우저 (Web UI)
|
||||
↓
|
||||
GET / → HTML/CSS/JS 반환
|
||||
↓
|
||||
POST /api/chat → telegram-cli-web Worker
|
||||
↓
|
||||
Bot Worker (/api/test)
|
||||
- message
|
||||
- chat_id
|
||||
- user_id
|
||||
- username: 'web-tester'
|
||||
↓
|
||||
Bot 응답 처리
|
||||
- DB 작업
|
||||
- AI 응답 생성
|
||||
- Function Calling
|
||||
↓
|
||||
Web UI로 응답 반환
|
||||
{ response, time_ms }
|
||||
```
|
||||
|
||||
## 테스트 시나리오
|
||||
|
||||
### 1. 웹 UI 테스트
|
||||
|
||||
브라우저에서 접속 후:
|
||||
|
||||
```
|
||||
# 기본 대화
|
||||
"안녕하세요"
|
||||
"날씨 알려줘"
|
||||
|
||||
# Function Calling 도구
|
||||
"서울 날씨"
|
||||
"ChatGPT 가격 검색"
|
||||
"123 * 456"
|
||||
"현재 시간"
|
||||
|
||||
# 도메인
|
||||
"example.com 조회"
|
||||
"도메인 추천해줘: 커피숍"
|
||||
|
||||
# 예치금
|
||||
"잔액 조회"
|
||||
"홍길동 5000원 입금"
|
||||
|
||||
# 서버
|
||||
"서버 추천해줘"
|
||||
"Linode 2GB 도쿄 서버 생성"
|
||||
```
|
||||
|
||||
### 2. API 테스트 (curl)
|
||||
|
||||
```bash
|
||||
# 기본 대화
|
||||
curl -X POST https://your-worker.workers.dev/api/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "안녕하세요"}'
|
||||
|
||||
# 서버 추천
|
||||
curl -X POST https://your-worker.workers.dev/api/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "서버 추천해줘"}'
|
||||
|
||||
# 잔액 조회
|
||||
curl -X POST https://your-worker.workers.dev/api/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "/deposit"}'
|
||||
```
|
||||
|
||||
### 3. Claude 사용 예시
|
||||
|
||||
Claude가 이 API를 사용하여 봇과 대화:
|
||||
|
||||
```bash
|
||||
# Claude는 이 엔드포인트를 호출하여 봇의 기능을 테스트할 수 있습니다
|
||||
curl -X POST https://telegram-cli-web.workers.dev/api/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "날씨 알려줘"}'
|
||||
```
|
||||
|
||||
## 로그 확인
|
||||
|
||||
```bash
|
||||
npm run tail
|
||||
```
|
||||
|
||||
실시간 로그 스트리밍으로 요청/응답 확인 가능
|
||||
|
||||
## 개발 모드
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
로컬에서 http://localhost:8787 접속하여 테스트
|
||||
|
||||
**로컬 개발 시 주의사항:**
|
||||
- Secrets는 `.dev.vars` 파일에 설정
|
||||
- 또는 `wrangler dev --remote`로 프로덕션 Secrets 사용
|
||||
|
||||
## 기술 스택
|
||||
|
||||
- **Runtime**: Cloudflare Workers (V8 Isolate)
|
||||
- **Language**: TypeScript
|
||||
- **Frontend**: Vanilla JavaScript (인라인 HTML)
|
||||
- **CSS**: 다크 테마, 애니메이션, 반응형
|
||||
|
||||
## 보안
|
||||
|
||||
- ✅ CORS 설정 완료 (모든 Origin 허용)
|
||||
- ✅ Bot Worker의 /api/test 엔드포인트는 Bearer 토큰으로 인증
|
||||
- ✅ Secrets는 Workers 환경변수로 안전하게 관리
|
||||
- ⚠️ 웹 UI는 공개 접근 가능 (인증 없음)
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### Secrets 미설정 오류
|
||||
|
||||
**증상:**
|
||||
```
|
||||
Bot Worker error: 401 - Unauthorized
|
||||
```
|
||||
|
||||
**해결:**
|
||||
```bash
|
||||
wrangler secret put WEBHOOK_SECRET
|
||||
# Vault에서 가져온 값 입력
|
||||
```
|
||||
|
||||
### Bot Worker URL 변경
|
||||
|
||||
`wrangler.toml` 수정:
|
||||
|
||||
```toml
|
||||
[vars]
|
||||
BOT_WORKER_URL = "https://new-worker.workers.dev"
|
||||
```
|
||||
|
||||
### CHAT_ID 변경
|
||||
|
||||
`wrangler.toml` 수정:
|
||||
|
||||
```toml
|
||||
[vars]
|
||||
CHAT_ID = "123456789"
|
||||
```
|
||||
|
||||
### 로컬 테스트 시 Secrets 설정
|
||||
|
||||
`.dev.vars` 파일 생성:
|
||||
|
||||
```env
|
||||
BOT_TOKEN=1234567890:ABC...
|
||||
WEBHOOK_SECRET=your-webhook-secret
|
||||
```
|
||||
|
||||
## 성능
|
||||
|
||||
- **응답 시간**: 평균 200-500ms (Bot Worker 처리 시간 포함)
|
||||
- **Cold Start**: ~100ms (Workers 특성상 매우 빠름)
|
||||
- **동시 요청**: 무제한 (Workers 스케일링)
|
||||
|
||||
## 라이센스
|
||||
|
||||
MIT
|
||||
|
||||
## 관련 파일
|
||||
|
||||
| 파일 | 역할 |
|
||||
|------|------|
|
||||
| `src/index.ts` | Worker 메인 로직 |
|
||||
| `wrangler.toml` | Workers 설정 |
|
||||
| `package.json` | 의존성 및 스크립트 |
|
||||
| `../src/routes/api.ts` | Bot Worker /api/test 엔드포인트 |
|
||||
| `../openapi.yaml` | API 문서 |
|
||||
|
||||
## 참고 자료
|
||||
|
||||
- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
|
||||
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
|
||||
- [Telegram Bot API](https://core.telegram.org/bots/api)
|
||||
Reference in New Issue
Block a user