🤖 Cloudflare Workers 텔레그램 AI 봇

Cloudflare Workers + D1 + OpenAI를 활용한 서버리스 아키텍처 기반의 지능형 텔레그램 봇입니다. 사용자별 프로필을 자동으로 생성하고 기억하며, 예치금 관리 및 도메인 등록 등의 복잡한 작업을 수행할 수 있습니다.

📚 문서 안내

• 사용자 가이드 (User Guide): 봇 사용법, 명령어, 예치금/도메인 기능 설명
• 시스템 아키텍처 (Architecture): 기술 구조, 데이터 흐름, 프로필 시스템 상세
• 개발자 가이드 (Dev Guide): 개발 환경 설정, 컨벤션, 트러블슈팅

---

✨ 주요 기능

• 🧠 AI 기반 개인화: 대화 내용을 분석하여 사용자의 관심사와 맥락을 기억하는 동적 프로필 시스템
• 🛠 Function Calling: 날씨, 검색, 계산, 시간 등 다양한 도구를 자연어로 호출
• 💰 예치금 시스템: 은행 SMS 자동 파싱(AI 폴백 지원) 및 양방향 매칭을 통한 자동 충전
• 🌐 도메인 관리: 도메인 검색, 추천(AI), 가격 조회, 등록, DNS 관리 통합
• ⚡ 서버리스: Cloudflare Workers 위에서 동작하여 별도의 서버 관리 불필요

🚀 성능 최적화

• N+1 쿼리 제거: Cron 작업 99% 쿼리 감소 (100건: 101 → 1 쿼리)
• 병렬 API 호출: 도메인 추천 80% 속도 향상
• KV 캐싱: TLD 가격 1시간 캐싱으로 중복 조회 방지
• Circuit Breaker: OpenAI API 장애 시 자동 차단 및 복구
• Retry 로직: 15개 외부 API에 지수 백오프 + 지터 적용

---

🚀 빠른 시작 (배포 가이드)

1. 환경 설정

# 의존성 설치
npm install

# Wrangler 로그인
npx wrangler login

2. 데이터베이스 생성

npx wrangler d1 create telegram-conversations
npx wrangler d1 execute telegram-conversations --file=schema.sql

생성된 database_id를 wrangler.toml에 반영해야 합니다.

3. KV Namespace 생성

# Rate Limiting용 KV Namespace 생성 (필수)
npx wrangler kv:namespace create RATE_LIMIT_KV
# 출력된 id를 wrangler.toml의 [[kv_namespaces]] 섹션에 입력

4. 환경변수 설정

필수 Secrets

# 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 (기능별)

# 도메인 관련 (도메인 기능 사용 시)
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 # 외부 서비스 연동용

환경별 설정 (선택)

wrangler.toml의 환경변수는 기본값이 설정되어 있어 생략 가능합니다. 환경별로 다른 엔드포인트를 사용하려면 override하세요:

[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 - 공식 웹사이트

5. 배포

배포 전 체크리스트

# 1. 로컬 테스트
npm run dev

# 2. TypeScript 컴파일 확인
npx tsc --noEmit

# 3. 환경변수 확인
npx wrangler secret list

# 4. KV Namespace 확인
npx wrangler kv:namespace list

배포 실행

npm run deploy

배포 후 확인

# Health check
curl https://telegram-summary-bot.kappa-d8e.workers.dev/health

# Webhook 상태
curl https://telegram-summary-bot.kappa-d8e.workers.dev/webhook-info

# 실시간 로그
npm run tail

6. Webhook 연결

# 웹훅 설정 (배포된 URL 사용)
curl https://<YOUR_WORKER_URL>/setup-webhook

⚠️ 주의사항

• WEBHOOK_SECRET 필수: 미설정 시 모든 webhook 요청이 거부됩니다.
• KV Namespace 필수: 미생성 시 Rate Limiting이 비활성화되어 DoS 공격에 취약합니다.
• 환경변수 기본값: 대부분의 외부 API URL은 기본값이 설정되어 있습니다. 프로덕션 환경에서는 기본값을 그대로 사용하거나, 필요시에만 override하세요.

---

🛠 기술 스택

분류	기술	비고
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

---

🤝 기여 및 문의

버그 신고나 기능 제안은 Issue를 등록해주세요. 소스 코드는 **Gitea**에서 관리됩니다.