first commit

2025-12-08 21:35:55 +09:00
commit f343f405f7
5357 changed files with 923703 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,156 @@
+# 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)