first commit

QUICKSTART.md

@@ -0,0 +1,151 @@
+# VConnect API 서버 빠른 시작 가이드
+
+## 1️⃣ 설치
+
+```bash
+# 프로젝트 디렉토리로 이동
+cd vconnect-api
+
+# 가상환경 생성 (선택사항이지만 권장)
+python -m venv venv
+
+# 가상환경 활성화
+# Linux/Mac:
+source venv/bin/activate
+# Windows:
+venv\Scripts\activate
+
+# 의존성 설치
+pip install -r requirements.txt
+```
+
+## 2️⃣ 환경 설정
+
+```bash
+# .env 파일 생성
+cp .env.example .env
+
+# .env 파일 편집
+nano .env  # 또는 원하는 에디터 사용
+```
+
+### 필수 설정 항목:
+
+```env
+# Proxmox 설정
+PROXMOX_HOST=https://pve.mouse84.com:8006
+PROXMOX_API_TOKEN=PVEAPIToken=root@pam!vconnect=YOUR-TOKEN-HERE
+
+# SSH Gateway 설정 (터널링 서버)
+SSH_HOST=your-ssh-server.com
+SSH_PORT=22
+SSH_USERNAME=tunneluser
+SSH_KEY_PATH=/path/to/ssh/key
+# 또는
+SSH_PASSWORD=your-password
+
+# JWT Secret (반드시 변경!)
+JWT_SECRET_KEY=your-super-secret-key-change-this
+```
+
+## 3️⃣ 서버 실행
+
+```bash
+# 개발 모드 (자동 리로드)
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+
+# 프로덕션 모드
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+## 4️⃣ 접속 확인
+
+브라우저에서:
+- API Docs: http://localhost:8000/docs
+- Health Check: http://localhost:8000/health
+
+## 5️⃣ 테스트
+
+### 로그인 테스트
+```bash
+curl -X POST http://localhost:8000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}'
+```
+
+### VM 목록 조회
+```bash
+# 먼저 로그인해서 토큰 받기
+TOKEN="your-jwt-token-here"
+
+curl -X GET http://localhost:8000/api/vms/my \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+## 6️⃣ Docker로 실행 (선택사항)
+
+```bash
+# Docker 이미지 빌드
+docker build -t vconnect-api .
+
+# 컨테이너 실행
+docker run -d \
+  --name vconnect-api \
+  -p 8000:8000 \
+  --env-file .env \
+  vconnect-api
+```
+
+## 📋 기본 관리자 계정
+
+- Username: `admin`
+- Password: `admin123`
+
+⚠️ **보안을 위해 첫 로그인 후 반드시 비밀번호를 변경하세요!**
+
+## 🔧 문제 해결
+
+### Proxmox 연결 오류
+- API Token이 올바른지 확인
+- Proxmox 서버 URL과 포트 확인 (기본 8006)
+- 방화벽 설정 확인
+
+### SSH 터널 오류
+- SSH 서버 접속 정보 확인
+- SSH 키 파일 경로 확인
+- SSH 서버에서 Port Forwarding 허용 여부 확인
+
+### 포트 충돌
+- 8000 포트가 이미 사용 중이면 다른 포트로 변경:
+  ```bash
+  uvicorn app.main:app --reload --port 8001
+  ```
+
+## 📚 API 문서
+
+서버 실행 후 http://localhost:8000/docs 에서 자동 생성된 API 문서를 확인할 수 있습니다.
+
+### 주요 엔드포인트:
+
+**인증**
+- POST /api/auth/register - 회원가입
+- POST /api/auth/login - 로그인
+- GET /api/auth/me - 현재 사용자 정보
+
+**VM 관리**
+- GET /api/vms/my - 내 VM 목록
+- GET /api/vms/{vm_id} - VM 상세 정보
+- POST /api/vms/{vm_id}/start - VM 시작
+- POST /api/vms/{vm_id}/stop - VM 종료
+
+**터널 관리**
+- POST /api/tunnel/create - SSH 터널 생성
+- GET /api/tunnel/{session_id}/status - 터널 상태
+- DELETE /api/tunnel/{session_id} - 터널 종료
+
+## 🎯 다음 단계
+
+1. WPF 클라이언트와 연동
+2. 사용자별 VM 접근 권한 설정
+3. 감사 로그 확인
+4. 프로덕션 배포