Agent 2.0 exdev 서버 배포 스택

- server-dev start/stop/deploy 및 Gitea push 자동 배포 - local-dev 로컬 개발 환경 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-21 22:57:30 +09:00
commit 4b86b2a660
344 changed files with 45787 additions and 0 deletions
@@ -0,0 +1,283 @@
+# RAG API 구현 완료 문서
+
+## ✅ 수정 완료된 파일
+
+### 1️⃣ **RagConfig.java** - Docker 스펙에 맞게 수정
+```java
+- host: localhost (Docker 컨테이너)
+- port: 28012 (Docker 외부 포트)
+- askEndpoint: /ask
+- healthEndpoint: /health (추가)
+```
+
+### 2️⃣ **RagServerRequest.java** - API 스펙 적용
+```java
+{
+  "query": "사용자 질문"  // Docker API 필드명에 맞춤
+}
+```
+
+### 3️⃣ **RagServerResponse.java** - 실제 응답 구조
+```java
+{
+  "answer": "LLM 답변",
+  "matched_questions": ["질문1", "질문2", "질문3"],
+  "scores": [0.95, 0.89, 0.82],
+  "num_references": 5
+}
+```
+
+### 4️⃣ **RagService.java** - 변환 로직 추가
+- question → query 자동 변환
+- 헬스체크 기능 추가
+- 상세 로깅 추가
+
+### 5️⃣ **RagApiController.java** - 헬스체크 엔드포인트 추가
+- POST /api/v1/rag-only (질문 처리)
+- GET /api/v1/rag-only/health (헬스체크)
+
+### 6️⃣ **application.yml** - Docker 설정
+```yaml
+rag:
+  server:
+    host: localhost
+    port: 28012
+    ask-endpoint: /ask
+    health-endpoint: /health
+```
+
+---
+
+## 🔄 API 처리 흐름
+
+```
+챗봇 웹
+  ↓ POST /api/v1/rag-only
+  ↓ {
+      "question": "회원가입은 어떻게 하나요?",
+      "botId": "bot-001"
+    }
+  ↓
+[Spring Boot API - RagApiController]
+  ↓
+[RagService]
+  - 입력 검증
+  - question → query 변환
+  ↓ POST http://localhost:28012/ask
+  ↓ {
+      "query": "회원가입은 어떻게 하나요?"
+    }
+  ↓
+[Docker 컨테이너 - RAG 서버]
+  - LLM 처리
+  - 벡터 검색
+  - 답변 생성
+  ↓ 응답
+  ↓ {
+      "answer": "회원가입은 다음과 같이...",
+      "matched_questions": ["회원가입 방법", "가입 절차", "회원 등록"],
+      "scores": [0.95, 0.89, 0.82],
+      "num_references": 5
+    }
+  ↓
+[RagService]
+  - 응답 가공
+  ↓
+[RagApiController]
+  ↓ 최종 응답
+  ↓ {
+      "status": true,
+      "statusMsg": "정상응답",
+      "answer": "회원가입은 다음과 같이...",
+      "matchedQuestions": ["회원가입 방법", "가입 절차", "회원 등록"],
+      "scores": [0.95, 0.89, 0.82],
+      "numReferences": 5
+    }
+  ↓
+챗봇 웹
+```
+
+---
+
+## 🧪 테스트 방법
+
+### 1. Docker 컨테이너 직접 테스트
+
+```bash
+# 질문 테스트
+curl -X POST http://localhost:28012/ask \
+  -H "Content-Type: application/json" \
+  -d '{"query":"회원가입은 어떻게 하나요?"}'
+
+# 헬스체크
+curl http://localhost:28012/health
+```
+
+**예상 응답:**
+```json
+{
+  "answer": "회원가입은...",
+  "matched_questions": ["회원가입 방법", "가입 절차"],
+  "scores": [0.95, 0.89],
+  "num_references": 5
+}
+```
+
+### 2. Spring Boot API 테스트
+
+```bash
+# 질문 API
+curl -X POST http://localhost:8086/api/v1/rag-only \
+  -H "Content-Type: application/json" \
+  -d '{
+    "question": "회원가입은 어떻게 하나요?",
+    "botId": "bot-001"
+  }'
+
+# 헬스체크 API
+curl http://localhost:8086/api/v1/rag-only/health
+```
+
+**예상 응답 (성공):**
+```json
+{
+  "status": true,
+  "statusMsg": "정상응답",
+  "answer": "회원가입은 다음과 같이 진행됩니다...",
+  "matchedQuestions": ["회원가입 방법", "가입 절차", "회원 등록"],
+  "scores": [0.95, 0.89, 0.82],
+  "numReferences": 5
+}
+```
+
+**예상 응답 (실패):**
+```json
+{
+  "status": false,
+  "statusMsg": "RAG 서버 통신 실패"
+}
+```
+
+### 3. Postman으로 테스트
+
+**질문 API:**
+- Method: POST
+- URL: `http://localhost:8086/api/v1/rag-only`
+- Headers: `Content-Type: application/json`
+- Body (raw JSON):
+```json
+{
+  "question": "배송은 얼마나 걸리나요?",
+  "botId": "bot-001"
+}
+```
+
+**헬스체크 API:**
+- Method: GET
+- URL: `http://localhost:8086/api/v1/rag-only/health`
+
+---
+
+## 📋 환경별 설정
+
+### 로컬 개발 (application-local.yml)
+```yaml
+rag:
+  server:
+    host: localhost
+    port: 28012
+```
+
+### 개발 서버 (application-dev.yml)
+```yaml
+rag:
+  server:
+    host: 172.16.163.62  # 개발 서버 IP
+    port: 28012
+```
+
+### 운영 서버 (application-prod.yml)
+```yaml
+rag:
+  server:
+    host: ${RAG_SERVER_HOST:localhost}
+    port: ${RAG_SERVER_PORT:28012}
+```
+
+---
+
+## 🔍 로그 확인
+
+### 질문 처리 시
+```
+INFO  - RAG 질문 처리 시작 - 질문: 회원가입은 어떻게 하나요?, 봇ID: bot-001
+INFO  - RAG 서버 요청 시작 - URL: http://localhost:28012/ask, 질문: 회원가입은 어떻게 하나요?
+INFO  - RAG 서버 응답 성공 - Status: 200 OK
+INFO  - RAG 질문 처리 완료 - 참조: 5개, 유사 질문: 3개
+```
+
+### 헬스체크 시
+```
+INFO  - RAG 서버 헬스체크 시작
+INFO  - 헬스체크 URL: http://localhost:28012/health
+INFO  - RAG 서버 상태: ok, 벡터 개수: 1000
+```
+
+### 에러 시
+```
+ERROR - RAG 서버 통신 실패 - Connection refused
+```
+
+---
+
+## ⚠️ 주의사항
+
+1. **Docker 컨테이너 실행 확인**
+   ```bash
+   docker ps | grep 28012
+   ```
+
+2. **포트 접근 가능 확인**
+   ```bash
+   telnet localhost 28012
+   # 또는
+   nc -zv localhost 28012
+   ```
+
+3. **방화벽 설정 확인**
+   - 28012 포트가 열려있는지 확인
+   - 개발 서버에서는 172.16.163.62:28012 접근 가능한지 확인
+
+4. **botId는 선택사항**
+   - 현재 Docker API에는 전달되지 않음
+   - 로깅/추적 목적으로만 사용
+
+---
+
+## 📌 다음 단계 (선택사항)
+
+1. **응답 캐싱**
+   - 동일한 질문에 대한 캐시 처리
+   - Redis 또는 로컬 캐시 활용
+
+2. **재시도 로직**
+   - RAG 서버 통신 실패 시 재시도
+   - Exponential Backoff 적용
+
+3. **모니터링**
+   - 응답 시간 측정
+   - 에러율 추적
+   - Prometheus/Grafana 연동
+
+4. **보안 강화**
+   - API 키 인증
+   - Rate Limiting
+
+---
+
+## 🎯 완료!
+
+모든 파일이 Docker RAG 서버 API 스펙에 맞춰 수정되었습니다.
+
+테스트 후 문제가 있으면 알려주세요! 😊
+