shared-dg04-hi/ai-review

Fork 0

hiondal 6a5c411800 release

2025-06-15 13:52:26 +00:00

12 KiB

Raw Blame History

카카오 API 기반 음식점 수집 서비스

카카오 로컬 API를 활용하여 음식점 정보를 수집하고 관리하는 RESTful API 서비스입니다.

📋 프로젝트 개요

주요 기능

🔍 카카오 로컬 API 연동: 키워드 및 지역 기반 음식점 검색
📊 다중 페이지 수집: 최대 45페이지까지 데이터 수집 지원
💾 자동 JSON 저장: 수집된 데이터를 JSON 파일로 자동 저장
🚀 RESTful API 제공: FastAPI 기반의 완전한 API 서비스
📚 Swagger UI 지원: 자동 생성되는 API 문서
☸️ Kubernetes 배포: 완전한 컨테이너 오케스트레이션 지원
🔧 환경변수 설정: ConfigMap과 Secret을 통한 유연한 설정 관리

기술 스택

Backend: Python 3.11, FastAPI, aiohttp
API: Kakao Local API
Container: Docker, Multi-stage build
Orchestration: Kubernetes (AKS)
Registry: Azure Container Registry (ACR)
Documentation: Swagger UI, ReDoc

🏗️ 프로젝트 구조

review-api/restaurant/
├── 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                     # 프로젝트 문서

📋 사전 작업

카카오 API 설정

카카오 developers 포탈에서 애플리케이션 등록이 필요합니다.

포탈 접속: https://developers.kakao.com/console/app
애플리케이션 등록:
- 앱 이름: RestaurantCollector
- 회사명: {회사명}
- 카테고리: 식음료
카카오맵 활성화: 등록한 애플리케이션에서 좌측 '카카오맵' 메뉴 클릭하여 활성화

🚀 빠른 시작

1. 로컬 개발 환경 설정

# 저장소 클론 (review-api/restaurant 디렉토리로 이동)
cd review-api/restaurant

# 환경 설정 스크립트 실행
chmod +x setup.sh
./setup.sh

# 가상환경 활성화
source venv/bin/activate

# 애플리케이션 실행
python app/main.py

2. 로컬 웹 브라우저 접속

# 애플리케이션이 정상 실행된 후 아래 URL로 접속

메인 페이지: http://localhost:18000
Swagger UI: http://localhost:18000/docs
ReDoc: http://localhost:18000/redoc
헬스체크: http://localhost:18000/health

3. API 테스트

# 기본 음식점 수집
curl -X POST "http://localhost:18000/collect" \
     -H "Content-Type: application/json" \
     -d '{
       "query": "치킨",
       "region": "서울",
       "size": 15,
       "pages": 3,
       "save_to_file": true
     }'

# 수집된 파일 목록 조회
curl "http://localhost:18000/list-files"

# 파일 다운로드 (예시)
curl "http://localhost:18000/download/restaurant.json" -o downloaded_restaurants.json

🐳 Docker 컨테이너 실행

베이스 이미지 빌드

# ACR에 베이스 이미지 빌드 및 푸시
./build-base.sh latest acrdigitalgarage03 rg-digitalgarage-03

서비스 이미지 빌드

# ACR에 서비스 이미지 빌드 및 푸시
./build.sh latest acrdigitalgarage03 rg-digitalgarage-03

로컬 Docker 실행

# 컨테이너 실행
docker run -p 18000:8000 \
  -e KAKAO_API_KEY=5cdc24407edbf8544f3954cfaa4650c6 \
  -e PORT=8000 \
  restaurant-api:latest

# 백그라운드 실행
docker run -d -p 18000:8000 \
  --name restaurant-api \
  -e KAKAO_API_KEY=5cdc24407edbf8544f3954cfaa4650c6 \
  -e PORT=8000 \
  restaurant-api:latest

☸️ Kubernetes 배포

1. ACR Image Pull Secret 생성

# Image Pull Secret 생성
./create-imagepullsecret.sh acrdigitalgarage03 rg-digitalgarage-03

2. Kubernetes 리소스 배포

# 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. 배포 상태 확인

# Pod 상태 확인
kubectl get pods -l app=restaurant-api

# 서비스 상태 확인
kubectl get svc restaurant-api-service

# Ingress 상태 확인
kubectl get ingress restaurant-api-ingress

# 로그 확인
kubectl logs -l app=restaurant-api -f

4. 🌐 외부 브라우저에서 접속하기

Ingress 주소 확인 방법

# 1. Ingress 설정된 호스트 확인
kubectl get ingress restaurant-api-ingress -o jsonpath='{.spec.rules[0].host}'

# 2. Ingress External IP 확인 (LoadBalancer 타입인 경우)
kubectl get ingress restaurant-api-ingress

# 3. Ingress Controller의 External IP 확인
kubectl get svc -n ingress-nginx ingress-nginx-controller

# 4. 현재 설정된 ingress 주소 확인
INGRESS_HOST=$(kubectl get ingress restaurant-api-ingress -o jsonpath='{.spec.rules[0].host}')
echo "🌐 Restaurant API URL: http://${INGRESS_HOST}"

브라우저 접속 주소

현재 설정된 주소로 접속하세요:

# 현재 설정된 기본 주소 (환경에 따라 다를 수 있음)
INGRESS_URL="http://restaurant-api.20.249.191.180.nip.io"
echo "브라우저에서 접속: ${INGRESS_URL}"

주요 접속 페이지:

🏠 메인 페이지: http://restaurant-api.20.249.191.180.nip.io
📖 Swagger UI: http://restaurant-api.20.249.191.180.nip.io/docs
📄 ReDoc: http://restaurant-api.20.249.191.180.nip.io/redoc
❤️ 헬스체크: http://restaurant-api.20.249.191.180.nip.io/health

접속 테스트

# API 접속 테스트
curl "http://restaurant-api.20.249.191.180.nip.io/health"

# 설정 정보 확인
curl "http://restaurant-api.20.249.191.180.nip.io/config"

# Swagger UI 접속 확인
curl -I "http://restaurant-api.20.249.191.180.nip.io/docs"

⚙️ 환경 설정

환경 변수

변수명	기본값	설명
`KAKAO_API_KEY`	`5cdc24407edbf8544f3954cfaa4650c6`	카카오 API 키
`APP_TITLE`	`카카오 API 기반 음식점 수집 서비스`	애플리케이션 제목
`HOST`	`0.0.0.0`	서버 호스트
`PORT`	`8000`	서버 포트 (컨테이너 내부)
`DEFAULT_QUERY`	`음식점`	기본 검색 키워드
`DEFAULT_REGION`	`서울`	기본 검색 지역
`DEFAULT_SIZE`	`15`	페이지당 결과 수
`MAX_PAGES`	`45`	최대 페이지 수
`DATA_DIR`	`/app/data`	데이터 저장 디렉토리
`REQUEST_DELAY`	`0.1`	API 요청 간 지연시간(초)

📊 API 엔드포인트

주요 엔드포인트

Method	Endpoint	설명
`GET`	`/`	메인 페이지
`GET`	`/docs`	Swagger UI 문서
`GET`	`/health`	헬스체크
`POST`	`/collect`	음식점 정보 수집
`POST`	`/collect-background`	백그라운드 수집
`GET`	`/list-files`	저장된 파일 목록
`GET`	`/download/{filename}`	파일 다운로드
`GET`	`/config`	환경 설정 확인

수집 API 예시

POST /collect
{
  "query": "피자",
  "region": "강남구",
  "size": 15,
  "pages": 5,
  "save_to_file": true
}

응답:

{
  "success": true,
  "message": "음식점 정보 수집이 완료되었습니다. (총 67개)",
  "metadata": {
    "collection_date": "2024-06-12T10:30:00",
    "query": "피자",
    "region": "강남구",
    "total_count": 67,
    "pages_collected": 5,
    "execution_time": 12.5
  },
  "restaurants": [...],
  "file_saved": true,
  "file_path": "/app/data/restaurants_피자_강남구_20240612_103000.json"
}

🔧 개발 및 확장

로컬 개발

# 개발 모드로 실행 (자동 재시작)
uvicorn app.main:app --host 0.0.0.0 --port 18000 --reload

# 의존성 추가
pip install 새패키지명
pip freeze > app/requirements.txt

# 코드 포맷팅
black app/main.py
flake8 app/main.py

Ingress 호스트 변경

현재 환경에 맞게 Ingress 호스트를 변경하려면:

# 1. 현재 External IP 확인
kubectl get svc -n ingress-nginx ingress-nginx-controller

# 2. deployment/manifests/ingress.yaml 파일에서 host 수정
# 예: restaurant-api.{YOUR_EXTERNAL_IP}.nip.io

# 3. 변경사항 적용
kubectl apply -f deployment/manifests/ingress.yaml

# 4. 새로운 주소 확인
kubectl get ingress restaurant-api-ingress

🐛 문제 해결

일반적인 문제

1. API 키 인증 실패

# API 키 확인
curl -H "Authorization: KakaoAK YOUR_API_KEY" \
     "https://dapi.kakao.com/v2/local/search/keyword.json?query=테스트&size=1"

# 환경변수 확인
echo $KAKAO_API_KEY

2. Kubernetes 배포 실패

# Pod 로그 확인
kubectl logs -l app=restaurant-api

# ConfigMap 확인
kubectl get configmap restaurant-api-config -o yaml

# Secret 확인
kubectl get secret restaurant-api-secret -o yaml

3. Ingress 접속 실패

# Ingress Controller 상태 확인
kubectl get pods -n ingress-nginx

# Ingress 규칙 확인
kubectl describe ingress restaurant-api-ingress

# Service 연결 확인
kubectl get endpoints restaurant-api-service

4. 포트 관련 문제

로컬 개발: 18000번 포트 사용
Docker 컨테이너: 8000번 포트로 실행 (외부 18000번으로 매핑)
Kubernetes: 8000번 포트로 실행 (Service에서 80번으로 노출, Ingress를 통해 외부 접근)

🎯 성능 최적화

권장 설정

# deployment.yaml에서 리소스 최적화
resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "1Gi"
    cpu: "500m"

모니터링

# 리소스 사용량 확인
kubectl top pods -l app=restaurant-api

# 메트릭 수집 (Prometheus 설정 시)
kubectl get --raw /metrics

📈 향후 확장 계획

전국 확대: 지역별 음식점 수집 기능 확장
데이터베이스 연동: PostgreSQL, MongoDB 지원
비동기 작업 큐: Celery, Redis 활용
데이터 분석: 음식점 트렌드 분석 기능
알림 시스템: 새로운 음식점 알림 기능
사용자 인증: JWT 기반 인증 시스템
API 레이트 리미팅: 요청 제한 기능
GraphQL 지원: 유연한 쿼리 인터페이스
실시간 모니터링: Grafana, Prometheus 연동

📞 지원 및 문의

이슈 리포트: GitHub Issues
기술 문의: 개발팀 Slack
API 문서: Swagger UI에서 상세 확인

12 KiB Raw Blame History