481 lines
14 KiB
Markdown
481 lines
14 KiB
Markdown
# 카카오맵 리뷰 분석 서비스 (교육용)
|
|
|
|
AI 기반 리뷰 분석을 통해 소상공인의 고객 피드백 관리를 지원하는 RESTful API 서비스입니다.
|
|
|
|
## ⚠️ 중요 법적 경고사항
|
|
|
|
**이 서비스는 교육 목적으로만 제작되었습니다.**
|
|
|
|
### 법적 위험
|
|
- 카카오 이용약관 위반 → 계정 정지, 법적 조치
|
|
- 개인정보보호법(PIPA) 위반 → 과태료 최대 3억원
|
|
- 저작권 및 데이터베이스권 침해 → 손해배상
|
|
- 업무방해죄 → 5년 이하 징역 또는 1천500만원 이하 벌금
|
|
|
|
### 합법적 대안
|
|
- **카카오 공식 API 활용** ([developers.kakao.com](https://developers.kakao.com))
|
|
- 점주 대상 자체 가게 관리 서비스 개발
|
|
- 사용자 동의 기반 데이터 수집 앱
|
|
- 카카오와 정식 파트너십 체결
|
|
|
|
**실제 서비스 사용을 금지합니다!**
|
|
|
|
---
|
|
|
|
## 📋 프로젝트 개요
|
|
|
|
### 주요 기능
|
|
- 🔍 **카카오맵 리뷰 분석**: HTML 파싱 및 Selenium 기반 동적 수집
|
|
- 🤖 **AI 기반 피드백**: Claude API 연동을 통한 맞춤형 개선 방안 제시
|
|
- 📊 **감정 분석**: 긍정/부정/중립 감정 분류 및 통계
|
|
- 💾 **Vector DB 연동**: 유사 케이스 검색 및 템플릿 활용
|
|
- 🚀 **RESTful API 제공**: FastAPI 기반의 완전한 API 서비스
|
|
- 📚 **Swagger UI 지원**: 자동 생성되는 API 문서
|
|
- ☸️ **Kubernetes 배포**: 완전한 컨테이너 오케스트레이션 지원
|
|
- 🔧 **환경변수 설정**: ConfigMap과 Secret을 통한 유연한 설정 관리
|
|
|
|
### 기술 스택
|
|
- **Backend**: Python 3.11, FastAPI, aiohttp
|
|
- **Web Scraping**: Selenium, BeautifulSoup4, Chrome WebDriver
|
|
- **AI/ML**: Claude AI API, Vector DB (Chroma)
|
|
- **Database**: PostgreSQL (향후), Vector DB
|
|
- **Container**: Docker, Multi-stage build
|
|
- **Orchestration**: Kubernetes (AKS)
|
|
- **Registry**: Azure Container Registry (ACR)
|
|
- **Documentation**: Swagger UI, ReDoc
|
|
|
|
## 🏗️ 프로젝트 구조
|
|
|
|
```
|
|
review-api/review/
|
|
├── app/ # 애플리케이션 소스
|
|
│ ├── main.py # 메인 애플리케이션
|
|
│ └── requirements.txt # Python 의존성
|
|
├── deployment/ # 배포 관련 파일
|
|
│ ├── container/ # 컨테이너 이미지 빌드
|
|
│ │ ├── Dockerfile # 서비스 이미지 빌드
|
|
│ │ └── Dockerfile-base # 베이스 이미지 빌드
|
|
│ └── manifests/ # Kubernetes 매니페스트
|
|
│ ├── configmap.yaml # 환경 설정
|
|
│ ├── secret.yaml # 민감 정보 (API 키)
|
|
│ ├── deployment.yaml # 애플리케이션 배포
|
|
│ ├── service.yaml # 서비스 노출
|
|
│ └── ingress.yaml # 외부 접근
|
|
├── build-base.sh # 베이스 이미지 빌드 스크립트
|
|
├── build.sh # 서비스 이미지 빌드 스크립트
|
|
├── create-imagepullsecret.sh # ACR 인증 설정 스크립트
|
|
├── setup.sh # 로컬 환경 설정 스크립트
|
|
└── README.md # 프로젝트 문서
|
|
```
|
|
|
|
## 🚀 빠른 시작
|
|
|
|
### 1. 로컬 개발 환경 설정
|
|
|
|
```bash
|
|
# 저장소 클론 (review-api/review 디렉토리로 이동)
|
|
cd review-api/review
|
|
|
|
# 환경 설정 스크립트 실행
|
|
chmod +x setup.sh
|
|
./setup.sh
|
|
|
|
# 가상환경 활성화
|
|
source venv/bin/activate
|
|
|
|
# 애플리케이션 실행
|
|
python app/main.py
|
|
```
|
|
|
|
### 2. 로컬 웹 브라우저 접속
|
|
|
|
```bash
|
|
# 애플리케이션이 정상 실행된 후 아래 URL로 접속
|
|
```
|
|
|
|
- **메인 페이지**: http://localhost:19000
|
|
- **Swagger UI**: http://localhost:19000/docs
|
|
- **ReDoc**: http://localhost:19000/redoc
|
|
- **헬스체크**: http://localhost:19000/health
|
|
- **진단 정보**: http://localhost:19000/diagnostic
|
|
- **법적 경고**: http://localhost:19000/legal-warning
|
|
|
|
### 3. API 테스트 (교육용)
|
|
|
|
```bash
|
|
# 기본 리뷰 분석 (교육용 - 실제 사용 금지)
|
|
curl -X POST "http://localhost:19000/analyze" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"store_id": "501745730",
|
|
"days_limit": 7,
|
|
"max_time": 300
|
|
}'
|
|
|
|
# 환경 설정 확인
|
|
curl "http://localhost:19000/config"
|
|
|
|
# 법적 경고사항 확인
|
|
curl "http://localhost:19000/legal-warning"
|
|
```
|
|
|
|
## 🐳 Docker 컨테이너 실행
|
|
|
|
### 베이스 이미지 빌드
|
|
|
|
```bash
|
|
# ACR에 베이스 이미지 빌드 및 푸시
|
|
./build-base.sh latest acrdigitalgarage03 rg-digitalgarage-03
|
|
```
|
|
|
|
### 서비스 이미지 빌드
|
|
|
|
```bash
|
|
# ACR에 서비스 이미지 빌드 및 푸시
|
|
./build.sh latest acrdigitalgarage03 rg-digitalgarage-03
|
|
```
|
|
|
|
### 로컬 Docker 실행
|
|
|
|
```bash
|
|
# 컨테이너 실행
|
|
docker run -p 19000:19000 \
|
|
-e APP_TITLE="카카오맵 리뷰 분석 API" \
|
|
-e PORT=19000 \
|
|
kakao-review-api:latest
|
|
|
|
# 백그라운드 실행
|
|
docker run -d -p 19000:19000 \
|
|
--name kakao-review-api \
|
|
-e PORT=19000 \
|
|
kakao-review-api:latest
|
|
```
|
|
|
|
## ☸️ Kubernetes 배포
|
|
|
|
### 1. ACR Image Pull Secret 생성
|
|
|
|
```bash
|
|
# Image Pull Secret 생성
|
|
./create-imagepullsecret.sh acrdigitalgarage03 rg-digitalgarage-03
|
|
```
|
|
|
|
### 2. Kubernetes 리소스 배포
|
|
|
|
```bash
|
|
# ConfigMap 및 Secret 적용
|
|
kubectl apply -f deployment/manifests/configmap.yaml
|
|
kubectl apply -f deployment/manifests/secret.yaml
|
|
|
|
# 애플리케이션 배포
|
|
kubectl apply -f deployment/manifests/deployment.yaml
|
|
kubectl apply -f deployment/manifests/service.yaml
|
|
kubectl apply -f deployment/manifests/ingress.yaml
|
|
```
|
|
|
|
### 3. 배포 상태 확인
|
|
|
|
```bash
|
|
# Pod 상태 확인
|
|
kubectl get pods -l app=kakao-review-api
|
|
|
|
# 서비스 상태 확인
|
|
kubectl get svc kakao-review-api-service
|
|
|
|
# Ingress 상태 확인
|
|
kubectl get ingress kakao-review-api-ingress
|
|
|
|
# 로그 확인
|
|
kubectl logs -l app=kakao-review-api -f
|
|
```
|
|
|
|
### 4. 🌐 외부 브라우저에서 접속하기
|
|
|
|
#### Ingress 주소 확인 방법
|
|
|
|
```bash
|
|
# 1. Ingress 설정된 호스트 확인
|
|
kubectl get ingress kakao-review-api-ingress -o jsonpath='{.spec.rules[0].host}'
|
|
|
|
# 2. Ingress External IP 확인 (LoadBalancer 타입인 경우)
|
|
kubectl get ingress kakao-review-api-ingress
|
|
|
|
# 3. Ingress Controller의 External IP 확인
|
|
kubectl get svc -n ingress-nginx ingress-nginx-controller
|
|
|
|
# 4. 현재 설정된 ingress 주소 확인
|
|
INGRESS_HOST=$(kubectl get ingress kakao-review-api-ingress -o jsonpath='{.spec.rules[0].host}')
|
|
echo "🌐 Review API URL: http://${INGRESS_HOST}"
|
|
```
|
|
|
|
#### 브라우저 접속 주소
|
|
|
|
현재 설정된 주소로 접속하세요:
|
|
|
|
```bash
|
|
# 현재 설정된 기본 주소 (환경에 따라 다를 수 있음)
|
|
INGRESS_URL="http://kakao-review-api.20.249.191.180.nip.io"
|
|
echo "브라우저에서 접속: ${INGRESS_URL}"
|
|
```
|
|
|
|
**주요 접속 페이지:**
|
|
- **🏠 메인 페이지**: http://kakao-review-api.20.249.191.180.nip.io
|
|
- **📖 Swagger UI**: http://kakao-review-api.20.249.191.180.nip.io/docs
|
|
- **📄 ReDoc**: http://kakao-review-api.20.249.191.180.nip.io/redoc
|
|
- **❤️ 헬스체크**: http://kakao-review-api.20.249.191.180.nip.io/health
|
|
- **🔧 진단 정보**: http://kakao-review-api.20.249.191.180.nip.io/diagnostic
|
|
- **⚠️ 법적 경고**: http://kakao-review-api.20.249.191.180.nip.io/legal-warning
|
|
|
|
#### 접속 테스트
|
|
|
|
```bash
|
|
# API 접속 테스트
|
|
curl "http://kakao-review-api.20.249.191.180.nip.io/health"
|
|
|
|
# 설정 정보 확인
|
|
curl "http://kakao-review-api.20.249.191.180.nip.io/config"
|
|
|
|
# Swagger UI 접속 확인
|
|
curl -I "http://kakao-review-api.20.249.191.180.nip.io/docs"
|
|
|
|
# 법적 경고 확인
|
|
curl "http://kakao-review-api.20.249.191.180.nip.io/legal-warning"
|
|
```
|
|
|
|
## ⚙️ 환경 설정
|
|
|
|
### 환경 변수
|
|
|
|
| 변수명 | 기본값 | 설명 |
|
|
|--------|--------|------|
|
|
| `APP_TITLE` | `카카오맵 리뷰 분석 API` | 애플리케이션 제목 |
|
|
| `APP_VERSION` | `1.0.1` | 애플리케이션 버전 |
|
|
| `HOST` | `0.0.0.0` | 서버 호스트 |
|
|
| `PORT` | `19000` | 서버 포트 |
|
|
| `DEFAULT_MAX_TIME` | `300` | 기본 최대 스크롤 시간(초) |
|
|
| `DEFAULT_DAYS_LIMIT` | `60` | 기본 날짜 제한(일) |
|
|
| `MAX_DAYS_LIMIT` | `365` | 최대 날짜 제한(일) |
|
|
| `CHROME_OPTIONS` | `--headless...` | Chrome 브라우저 옵션 |
|
|
| `LEGAL_WARNING_ENABLED` | `true` | 법적 경고 표시 여부 |
|
|
| `CONTACT_EMAIL` | `admin@example.com` | 연락처 이메일 |
|
|
|
|
### Chrome 및 Selenium 설정
|
|
|
|
현재 서비스는 Chrome WebDriver를 사용합니다:
|
|
|
|
```bash
|
|
# Chrome 설치 확인
|
|
google-chrome --version
|
|
|
|
# ChromeDriver 설치 확인
|
|
chromedriver --version
|
|
|
|
# Selenium 테스트
|
|
python -c "from selenium import webdriver; print('Selenium 설치됨')"
|
|
```
|
|
|
|
## 📊 API 엔드포인트
|
|
|
|
### 주요 엔드포인트
|
|
|
|
| Method | Endpoint | 설명 |
|
|
|--------|----------|------|
|
|
| `GET` | `/` | 메인 페이지 |
|
|
| `GET` | `/docs` | Swagger UI 문서 |
|
|
| `GET` | `/health` | 헬스체크 |
|
|
| `GET` | `/diagnostic` | 시스템 진단 정보 |
|
|
| `POST` | `/analyze` | 리뷰 분석 수행 (교육용) |
|
|
| `GET` | `/config` | 환경 설정 확인 |
|
|
| `GET` | `/legal-warning` | 법적 경고사항 |
|
|
|
|
### 리뷰 분석 API 예시 (교육용)
|
|
|
|
```json
|
|
POST /analyze
|
|
{
|
|
"store_id": "501745730",
|
|
"days_limit": 7,
|
|
"max_time": 300
|
|
}
|
|
```
|
|
|
|
**응답:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "분석이 성공적으로 완료되었습니다.",
|
|
"store_info": {
|
|
"id": "501745730",
|
|
"name": "맛있는 식당",
|
|
"category": "한식",
|
|
"rating": "4.2",
|
|
"review_count": "1,234"
|
|
},
|
|
"reviews": [...],
|
|
"analysis_date": "2024-06-12T10:30:00",
|
|
"total_reviews": 25,
|
|
"execution_time": 45.2
|
|
}
|
|
```
|
|
|
|
## 🔧 개발 및 확장
|
|
|
|
### 로컬 개발
|
|
|
|
```bash
|
|
# 개발 모드로 실행 (자동 재시작)
|
|
uvicorn app.main:app --host 0.0.0.0 --port 19000 --reload
|
|
|
|
# 의존성 추가
|
|
pip install 새패키지명
|
|
pip freeze > app/requirements.txt
|
|
|
|
# 코드 포맷팅
|
|
black app/main.py
|
|
flake8 app/main.py
|
|
```
|
|
|
|
### Ingress 호스트 변경
|
|
|
|
현재 환경에 맞게 Ingress 호스트를 변경하려면:
|
|
|
|
```bash
|
|
# 1. 현재 External IP 확인
|
|
kubectl get svc -n ingress-nginx ingress-nginx-controller
|
|
|
|
# 2. deployment/manifests/ingress.yaml 파일에서 host 수정
|
|
# 예: kakao-review-api.{YOUR_EXTERNAL_IP}.nip.io
|
|
|
|
# 3. 변경사항 적용
|
|
kubectl apply -f deployment/manifests/ingress.yaml
|
|
|
|
# 4. 새로운 주소 확인
|
|
kubectl get ingress kakao-review-api-ingress
|
|
```
|
|
|
|
## 🐛 문제 해결
|
|
|
|
### 일반적인 문제
|
|
|
|
**1. Chrome WebDriver 관련 문제**
|
|
```bash
|
|
# Chrome 설치 상태 확인
|
|
docker run --rm kakao-review-api:latest google-chrome --version
|
|
|
|
# ChromeDriver 버전 확인
|
|
docker run --rm kakao-review-api:latest chromedriver --version
|
|
|
|
# 헤드리스 모드 테스트
|
|
curl -X POST "http://localhost:19000/analyze" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"store_id": "test", "days_limit": 1, "max_time": 30}'
|
|
```
|
|
|
|
**2. Kubernetes 배포 실패**
|
|
```bash
|
|
# Pod 로그 확인 (Chrome 에러 확인)
|
|
kubectl logs -l app=kakao-review-api
|
|
|
|
# ConfigMap 확인
|
|
kubectl get configmap kakao-review-api-config -o yaml
|
|
|
|
# 리소스 사용량 확인 (Chrome이 메모리를 많이 사용함)
|
|
kubectl top pods -l app=kakao-review-api
|
|
```
|
|
|
|
**3. Ingress 접속 실패**
|
|
```bash
|
|
# Ingress Controller 상태 확인
|
|
kubectl get pods -n ingress-nginx
|
|
|
|
# Ingress 규칙 확인
|
|
kubectl describe ingress kakao-review-api-ingress
|
|
|
|
# Service 연결 확인
|
|
kubectl get endpoints kakao-review-api-service
|
|
|
|
# 타임아웃 설정 확인 (Chrome 분석은 시간이 오래 걸림)
|
|
kubectl get ingress kakao-review-api-ingress -o yaml | grep timeout
|
|
```
|
|
|
|
**4. 포트 관련 문제**
|
|
- 로컬 개발: 19000번 포트 사용
|
|
- Docker 컨테이너: 19000번 포트로 실행
|
|
- Kubernetes: 19000번 포트로 실행 (Service에서 80번으로 노출, Ingress를 통해 외부 접근)
|
|
|
|
**5. 법적 문제 회피**
|
|
```bash
|
|
# 법적 경고 항상 확인
|
|
curl "http://kakao-review-api.20.249.191.180.nip.io/legal-warning"
|
|
|
|
# 교육용임을 명시하는 환경변수 설정
|
|
export LEGAL_WARNING_ENABLED=true
|
|
export EDUCATIONAL_USE_ONLY=true
|
|
```
|
|
|
|
## 🎯 성능 최적화
|
|
|
|
### Chrome 최적화 설정
|
|
|
|
```yaml
|
|
# deployment.yaml에서 Chrome 최적화를 위한 리소스 설정
|
|
resources:
|
|
requests:
|
|
memory: "1Gi" # Chrome은 메모리를 많이 사용
|
|
cpu: "500m"
|
|
limits:
|
|
memory: "2Gi" # Chrome 분석을 위한 충분한 메모리
|
|
cpu: "1000m"
|
|
```
|
|
|
|
### 타임아웃 설정
|
|
|
|
```yaml
|
|
# ingress.yaml에서 긴 분석 시간을 고려한 타임아웃
|
|
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # 30분
|
|
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # 30분
|
|
```
|
|
|
|
## 📈 향후 확장 계획
|
|
|
|
- [ ] **Claude AI 연동**: 리뷰 분석 및 개선 방안 자동 생성
|
|
- [ ] **Vector DB 구축**: 유사 케이스 검색 및 템플릿 관리
|
|
- [ ] **PostgreSQL 연동**: 분석 결과 영구 저장
|
|
- [ ] **다중 플랫폼 지원**: 네이버, 구글 등 추가 플랫폼 (합법적 방법으로)
|
|
- [ ] **실시간 분석**: WebSocket 기반 실시간 피드백
|
|
- [ ] **사용자 인증**: JWT 기반 인증 시스템
|
|
- [ ] **대시보드**: 분석 결과 시각화
|
|
- [ ] **알림 시스템**: 새로운 리뷰 알림 기능
|
|
- [ ] **감정 분석 고도화**: 더 정확한 감정 분류
|
|
- [ ] **비즈니스 통찰**: AI 기반 개선 방안 제시
|
|
|
|
## ⚖️ 법적 준수 사항
|
|
|
|
### 필수 확인 사항
|
|
|
|
1. **교육용 목적으로만 사용**
|
|
2. **실제 서비스 환경에서 사용 금지**
|
|
3. **카카오 이용약관 준수**
|
|
4. **개인정보보호법 준수**
|
|
5. **저작권 침해 금지**
|
|
|
|
### 권장 대안
|
|
|
|
1. **카카오 공식 API 사용**
|
|
2. **자체 플랫폼 개발**
|
|
3. **사용자 동의 기반 수집**
|
|
4. **정식 파트너십 체결**
|
|
|
|
---
|
|
|
|
## 📞 지원 및 문의
|
|
|
|
- **이슈 리포트**: GitHub Issues
|
|
- **기술 문의**: 개발팀 Slack
|
|
- **법적 문의**: 법무팀
|
|
- **API 문서**: Swagger UI에서 상세 확인
|
|
|
|
---
|
|
|
|
**⚠️ 재고지: 이 서비스는 교육용으로만 제작되었으며, 실제 운영 환경에서의 사용을 엄격히 금지합니다.**
|