# 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. 프로덕션 배포