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,200 @@
+# 빠른 설정 가이드
+
+## .env 파일 작성 방법
+
+### 1단계: 템플릿 복사
+
+```bash
+cd /Users/parkjiwon/src/rag
+cp env.template .env
+```
+
+### 2단계: 서버 정보 확인
+
+각 서비스가 실행 중인 서버의 IP와 포트를 확인하세요:
+
+| 서비스 | 확인 방법 |
+|--------|-----------|
+| **LLM API** | 내부 LLM 서버 관리자에게 문의 |
+| **TEI Embedding** | `docker ps | grep embedding` |
+| **TEI Reranker** | `docker ps | grep reranker` |
+
+### 3단계: .env 파일 수정
+
+#### 시나리오 A: 모든 서비스가 같은 서버 (일반적)
+
+```bash
+vi .env
+```
+
+```bash
+# LLM 서버 정보 입력
+LLM_HOST=192.168.1.100        # ← 실제 IP로 변경
+LLM_PORT=16000
+LLM_BASE_URL=http://192.168.1.100:16000
+LLM_MODEL_NAME=default
+
+# TEI 서버 정보 입력 (같은 서버)
+TEI_EMBED_HOST=192.168.1.100  # ← 실제 IP로 변경
+TEI_EMBED_PORT=16001
+TEI_EMBED_URL=http://192.168.1.100:16001
+
+TEI_RERANK_HOST=192.168.1.100 # ← 실제 IP로 변경
+TEI_RERANK_PORT=16002
+TEI_RERANK_URL=http://192.168.1.100:16002
+
+# 나머지는 기본값 사용
+VECTOR_STORE=faiss
+API_TIMEOUT=60
+```
+
+#### 시나리오 B: LLM과 TEI가 다른 서버
+
+```bash
+# LLM 서버 (서버 A)
+LLM_HOST=10.20.30.40          # ← LLM 서버 IP
+LLM_PORT=8000                 # ← LLM 포트
+LLM_BASE_URL=http://10.20.30.40:8000
+LLM_MODEL_NAME=default
+
+# TEI 서버 (서버 B)
+TEI_EMBED_HOST=10.20.30.50    # ← TEI 서버 IP
+TEI_EMBED_PORT=80             # ← Embed 포트
+TEI_EMBED_URL=http://10.20.30.50:80
+
+TEI_RERANK_HOST=10.20.30.50   # ← TEI 서버 IP
+TEI_RERANK_PORT=81            # ← Rerank 포트
+TEI_RERANK_URL=http://10.20.30.50:81
+
+VECTOR_STORE=faiss
+API_TIMEOUT=60
+```
+
+### 4단계: 연결 테스트
+
+```bash
+# LLM API 테스트
+curl http://192.168.1.100:16000/health
+
+# TEI Embedding 테스트
+curl http://192.168.1.100:16001/health
+
+# TEI Reranker 테스트
+curl http://192.168.1.100:16002/health
+```
+
+**모두 OK 응답이 나와야 합니다!**
+
+---
+
+## 자주 사용하는 설정 패턴
+
+### 패턴 1: 단일 서버 (가장 간단)
+
+```bash
+# 하나의 IP만 변경
+LLM_HOST=192.168.1.100
+LLM_PORT=16000
+TEI_EMBED_HOST=192.168.1.100
+TEI_EMBED_PORT=16001
+TEI_RERANK_HOST=192.168.1.100
+TEI_RERANK_PORT=16002
+```
+
+### 패턴 2: URL 직접 지정 (고급)
+
+HOST/PORT 대신 URL을 직접 지정할 수도 있습니다:
+
+```bash
+# 이렇게 하면 HOST/PORT는 무시됨
+LLM_BASE_URL=http://my-llm-server.company.com:8000
+TEI_EMBED_URL=http://tei-server-1.company.com/embed
+TEI_RERANK_URL=http://tei-server-2.company.com/rerank
+```
+
+**주의**: URL을 직접 지정하면 HOST/PORT 값은 무시됩니다.
+
+---
+
+## 체크리스트
+
+배포 전에 확인하세요:
+
+- [ ] `.env` 파일 생성 완료
+- [ ] `LLM_HOST` 실제 IP로 변경
+- [ ] `LLM_PORT` 확인 (기본: 16000)
+- [ ] `TEI_EMBED_HOST` 실제 IP로 변경
+- [ ] `TEI_EMBED_PORT` 확인 (기본: 16001)
+- [ ] `TEI_RERANK_HOST` 실제 IP로 변경
+- [ ] `TEI_RERANK_PORT` 확인 (기본: 16002)
+- [ ] 각 서비스 헬스체크 성공 확인
+- [ ] `VECTOR_STORE=faiss` 설정 확인
+
+---
+
+## 다음 단계
+
+설정 완료 후:
+
+```bash
+# Docker 빌드
+docker-compose build
+
+# 배치 작업 실행
+docker-compose up preprocess embed index
+
+# API 서비스 시작
+docker-compose up -d api
+
+# 최종 테스트
+curl http://localhost:28012/health
+```
+
+---
+
+## 문제 해결
+
+### "Connection refused" 오류
+
+```bash
+# 1. IP 주소 확인
+ping 192.168.1.100
+
+# 2. 포트 접근 테스트
+telnet 192.168.1.100 16000
+
+# 3. 방화벽 확인
+# 서버에서:
+sudo ufw status
+sudo ufw allow 16000:16002/tcp
+```
+
+### 변수가 적용 안 됨
+
+```bash
+# .env 파일 문법 확인
+cat .env | grep -E "HOST|PORT|URL"
+
+# 공백 없이 작성했는지 확인
+# 잘못됨: LLM_HOST = 192.168.1.100 (공백 있음)
+# 올바름: LLM_HOST=192.168.1.100 (공백 없음)
+```
+
+### 어떤 값을 설정해야 할지 모르겠어요
+
+**env.example 파일을 참고하세요:**
+
+```bash
+cat env.example
+```
+
+4가지 일반적인 시나리오가 주석으로 설명되어 있습니다.
+
+---
+
+## 추가 정보
+
+- 상세 가이드: `INTERNAL_LLM_GUIDE.md`
+- 배포 가이드: `DEPLOYMENT.md`
+- 전체 README: `README.md`
+