🤖 Cloudflare Workers 텔레그램 AI 봇

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

📚 문서 안내

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

---

✨ 주요 기능

• 🧠 AI 기반 개인화: 대화 내용을 분석하여 사용자의 관심사와 맥락을 기억하는 동적 프로필 시스템
• 🛠 Function Calling: 날씨, 검색, 계산, 시간 등 다양한 도구를 자연어로 호출
• 💰 예치금 시스템: 은행 SMS 자동 파싱(AI 폴백 지원) 및 양방향 매칭을 통한 자동 충전
• 🌐 도메인 관리: 도메인 검색, 추천(AI), 가격 조회, 등록, DNS 관리 통합
• 🤖 서버 추천 AI 상담: 30년 경력 전문가 페르소나 기반 대화형 서버 추천, 최신 트렌드 검색 지원 (KV 세션 관리)
• ⚡ 서버리스: Cloudflare Workers + KV로 긴 작업도 안정적 처리
• 🌐 웹 채팅 UI: 브라우저와 API로 봇 테스트 가능 (telegram-cli)

🚀 성능 최적화

• 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

# 서버 상담 세션 저장용 KV Namespace 생성 (서버 추천 기능 사용 시 필수)
npx wrangler kv:namespace create SESSION_KV

# 출력된 id를 wrangler.toml의 [[kv_namespaces]] 섹션에 입력

4. Queue 생성

# 서버 프로비저닝용 Queue 생성 (서버 기능 사용 시 필수)
npx wrangler queues create server-provision-queue
npx wrangler queues create provision-dlq

5. 환경변수 설정

필수 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 # 외부 서비스 연동용

# 서버 관리 (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하세요:

[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. 배포

배포 전 체크리스트

# 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 상태 (token + secret 필요)
curl "https://telegram-summary-bot.kappa-d8e.workers.dev/webhook-info?token=${BOT_TOKEN}&secret=${WEBHOOK_SECRET}"

# 실시간 로그
npm run tail

7. Webhook 연결

# 웹훅 설정 (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

주요 엔드포인트

엔드포인트	메서드	인증	용도
/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)

문서 보기

# 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을 참조하세요.

---

🌐 웹 채팅 인터페이스 (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)

curl -s -X POST 'https://telegram-cli-web.kappa-d8e.workers.dev/api/chat' \
  -H 'Content-Type: application/json' \
  -d '{"message": "안녕"}'

응답:

{
  "response": "안녕하세요! 무엇을 도와드릴까요?",
  "time_ms": 1234
}

Claude Code 사용

Claude는 이 API를 사용하여 봇과 대화하고 기능을 테스트할 수 있습니다.

# 예치금 기능 테스트
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를 참조하세요.

---

🧪 테스트

자동화된 단위 테스트

프로젝트는 Vitest와 Miniflare를 사용하여 Cloudflare Workers 환경에서 단위 테스트를 실행합니다.

테스트 실행

# 의존성 설치
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**에서 관리됩니다.