vconnect-api/QUICKSTART.md

VConnect API 서버 빠른 시작 가이드

1️⃣ 설치

# 프로젝트 디렉토리로 이동
cd vconnect-api

# 가상환경 생성 (선택사항이지만 권장)
python -m venv venv

# 가상환경 활성화
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

2️⃣ 환경 설정

# .env 파일 생성
cp .env.example .env

# .env 파일 편집
nano .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️⃣ 서버 실행

# 개발 모드 (자동 리로드)
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️⃣ 테스트

로그인 테스트

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

VM 목록 조회

# 먼저 로그인해서 토큰 받기
TOKEN="your-jwt-token-here"

curl -X GET http://localhost:8000/api/vms/my \
  -H "Authorization: Bearer $TOKEN"

6️⃣ Docker로 실행 (선택사항)

# 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 포트가 이미 사용 중이면 다른 포트로 변경:

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