feat: AI 서비스 AKS 배포 준비 및 API 경로 수정

## API 경로 변경 - /api/v1/ai → /api/ai 로 경로 단순화 - 최종 엔드포인트: /api/ai/suggestions/meetings/{meetingId}/stream ## Docker 컨테이너화 - Dockerfile 작성 (Python 3.11 slim 기반) - .dockerignore 추가 - 헬스 체크 포함 ## Kubernetes 배포 - Deployment 및 Service 매니페스트 작성 - Replica: 1, Port: 8087 - Liveness/Readiness Probe 설정 - 리소스 제한: CPU 250m-1000m, Memory 512Mi-1024Mi ## Secret 및 ConfigMap - ai-secret: Claude API Key - azure-secret: Event Hub Connection String (AI Listen Policy) - redis-config/redis-secret: Redis 연결 정보 ## Ingress 설정 - /api/ai/suggestions 경로 추가 (ai-service:8087) - 기존 /api/ai 경로 유지 (ai:8080) ## 배포 문서 - DEPLOYMENT.md: 상세한 AKS 배포 가이드 - Docker 이미지 빌드 및 푸시 - Secret/ConfigMap 생성 - 배포 및 검증 - 트러블슈팅 ## ACR 이미지 - acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-06 07:56:24 +00:00 · 2025-10-28 17:08:28 +09:00 · 2025-10-28 17:08:28 +09:00 · c9d24ce1af
commit c9d24ce1af
parent 938cfdb98e
8 changed files with 556 additions and 11 deletions
--- a/.github/kustomize/base/common/ingress.yaml
+++ b/.github/kustomize/base/common/ingress.yaml
@ -32,6 +32,13 @@ spec:
                name: stt
                port:
                  number: 8080
+          - path: /api/ai/suggestions
+            pathType: Prefix
+            backend:
+              service:
+                name: ai-service
+                port:
+                  number: 8087
          - path: /api/ai
            pathType: Prefix
            backend:
--- a/ai-python/.dockerignore
+++ b/ai-python/.dockerignore
@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+logs/
+*.log
+
+# Environment
+.env
+.env.local
+
+# Git
+.git/
+.gitignore
+
+# Documentation
+README.md
+API-DOCUMENTATION.md
+
+# Test
+tests/
+test_*.py
--- a/ai-python/API-DOCUMENTATION.md
+++ b/ai-python/API-DOCUMENTATION.md
@ -11,7 +11,7 @@

 ### 1. 실시간 AI 제안사항 스트리밍 (SSE)

-**엔드포인트**: `GET /api/v1/ai/suggestions/meetings/{meeting_id}/stream`
+**엔드포인트**: `GET /api/ai/suggestions/meetings/{meeting_id}/stream`

 **설명**: 회의 중 실시간으로 AI 제안사항을 Server-Sent Events로 스트리밍합니다.

@ -49,7 +49,7 @@ interface RealtimeSuggestionsResponse {
 // EventSource 연결
 const meetingId = 'meeting-123';
 const eventSource = new EventSource(
-  `http://localhost:8087/api/v1/ai/suggestions/meetings/${meetingId}/stream`
+  `http://localhost:8087/api/ai/suggestions/meetings/${meetingId}/stream`
 );

 // AI 제안사항 수신
@ -95,7 +95,7 @@ function MeetingRoom({ meetingId }: { meetingId: string }) {

  useEffect(() => {
    const eventSource = new EventSource(
-      `http://localhost:8087/api/v1/ai/suggestions/meetings/${meetingId}/stream`
+      `http://localhost:8087/api/ai/suggestions/meetings/${meetingId}/stream`
    );

    eventSource.addEventListener('ai-suggestion', (event) => {
@ -156,8 +156,8 @@ function MeetingRoom({ meetingId }: { meetingId: string }) {
  "version": "1.0.0",
  "status": "running",
  "endpoints": {
-    "test": "/api/v1/ai/suggestions/test",
-    "stream": "/api/v1/ai/suggestions/meetings/{meeting_id}/stream"
+    "test": "/api/ai/suggestions/test",
+    "stream": "/api/ai/suggestions/meetings/{meeting_id}/stream"
  }
 }
 ```
@ -210,13 +210,13 @@ function MeetingRoom({ meetingId }: { meetingId: string }) {
 curl http://localhost:8087/health

 # SSE 스트리밍 테스트
-curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting/stream
+curl -N http://localhost:8087/api/ai/suggestions/meetings/test-meeting/stream
 ```

 ### 브라우저 테스트:
 1. 서비스 실행: `python3 main.py`
 2. Swagger UI 접속: http://localhost:8087/docs
-3. `/api/v1/ai/suggestions/meetings/{meeting_id}/stream` 엔드포인트 테스트
+3. `/api/ai/suggestions/meetings/{meeting_id}/stream` 엔드포인트 테스트

 ## 환경 변수

@ -231,7 +231,7 @@ NEXT_PUBLIC_AI_SERVICE_URL=http://localhost:8087
 const AI_SERVICE_URL = process.env.NEXT_PUBLIC_AI_SERVICE_URL || 'http://localhost:8087';

 const eventSource = new EventSource(
-  `${AI_SERVICE_URL}/api/v1/ai/suggestions/meetings/${meetingId}/stream`
+  `${AI_SERVICE_URL}/api/ai/suggestions/meetings/${meetingId}/stream`
 );
 ```

--- a/ai-python/DEPLOYMENT.md
+++ b/ai-python/DEPLOYMENT.md
@ -0,0 +1,318 @@
+# AI Service (Python) - AKS 배포 가이드
+
+## 📋 사전 준비
+
+### 1. Azure Container Registry (ACR) 접근 권한
+```bash
+# ACR 로그인
+az acr login --name acrdigitalgarage02
+```
+
+### 2. Kubernetes 클러스터 접근
+```bash
+# AKS 자격 증명 가져오기
+az aks get-credentials --resource-group <리소스그룹> --name <클러스터명>
+
+# 네임스페이스 확인
+kubectl get namespace hgzero
+```
+
+## 🐳 1단계: Docker 이미지 빌드 및 푸시
+
+### 이미지 빌드
+```bash
+cd ai-python
+
+# 이미지 빌드
+docker build -t acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest .
+
+# 특정 버전 태그도 함께 생성 (권장)
+docker tag acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest \
+  acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.0
+```
+
+### ACR에 푸시
+```bash
+# latest 태그 푸시
+docker push acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest
+
+# 버전 태그 푸시
+docker push acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.0
+```
+
+### 로컬 테스트 (선택)
+```bash
+# 이미지 실행 테스트
+docker run -p 8087:8087 \
+  -e CLAUDE_API_KEY="your-api-key" \
+  -e REDIS_HOST="20.249.177.114" \
+  -e REDIS_PASSWORD="Hi5Jessica!" \
+  acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest
+
+# 헬스 체크
+curl http://localhost:8087/health
+```
+
+## 🔐 2단계: Kubernetes Secret 생성
+
+### Claude API Key Secret 생성
+```bash
+# Claude API Key를 base64로 인코딩
+echo -n "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" | base64
+
+# Secret 생성
+kubectl create secret generic ai-secret \
+  --from-literal=claude-api-key="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" \
+  -n hgzero
+```
+
+### Event Hub Secret 생성 (기존에 없는 경우)
+```bash
+# Event Hub Connection String (AI Listen Policy)
+kubectl create secret generic azure-secret \
+  --from-literal=eventhub-ai-connection-string="Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=ai-listen-policy;SharedAccessKey=wqcbVIXlOMyn/C562lx6DD75AyjHQ87xo+AEhJ7js9Q=" \
+  -n hgzero --dry-run=client -o yaml | kubectl apply -f -
+```
+
+### Redis Secret 확인/생성
+```bash
+# 기존 Redis Secret 확인
+kubectl get secret redis-secret -n hgzero
+
+# 없으면 생성
+kubectl create secret generic redis-secret \
+  --from-literal=password="Hi5Jessica!" \
+  -n hgzero
+```
+
+### ConfigMap 확인
+```bash
+# Redis ConfigMap 확인
+kubectl get configmap redis-config -n hgzero
+
+# 없으면 생성
+kubectl create configmap redis-config \
+  --from-literal=host="20.249.177.114" \
+  --from-literal=port="6379" \
+  -n hgzero
+```
+
+## 🚀 3단계: AI 서비스 배포
+
+### 배포 실행
+```bash
+# 배포 매니페스트 적용
+kubectl apply -f deploy/k8s/backend/ai-service.yaml
+
+# 배포 상태 확인
+kubectl get deployment ai-service -n hgzero
+kubectl get pods -n hgzero -l app=ai-service
+```
+
+### 로그 확인
+```bash
+# Pod 이름 가져오기
+POD_NAME=$(kubectl get pods -n hgzero -l app=ai-service -o jsonpath='{.items[0].metadata.name}')
+
+# 실시간 로그 확인
+kubectl logs -f $POD_NAME -n hgzero
+
+# Event Hub 연결 로그 확인
+kubectl logs $POD_NAME -n hgzero | grep "Event Hub"
+```
+
+## 🌐 4단계: Ingress 업데이트
+
+### Ingress 적용
+```bash
+# Ingress 설정 적용
+kubectl apply -f .github/kustomize/base/common/ingress.yaml
+
+# Ingress 확인
+kubectl get ingress -n hgzero
+kubectl describe ingress hgzero -n hgzero
+```
+
+### 접속 테스트
+```bash
+# 서비스 URL
+AI_SERVICE_URL="http://hgzero-api.20.214.196.128.nip.io"
+
+# 헬스 체크
+curl $AI_SERVICE_URL/api/ai/suggestions/test
+
+# Swagger UI
+echo "Swagger UI: $AI_SERVICE_URL/swagger-ui.html"
+```
+
+## ✅ 5단계: 배포 검증
+
+### Pod 상태 확인
+```bash
+# Pod 상태
+kubectl get pods -n hgzero -l app=ai-service
+
+# Pod 상세 정보
+kubectl describe pod -n hgzero -l app=ai-service
+
+# Pod 리소스 사용량
+kubectl top pod -n hgzero -l app=ai-service
+```
+
+### 서비스 확인
+```bash
+# Service 확인
+kubectl get svc ai-service -n hgzero
+
+# Service 상세 정보
+kubectl describe svc ai-service -n hgzero
+```
+
+### 엔드포인트 테스트
+```bash
+# 내부 테스트 (Pod에서)
+kubectl exec -it $POD_NAME -n hgzero -- curl http://localhost:8087/health
+
+# 외부 테스트 (Ingress 통해)
+curl http://hgzero-api.20.214.196.128.nip.io/api/ai/suggestions/test
+
+# SSE 스트리밍 테스트
+curl -N http://hgzero-api.20.214.196.128.nip.io/api/ai/suggestions/meetings/test-meeting/stream
+```
+
+## 🔄 업데이트 배포
+
+### 새 버전 배포
+```bash
+# 1. 새 이미지 빌드 및 푸시
+docker build -t acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.1 .
+docker push acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.1
+
+# 2. Deployment 이미지 업데이트
+kubectl set image deployment/ai-service \
+  ai-service=acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.1 \
+  -n hgzero
+
+# 3. 롤아웃 상태 확인
+kubectl rollout status deployment/ai-service -n hgzero
+
+# 4. 롤아웃 히스토리
+kubectl rollout history deployment/ai-service -n hgzero
+```
+
+### 롤백 (문제 발생 시)
+```bash
+# 이전 버전으로 롤백
+kubectl rollout undo deployment/ai-service -n hgzero
+
+# 특정 리비전으로 롤백
+kubectl rollout undo deployment/ai-service -n hgzero --to-revision=2
+```
+
+## 🐛 트러블슈팅
+
+### Pod가 Running 상태가 아닌 경우
+```bash
+# Pod 상태 확인
+kubectl get pods -n hgzero -l app=ai-service
+
+# Pod 이벤트 확인
+kubectl describe pod -n hgzero -l app=ai-service
+
+# 로그 확인
+kubectl logs -n hgzero -l app=ai-service
+```
+
+### ImagePullBackOff 에러
+```bash
+# ACR 접근 권한 확인
+kubectl get secret -n hgzero
+
+# ACR Pull Secret 생성 (필요시)
+kubectl create secret docker-registry acr-secret \
+  --docker-server=acrdigitalgarage02.azurecr.io \
+  --docker-username=<ACR_USERNAME> \
+  --docker-password=<ACR_PASSWORD> \
+  -n hgzero
+```
+
+### CrashLoopBackOff 에러
+```bash
+# 로그 확인
+kubectl logs -n hgzero -l app=ai-service --previous
+
+# 환경 변수 확인
+kubectl exec -it $POD_NAME -n hgzero -- env | grep -E "CLAUDE|REDIS|EVENTHUB"
+```
+
+### Redis 연결 실패
+```bash
+# Redis 접속 테스트 (Pod에서)
+kubectl exec -it $POD_NAME -n hgzero -- \
+  python -c "import redis; r=redis.Redis(host='20.249.177.114', port=6379, password='Hi5Jessica!', db=4); print(r.ping())"
+```
+
+### Event Hub 연결 실패
+```bash
+# Event Hub 연결 문자열 확인
+kubectl get secret azure-secret -n hgzero -o jsonpath='{.data.eventhub-ai-connection-string}' | base64 -d
+
+# 로그에서 Event Hub 오류 확인
+kubectl logs $POD_NAME -n hgzero | grep -i "eventhub\|error"
+```
+
+## 📊 모니터링
+
+### 실시간 로그 모니터링
+```bash
+# 실시간 로그
+kubectl logs -f -n hgzero -l app=ai-service
+
+# 특정 키워드 필터링
+kubectl logs -f -n hgzero -l app=ai-service | grep -E "SSE|Claude|AI"
+```
+
+### 리소스 사용량
+```bash
+# CPU/메모리 사용량
+kubectl top pod -n hgzero -l app=ai-service
+
+# 상세 리소스 정보
+kubectl describe pod -n hgzero -l app=ai-service | grep -A 5 "Resources"
+```
+
+## 🗑️ 삭제
+
+### AI 서비스 삭제
+```bash
+# Deployment와 Service 삭제
+kubectl delete -f deploy/k8s/backend/ai-service.yaml
+
+# Secret 삭제
+kubectl delete secret ai-secret -n hgzero
+
+# ConfigMap 유지 (다른 서비스에서 사용 중)
+# kubectl delete configmap redis-config -n hgzero
+```
+
+## 📝 주의사항
+
+1. **Secret 관리**
+   - Claude API Key는 민감 정보이므로 Git에 커밋하지 마세요
+   - 프로덕션 환경에서는 Azure Key Vault 사용 권장
+
+2. **리소스 제한**
+   - 초기 설정: CPU 250m-1000m, Memory 512Mi-1024Mi
+   - 트래픽에 따라 조정 필요
+
+3. **Event Hub**
+   - AI Listen Policy 사용 (Listen 권한만)
+   - EntityPath는 연결 문자열에서 제거
+
+4. **Redis**
+   - DB 4번 사용 (다른 서비스와 분리)
+   - TTL 5분 설정 (슬라이딩 윈도우)
+
+5. **Ingress 경로**
+   - `/api/ai/suggestions`가 `/api/ai`보다 먼저 정의되어야 함
+   - 더 구체적인 경로를 위에 배치
--- a/ai-python/Dockerfile
+++ b/ai-python/Dockerfile
@ -0,0 +1,27 @@
+# Python 3.11 slim 이미지 사용
+FROM python:3.11-slim
+
+# 작업 디렉토리 설정
+WORKDIR /app
+
+# 시스템 패키지 업데이트 및 필요한 도구 설치
+RUN apt-get update && apt-get install -y \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Python 의존성 파일 복사 및 설치
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 애플리케이션 코드 복사
+COPY . .
+
+# 포트 노출
+EXPOSE 8087
+
+# 헬스 체크
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8087/health')" || exit 1
+
+# 애플리케이션 실행
+CMD ["python", "main.py"]
--- a/ai-python/main.py
+++ b/ai-python/main.py
@ -84,7 +84,7 @@ app.add_middleware(
 # 라우터 등록
 app.include_router(
    suggestions.router,
-    prefix="/api/v1/ai/suggestions",
+    prefix="/api/ai/suggestions",
    tags=["AI Suggestions"]
 )

@ -97,8 +97,9 @@ async def root():
        "version": "1.0.0",
        "status": "running",
        "endpoints": {
-            "test": "/api/v1/ai/suggestions/test",
-            "stream": "/api/v1/ai/suggestions/meetings/{meeting_id}/stream"
+            "test": "/api/ai/suggestions/test",
+            "stream": "/api/ai/suggestions/meetings/{meeting_id}/stream",
+            "swagger": "/swagger-ui.html"
        }
    }

--- a/deploy/k8s/backend/ai-secret-template.yaml
+++ b/deploy/k8s/backend/ai-secret-template.yaml
@ -0,0 +1,27 @@
+---
+# AI Service Secret Template
+# 실제 배포 시 base64로 인코딩된 값으로 교체 필요
+apiVersion: v1
+kind: Secret
+metadata:
+  name: ai-secret
+  namespace: hgzero
+type: Opaque
+data:
+  # Claude API Key (base64 인코딩 필요)
+  # echo -n "sk-ant-api03-..." | base64
+  claude-api-key: <BASE64_ENCODED_CLAUDE_API_KEY>
+
+---
+# Azure EventHub Secret for AI Service
+# AI 서비스용 Event Hub 연결 문자열
+apiVersion: v1
+kind: Secret
+metadata:
+  name: azure-secret
+  namespace: hgzero
+type: Opaque
+data:
+  # Event Hub Connection String (AI Listen Policy)
+  # echo -n "Endpoint=sb://..." | base64
+  eventhub-ai-connection-string: <BASE64_ENCODED_EVENTHUB_CONNECTION_STRING>
--- a/deploy/k8s/backend/ai-service.yaml
+++ b/deploy/k8s/backend/ai-service.yaml
@ -0,0 +1,130 @@
+---
+# AI Service (Python) Deployment
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ai-service
+  namespace: hgzero
+  labels:
+    app: ai-service
+    tier: backend
+    language: python
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: ai-service
+  template:
+    metadata:
+      labels:
+        app: ai-service
+        tier: backend
+        language: python
+    spec:
+      containers:
+      - name: ai-service
+        image: acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest
+        imagePullPolicy: Always
+        ports:
+        - containerPort: 8087
+          name: http
+        env:
+        # 서버 설정
+        - name: PORT
+          value: "8087"
+        - name: HOST
+          value: "0.0.0.0"
+        - name: LOG_LEVEL
+          value: "INFO"
+
+        # Claude API
+        - name: CLAUDE_API_KEY
+          valueFrom:
+            secretKeyRef:
+              name: ai-secret
+              key: claude-api-key
+        - name: CLAUDE_MODEL
+          value: "claude-3-5-sonnet-20241022"
+        - name: CLAUDE_MAX_TOKENS
+          value: "2000"
+        - name: CLAUDE_TEMPERATURE
+          value: "0.3"
+
+        # Redis
+        - name: REDIS_HOST
+          valueFrom:
+            configMapKeyRef:
+              name: redis-config
+              key: host
+        - name: REDIS_PORT
+          valueFrom:
+            configMapKeyRef:
+              name: redis-config
+              key: port
+        - name: REDIS_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: redis-secret
+              key: password
+        - name: REDIS_DB
+          value: "4"
+
+        # Azure Event Hub
+        - name: EVENTHUB_CONNECTION_STRING
+          valueFrom:
+            secretKeyRef:
+              name: azure-secret
+              key: eventhub-ai-connection-string
+        - name: EVENTHUB_NAME
+          value: "hgzero-eventhub-name"
+        - name: EVENTHUB_CONSUMER_GROUP
+          value: "$Default"
+
+        # CORS
+        - name: CORS_ORIGINS
+          value: '["*"]'
+
+        resources:
+          requests:
+            cpu: 250m
+            memory: 512Mi
+          limits:
+            cpu: 1000m
+            memory: 1024Mi
+
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 8087
+          initialDelaySeconds: 30
+          periodSeconds: 10
+          timeoutSeconds: 5
+          failureThreshold: 3
+
+        readinessProbe:
+          httpGet:
+            path: /health
+            port: 8087
+          initialDelaySeconds: 10
+          periodSeconds: 5
+          timeoutSeconds: 3
+          failureThreshold: 3
+
+---
+# AI Service Service
+apiVersion: v1
+kind: Service
+metadata:
+  name: ai-service
+  namespace: hgzero
+  labels:
+    app: ai-service
+spec:
+  type: ClusterIP
+  ports:
+  - port: 8087
+    targetPort: 8087
+    protocol: TCP
+    name: http
+  selector:
+    app: ai-service