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)

# 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    # 내부 터널링 바인딩 주소

설치 및 실행

# 가상환경 생성
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 - 시스템 통계

개발 로드맵 상태

• 프로젝트 구조 및 FastAPI 기본 설정
• PostgreSQL 연동 및 Alembic 마이그레이션 구성
• JWT 인증 시스템 (Login/Refresh)
• Proxmox API 연동 (VM 상태/제어)
• SSH 터널링 매니저 구현
• Zero-Trust 임시 자격증명 시스템 (SSH Password Manager)
• 감사 로그 (Audit Log)
• Docker 기반 배포 환경 (Dockerfile, Confirm)
• 클라이언트 자동 업데이트 배포 시스템 고도화
• 유닛 테스트 작성 (Pytest)