152 lines
3.2 KiB
Markdown
152 lines
3.2 KiB
Markdown
# 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. 프로덕션 배포
|