156 lines
5.0 KiB
Markdown
156 lines
5.0 KiB
Markdown
# VConnect API Server
|
|
|
|
Zero-Port, Zero-VPN SSH 기반 Proxmox VM 원격접속 플랫폼
|
|
|
|
## 아키텍처
|
|
|
|
```
|
|
[WPF Client] ←JWT→ [FastAPI Server] ←SSH→ [Proxmox VE]
|
|
↓
|
|
[PostgreSQL DB]
|
|
```
|
|
|
|
## 핵심 기능
|
|
|
|
### 1. 인증 시스템
|
|
- JWT 기반 토큰 인증
|
|
- 사용자 관리 (회원가입/로그인)
|
|
- 역할 기반 접근 제어 (RBAC)
|
|
|
|
### 2. Proxmox 통합
|
|
- API Token 기반 Proxmox 연동
|
|
- VM 목록 조회 및 상태 모니터링
|
|
- VM 제어 (시작/종료/재시작)
|
|
- QEMU Guest Agent IP 정보 수집
|
|
|
|
### 3. SSH 터널링 및 자격증명
|
|
- **Zero-Trust Access**: 클라이언트는 SSH Private Key 없이 일회용 자격증명으로 접속
|
|
- **임시 자격증명 발급**: JWT 토큰 인증 후 1시간 유효한 임시 SSH 비밀번호 발급
|
|
- **PAM 연동**: SSH 게이트웨이에서 API를 통해 임시 비밀번호 검증
|
|
- **동적 포트 할당**: 세션별 독립적인 포트 포워딩 관리
|
|
|
|
### 4. 감사 로그
|
|
- 접속 기록 (누가, 언제, 어떤 VM에)
|
|
- VM 제어 이력
|
|
- 보안 이벤트 추적
|
|
|
|
### 5. 자동 업데이트
|
|
- 클라이언트 버전 관리 및 업데이트 배포 지원
|
|
|
|
## 기술 스택
|
|
|
|
- **FastAPI**: 고성능 Python 웹 프레임워크
|
|
- **PostgreSQL**: 관계형 데이터베이스
|
|
- **SQLAlchemy**: ORM (Async support)
|
|
- **Alembic**: DB 마이그레이션 관리
|
|
- **JWT (Jose)**: 토큰 기반 인증
|
|
- **Paramiko / AsyncSSH**: SSH 터널 및 연결 관리
|
|
- **Uvicorn**: ASGI 웹 서버
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
vconnect-api/
|
|
├── app/
|
|
│ ├── main.py # FastAPI 앱 진입점
|
|
│ ├── config.py # 설정 관리 (.env 로드)
|
|
│ ├── database.py # DB 세션 및 엔진
|
|
│ ├── models/ # SQLAlchemy 모델 (User, VM, AuditLog)
|
|
│ ├── schemas/ # Pydantic 스키마 (Request/Response)
|
|
│ ├── api/ # API 라우터
|
|
│ │ ├── auth.py # 인증 (로그인/가입)
|
|
│ │ ├── vms.py # VM 제어 및 조회
|
|
│ │ ├── tunnel.py # SSH 터널 관리
|
|
│ │ ├── ssh_credentials.py # 임시 SSH 자격증명 발급/검증
|
|
│ │ └── admin.py # 관리자 기능 (사용자 관리, 로그)
|
|
│ ├── services/ # 비즈니스 로직
|
|
│ └── utils/ # 유틸리티 (JWT, Security)
|
|
├── alembic/ # DB 마이그레이션 스크립트
|
|
├── requirements.txt # 의존성 패키지 목록
|
|
├── docker-compose.yml # Docker 배포 설정
|
|
├── Dockerfile # Docker 빌드 설정
|
|
└── README.md # 문서
|
|
```
|
|
|
|
## 환경 변수 (.env)
|
|
|
|
```env
|
|
# Database
|
|
DATABASE_URL=postgresql://user:password@localhost/vconnect
|
|
|
|
# JWT
|
|
JWT_SECRET_KEY=your-secret-key-change-it
|
|
JWT_ALGORITHM=HS256
|
|
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
|
|
|
|
# Proxmox API
|
|
PROXMOX_HOST=https://pve.example.com:8006
|
|
PROXMOX_API_TOKEN=PVEAPIToken=root@pam!vconnect=xxx...
|
|
|
|
# SSH Gateway (Zero-Port)
|
|
SSH_HOST=ssh.example.com # 클라이언트가 접속할 외부 주소
|
|
SSH_PORT=22 # 외부 포트
|
|
SSH_INTERNAL_HOST=127.0.0.1 # 내부 터널링 바인딩 주소
|
|
```
|
|
|
|
## 설치 및 실행
|
|
|
|
```bash
|
|
# 가상환경 생성
|
|
python -m venv venv
|
|
# Windows
|
|
venv\Scripts\activate
|
|
# Linux/Mac
|
|
source venv/bin/activate
|
|
|
|
# 의존성 설치
|
|
pip install -r requirements.txt
|
|
|
|
# 환경 변수 설정
|
|
cp .env.example .env
|
|
# .env 파일 편집...
|
|
|
|
# DB 마이그레이션 (테이블 생성)
|
|
alembic upgrade head
|
|
|
|
# 서버 실행 (개발 모드)
|
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
## API 엔드포인트 요약
|
|
|
|
### 인증 (`/api/v1/auth`)
|
|
- `POST /register` - 회원가입
|
|
- `POST /login` - 로그인 (AccessToken 발급)
|
|
- `GET /me` - 현재 사용자 정보 확인
|
|
|
|
### VM 관리 (`/api/v1/vms`)
|
|
- `GET /my` - 사용자별 할당된 VM 목록
|
|
- `POST /{vm_id}/start` - VM 켜기
|
|
- `POST /{vm_id}/stop` - VM 끄기
|
|
|
|
### SSH 자격증명 (`/api/v1/ssh`)
|
|
- `POST /credentials` - [클라이언트용] 1시간 유효한 임시 SSH 비밀번호 발급
|
|
- `POST /verify` - [게이트웨이용] 임시 비밀번호 유효성 검증
|
|
|
|
### 터널 관리 (`/api/v1/tunnel`)
|
|
- `POST /create` - SSH 터널 세션 생성
|
|
- `DELETE /{tunnel_id}` - 터널 세션 종료
|
|
|
|
### 관리자 (`/api/v1/admin`)
|
|
- `GET /users` - 전체 사용자 관리
|
|
- `GET /audit-logs` - 전체 감사 로그 조회
|
|
- `GET /stats` - 시스템 통계
|
|
|
|
## 개발 로드맵 상태
|
|
|
|
- [x] 프로젝트 구조 및 FastAPI 기본 설정
|
|
- [x] PostgreSQL 연동 및 Alembic 마이그레이션 구성
|
|
- [x] JWT 인증 시스템 (Login/Refresh)
|
|
- [x] Proxmox API 연동 (VM 상태/제어)
|
|
- [x] SSH 터널링 매니저 구현
|
|
- [x] **Zero-Trust 임시 자격증명 시스템** (SSH Password Manager)
|
|
- [x] 감사 로그 (Audit Log)
|
|
- [x] Docker 기반 배포 환경 (Dockerfile, Confirm)
|
|
- [ ] 클라이언트 자동 업데이트 배포 시스템 고도화
|
|
- [ ] 유닛 테스트 작성 (Pytest) |