352 lines
10 KiB
Markdown
352 lines
10 KiB
Markdown
# 🤖 Cloudflare Workers 텔레그램 AI 봇
|
|
|
|
> **Cloudflare Workers + D1 + OpenAI**를 활용한 서버리스 아키텍처 기반의 지능형 텔레그램 봇입니다.
|
|
> 사용자별 프로필을 자동으로 생성하고 기억하며, 예치금 관리 및 도메인 등록 등의 복잡한 작업을 수행할 수 있습니다.
|
|
|
|
|
|
|
|
|
|
|
|
## 📚 문서 안내
|
|
|
|
- **[사용자 가이드 (User Guide)](./docs/USER_GUIDE.md)**: 봇 사용법, 명령어, 예치금/도메인 기능 설명
|
|
- **[시스템 아키텍처 (Architecture)](./docs/ARCHITECTURE.md)**: 기술 구조, 데이터 흐름, 프로필 시스템 상세
|
|
- **[개발자 가이드 (Dev Guide)](./CLAUDE.md)**: 개발 환경 설정, 컨벤션, 트러블슈팅
|
|
|
|
---
|
|
|
|
## ✨ 주요 기능
|
|
|
|
* 🧠 **AI 기반 개인화**: 대화 내용을 분석하여 사용자의 관심사와 맥락을 기억하는 **동적 프로필 시스템**
|
|
* 🛠 **Function Calling**: 날씨, 검색, 계산, 시간 등 다양한 도구를 자연어로 호출
|
|
* 💰 **예치금 시스템**: 은행 SMS 자동 파싱(AI 폴백 지원) 및 양방향 매칭을 통한 자동 충전
|
|
* 🌐 **도메인 관리**: 도메인 검색, 추천(AI), 가격 조회, 등록, DNS 관리 통합
|
|
* 🤖 **서버 추천 AI 상담**: 30년 경력 전문가 페르소나 기반 대화형 서버 추천, 최신 트렌드 검색 지원 (KV 세션 관리)
|
|
* ⚡ **서버리스**: Cloudflare Workers + KV로 긴 작업도 안정적 처리
|
|
* 🌐 **웹 채팅 UI**: 브라우저와 API로 봇 테스트 가능 ([telegram-cli](./telegram-cli/README.md))
|
|
|
|
### 🚀 성능 최적화
|
|
|
|
* **N+1 쿼리 제거**: Cron 작업 99% 쿼리 감소 (100건: 101 → 1 쿼리)
|
|
* **병렬 API 호출**: 도메인 추천 80% 속도 향상
|
|
* **KV 캐싱**: TLD 가격 1시간 캐싱으로 중복 조회 방지
|
|
* **Circuit Breaker**: OpenAI API 장애 시 자동 차단 및 복구
|
|
* **Retry 로직**: 15개 외부 API에 지수 백오프 + 지터 적용
|
|
|
|
---
|
|
|
|
## 🚀 빠른 시작 (배포 가이드)
|
|
|
|
### 1. 환경 설정
|
|
```bash
|
|
# 의존성 설치
|
|
npm install
|
|
|
|
# Wrangler 로그인
|
|
npx wrangler login
|
|
```
|
|
|
|
### 2. 데이터베이스 생성
|
|
```bash
|
|
npx wrangler d1 create telegram-conversations
|
|
npx wrangler d1 execute telegram-conversations --file=schema.sql
|
|
```
|
|
*생성된 `database_id`를 `wrangler.toml`에 반영해야 합니다.*
|
|
|
|
### 3. KV Namespace 생성
|
|
```bash
|
|
# Rate Limiting용 KV Namespace 생성 (필수)
|
|
npx wrangler kv:namespace create RATE_LIMIT_KV
|
|
|
|
# 서버 상담 세션 저장용 KV Namespace 생성 (서버 추천 기능 사용 시 필수)
|
|
npx wrangler kv:namespace create SESSION_KV
|
|
|
|
# 출력된 id를 wrangler.toml의 [[kv_namespaces]] 섹션에 입력
|
|
```
|
|
|
|
### 4. Queue 생성
|
|
```bash
|
|
# 서버 프로비저닝용 Queue 생성 (서버 기능 사용 시 필수)
|
|
npx wrangler queues create server-provision-queue
|
|
npx wrangler queues create provision-dlq
|
|
```
|
|
|
|
### 5. 환경변수 설정
|
|
|
|
#### 필수 Secrets
|
|
|
|
```bash
|
|
# Telegram Bot 설정
|
|
npx wrangler secret put BOT_TOKEN # @BotFather에서 발급
|
|
npx wrangler secret put WEBHOOK_SECRET # 임의의 강력한 문자열 (필수!)
|
|
|
|
# OpenAI API
|
|
npx wrangler secret put OPENAI_API_KEY # OpenAI API 키
|
|
```
|
|
|
|
#### 선택적 Secrets (기능별)
|
|
|
|
```bash
|
|
# 도메인 관련 (도메인 기능 사용 시)
|
|
npx wrangler secret put NAMECHEAP_API_KEY # namecheap-api 래퍼 인증
|
|
npx wrangler secret put NAMECHEAP_API_KEY_INTERNAL # Namecheap 실제 API 키
|
|
|
|
# 검색 (웹 검색 기능 사용 시)
|
|
npx wrangler secret put BRAVE_API_KEY # Brave Search API 키
|
|
|
|
# 예치금 API (namecheap-api 연동 시)
|
|
npx wrangler secret put DEPOSIT_API_SECRET # 외부 서비스 연동용
|
|
|
|
# 서버 관리 (VPS/클라우드 기능 사용 시)
|
|
npx wrangler secret put LINODE_API_KEY # Linode API 키
|
|
npx wrangler secret put VULTR_API_KEY # Vultr API 키
|
|
npx wrangler secret put SERVER_ADMIN_ID # 서버 관리 알림 Telegram ID
|
|
```
|
|
|
|
#### 환경별 설정 (선택)
|
|
|
|
`wrangler.toml`의 환경변수는 기본값이 설정되어 있어 생략 가능합니다.
|
|
환경별로 다른 엔드포인트를 사용하려면 override하세요:
|
|
|
|
```toml
|
|
[vars]
|
|
OPENAI_API_BASE = "https://your-custom-gateway.com/openai"
|
|
NAMECHEAP_API_URL = "https://your-api.example.com"
|
|
```
|
|
|
|
**사용 가능한 환경변수:**
|
|
- `OPENAI_API_BASE` - OpenAI API Gateway
|
|
- `NAMECHEAP_API_URL` - Namecheap API 래퍼
|
|
- `WHOIS_API_URL` - WHOIS 조회 서비스
|
|
- `CONTEXT7_API_BASE` - 문서 조회 API
|
|
- `BRAVE_API_BASE` - 검색 API
|
|
- `WTTR_IN_URL` - 날씨 API
|
|
- `HOSTING_SITE_URL` - 공식 웹사이트
|
|
|
|
### 6. 배포
|
|
|
|
#### 배포 전 체크리스트
|
|
|
|
```bash
|
|
# 1. 로컬 테스트
|
|
npm run dev
|
|
|
|
# 2. TypeScript 컴파일 확인
|
|
npx tsc --noEmit
|
|
|
|
# 3. 환경변수 확인
|
|
npx wrangler secret list
|
|
|
|
# 4. KV Namespace 확인
|
|
npx wrangler kv:namespace list
|
|
```
|
|
|
|
#### 배포 실행
|
|
|
|
```bash
|
|
npm run deploy
|
|
```
|
|
|
|
#### 배포 후 확인
|
|
|
|
```bash
|
|
# Health check
|
|
curl https://telegram-summary-bot.kappa-d8e.workers.dev/health
|
|
|
|
# Webhook 상태 (token + secret 필요)
|
|
curl "https://telegram-summary-bot.kappa-d8e.workers.dev/webhook-info?token=${BOT_TOKEN}&secret=${WEBHOOK_SECRET}"
|
|
|
|
# 실시간 로그
|
|
npm run tail
|
|
```
|
|
|
|
### 7. Webhook 연결
|
|
|
|
```bash
|
|
# 웹훅 설정 (token + secret 필요)
|
|
curl "https://<YOUR_WORKER_URL>/setup-webhook?token=${BOT_TOKEN}&secret=${WEBHOOK_SECRET}"
|
|
```
|
|
|
|
#### ⚠️ 주의사항
|
|
|
|
- **WEBHOOK_SECRET 필수**: 미설정 시 모든 webhook 요청이 거부됩니다.
|
|
- **RATE_LIMIT_KV 필수**: 미생성 시 Rate Limiting이 비활성화되어 DoS 공격에 취약합니다.
|
|
- **SESSION_KV 필수 (서버 추천 기능 사용 시)**: 미생성 시 서버 상담 세션 관리가 동작하지 않습니다.
|
|
- **환경변수 기본값**: 대부분의 외부 API URL은 기본값이 설정되어 있습니다. 프로덕션 환경에서는 기본값을 그대로 사용하거나, 필요시에만 override하세요.
|
|
|
|
---
|
|
|
|
## 📡 API Documentation
|
|
|
|
본 프로젝트는 외부 서비스 연동을 위한 REST API를 제공합니다.
|
|
|
|
**완전한 OpenAPI 문서**: [`openapi.yaml`](./openapi.yaml)
|
|
|
|
### 주요 엔드포인트
|
|
|
|
| 엔드포인트 | 메서드 | 인증 | 용도 |
|
|
|-----------|--------|------|------|
|
|
| `/health` | GET | None | Health check |
|
|
| `/api/contact` | POST | CORS | 웹사이트 문의 폼 |
|
|
| `/api/deposit/balance` | GET | API Key | 잔액 조회 (Internal) |
|
|
| `/api/deposit/deduct` | POST | API Key | 잔액 차감 (Internal) |
|
|
| `/api/metrics` | GET | Bearer | 시스템 모니터링 |
|
|
|
|
### 인증 방식
|
|
|
|
- **API Key**: `X-API-Key` 헤더 (Deposit API)
|
|
- **Bearer Token**: `Authorization: Bearer {token}` (Metrics API)
|
|
- **CORS**: `hosting.inouter.com`만 허용 (Contact Form)
|
|
|
|
### 문서 보기
|
|
|
|
```bash
|
|
# Swagger UI (로컬)
|
|
npx swagger-ui-watcher openapi.yaml
|
|
|
|
# HTML 문서 생성
|
|
npx redoc-cli bundle openapi.yaml -o docs/api.html
|
|
|
|
# 스펙 검증
|
|
npx @apidevtools/swagger-cli validate openapi.yaml
|
|
```
|
|
|
|
### External Consumers
|
|
|
|
- **namecheap-api**: 도메인 등록 시 예치금 조회/차감
|
|
- **hosting.inouter.com**: 웹사이트 문의 폼 제출
|
|
- **Monitoring Tools**: Circuit Breaker 상태 조회
|
|
|
|
자세한 내용은 [OpenAPI Specification](./openapi.yaml)을 참조하세요.
|
|
|
|
---
|
|
|
|
## 🌐 웹 채팅 인터페이스 (telegram-cli)
|
|
|
|
별도 Cloudflare Worker로 배포된 웹 채팅 UI 및 JSON API입니다.
|
|
|
|
### 엔드포인트
|
|
|
|
**배포 URL**: https://telegram-cli-web.kappa-d8e.workers.dev
|
|
|
|
| 엔드포인트 | 메서드 | 설명 |
|
|
|-----------|--------|------|
|
|
| `/` | GET | 웹 채팅 UI (브라우저 인터페이스) |
|
|
| `/api/chat` | POST | JSON API (프로그래밍 방식 접근) |
|
|
| `/health` | GET | Health check |
|
|
|
|
### 사용 예시
|
|
|
|
#### 웹 브라우저
|
|
```
|
|
https://telegram-cli-web.kappa-d8e.workers.dev
|
|
```
|
|
|
|
브라우저에서 접속하여 봇과 실시간 대화
|
|
|
|
#### JSON API (curl)
|
|
```bash
|
|
curl -s -X POST 'https://telegram-cli-web.kappa-d8e.workers.dev/api/chat' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"message": "안녕"}'
|
|
```
|
|
|
|
**응답:**
|
|
```json
|
|
{
|
|
"response": "안녕하세요! 무엇을 도와드릴까요?",
|
|
"time_ms": 1234
|
|
}
|
|
```
|
|
|
|
#### Claude Code 사용
|
|
Claude는 이 API를 사용하여 봇과 대화하고 기능을 테스트할 수 있습니다.
|
|
|
|
```bash
|
|
# 예치금 기능 테스트
|
|
curl -X POST 'https://telegram-cli-web.kappa-d8e.workers.dev/api/chat' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"message": "잔액 조회"}'
|
|
|
|
# 도메인 기능 테스트
|
|
curl -X POST 'https://telegram-cli-web.kappa-d8e.workers.dev/api/chat' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"message": "example.com 조회"}'
|
|
```
|
|
|
|
### 배포 방법
|
|
|
|
자세한 내용은 [telegram-cli/README.md](./telegram-cli/README.md)를 참조하세요.
|
|
|
|
---
|
|
|
|
## 🧪 테스트
|
|
|
|
### 자동화된 단위 테스트
|
|
|
|
프로젝트는 **Vitest**와 **Miniflare**를 사용하여 Cloudflare Workers 환경에서 단위 테스트를 실행합니다.
|
|
|
|
#### 테스트 실행
|
|
|
|
```bash
|
|
# 의존성 설치
|
|
npm install
|
|
|
|
# 모든 테스트 실행
|
|
npm test
|
|
|
|
# Watch 모드 (개발 중)
|
|
npm run test:watch
|
|
|
|
# 커버리지 리포트
|
|
npm run test:coverage
|
|
```
|
|
|
|
#### 테스트 범위
|
|
|
|
**deposit-agent.ts** (예치금 시스템):
|
|
- ✅ 음수/0원 금액 거부
|
|
- ✅ 동시성 처리 안전성
|
|
- ✅ Batch 부분 실패 처리
|
|
- ✅ 입금자명 7글자 매칭 로직
|
|
- ✅ 관리자 권한 검증
|
|
- ✅ 거래 상태 검증
|
|
|
|
**테스트 파일 위치**:
|
|
- `tests/deposit-agent.test.ts` - 예치금 시스템 테스트 (50+ test cases)
|
|
- `vitest.config.ts` - Vitest 설정 (Miniflare 환경)
|
|
- `tests/setup.ts` - D1 Database 초기화 및 헬퍼 함수
|
|
|
|
#### 테스트 아키텍처
|
|
|
|
- **환경**: Miniflare (in-memory SQLite)
|
|
- **모킹**: D1 Database, KV Namespace, 환경 변수
|
|
- **커버리지**: V8 Coverage Provider
|
|
- **실행 시간**: <10초 (전체 테스트 스위트)
|
|
|
|
#### 수동 테스트
|
|
|
|
자동화되지 않은 기능의 수동 테스트 예제:
|
|
- `src/services/__test__/notification.test.ts` - 관리자 알림 시스템
|
|
- `src/utils/__test__/logger.test.ts` - 구조화된 로깅
|
|
|
|
---
|
|
|
|
## 🛠 기술 스택
|
|
|
|
| 분류 | 기술 | 비고 |
|
|
|------|------|------|
|
|
| **Runtime** | Cloudflare Workers | Serverless |
|
|
| **DB** | Cloudflare D1 | SQLite |
|
|
| **Cache** | Cloudflare KV | Rate Limiting |
|
|
| **AI** | OpenAI GPT-4o-mini | Logic & Tools |
|
|
| **Fallback** | Workers AI (Llama 3) | Backup AI |
|
|
| **Testing** | Vitest + Miniflare | Unit Tests |
|
|
|
|
---
|
|
|
|
## 🤝 기여 및 문의
|
|
|
|
버그 신고나 기능 제안은 Issue를 등록해주세요.
|
|
소스 코드는 **[Gitea](https://gitea.inouter.com/kaffa/telegram-bot-workers)**에서 관리됩니다.
|