# 다중 Proxmox 호스트 관리 시스템 기획서

## 🎯 프로젝트 개요

약국별 독립적인 Proxmox 서버를 중앙에서 통합 관리하는 시스템 구축. Headscale 네트워크를 통해 여러 Proxmox 호스트에 접속하여 VM을 관리하고 VNC 원격 접속을 제공.

## 📋 현재 상황 분석

### 기존 구현 현황
- ✅ 단일 Proxmox 서버 (`pve7.0bin.in`) 연동 완료
- ✅ VNC WebSocket 직접 연결 구현
- ✅ VNC 인증 실패 자동 해결 시스템
- ✅ VM 목록 조회 및 상태 확인
- ✅ VM 시작/정지 기능

### 확장 요구사항
- 약국 수: 100개 (예상)
- Proxmox 호스트: 약국별 1개씩 (총 100대)
- 네트워크: Headscale VPN으로 연결된 사설 IP (예: 100.64.0.x)
- 인증: 모든 Proxmox에서 동일한 `root@pam` 계정 사용

## 🏗️ 시스템 아키텍처

```
┌─────────────────────────────────────────┐
│        Central Management Web UI        │
│          (farmq-admin)                  │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────┴─────────┐
        │   Headscale VPN   │
        │     Network       │
        └─────────┬─────────┘
                  │
    ┌─────────────┼─────────────┐
    │             │             │
┌───▼───┐    ┌───▼───┐    ┌───▼───┐
│약국 A │    │약국 B │    │약국 C │
│Proxmox│    │Proxmox│    │Proxmox│
│100.64.│    │100.64.│    │100.64.│
│0.10   │    │0.11   │    │0.12   │
└───┬───┘    └───┬───┘    └───┬───┘
    │            │            │
┌───▼───┐    ┌───▼───┐    ┌───▼───┐
│VM들   │    │VM들   │    │VM들   │
│- 키오스│    │- POS  │    │- 서버 │
│- POS  │    │- 키오스│    │- 백업 │
└───────┘    └───────┘    └───────┘
```

## 📊 데이터베이스 설계

### 1. Proxmox 호스트 관리 테이블
```sql
CREATE TABLE proxmox_hosts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    pharmacy_id INTEGER NOT NULL,
    pharmacy_name VARCHAR(255) NOT NULL,
    host_ip VARCHAR(15) NOT NULL,           -- 100.64.0.x
    host_port INTEGER DEFAULT 443,
    username VARCHAR(50) DEFAULT 'root@pam',
    password VARCHAR(255) NOT NULL,
    status ENUM('online', 'offline', 'maintenance') DEFAULT 'offline',
    last_check TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (pharmacy_id) REFERENCES pharmacies(pharmacy_id)
);
```

### 2. VM 인벤토리 테이블
```sql
CREATE TABLE vm_inventory (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    proxmox_host_id INTEGER NOT NULL,
    vmid INTEGER NOT NULL,
    vm_name VARCHAR(255) NOT NULL,
    vm_type ENUM('kiosk', 'pos', 'server', 'backup', 'other') DEFAULT 'other',
    node_name VARCHAR(100) NOT NULL,
    status ENUM('running', 'stopped', 'suspended') DEFAULT 'stopped',
    cpu_cores INTEGER,
    memory_mb INTEGER,
    disk_gb INTEGER,
    ip_address VARCHAR(15),
    description TEXT,
    last_sync TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (proxmox_host_id) REFERENCES proxmox_hosts(id)
);
```

### 3. VNC 세션 확장 테이블
```sql
CREATE TABLE vnc_sessions_extended (
    session_id VARCHAR(36) PRIMARY KEY,
    proxmox_host_id INTEGER NOT NULL,
    vmid INTEGER NOT NULL,
    vm_name VARCHAR(255) NOT NULL,
    websocket_url TEXT NOT NULL,
    password VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    expires_at TIMESTAMP,
    last_refresh TIMESTAMP,
    FOREIGN KEY (proxmox_host_id) REFERENCES proxmox_hosts(id)
);
```

## 🔧 주요 기능 구현 계획

### 1. Proxmox 호스트 관리
- **호스트 등록/수정/삭제**
  - 약국 정보와 연동하여 Proxmox 호스트 정보 관리
  - IP, 포트, 인증 정보 저장
  
- **호스트 상태 모니터링**
  - 주기적 헬스체크 (ping, API 연결 확인)
  - 오프라인 호스트 알림 및 상태 표시

- **보안 관리**
  - 패스워드 암호화 저장
  - API 토큰 관리 옵션 제공

### 2. 통합 VM 관리 대시보드
- **멀티 호스트 VM 목록**
  ```
  약국A (100.64.0.10) - 온라인
  ├── VM 101: Kiosk-1 (실행중)
  ├── VM 102: POS-System (정지됨)
  └── VM 103: Backup-Server (실행중)
  
  약국B (100.64.0.11) - 오프라인
  ├── 연결 불가
  
  약국C (100.64.0.12) - 온라인
  ├── VM 201: Main-Server (실행중)
  └── VM 202: Kiosk-Terminal (실행중)
  ```

- **통합 검색 및 필터링**
  - 약국별, VM 타입별, 상태별 필터링
  - VM 이름 및 IP 주소 검색
  - 상태별 대시보드 (전체 실행중/정지됨 VM 수)

- **배치 작업**
  - 여러 VM 동시 시작/정지
  - 약국별 전체 VM 관리
  - 예약 작업 (특정 시간에 VM 시작/정지)

### 3. 동적 VNC 접속 시스템
- **호스트 자동 선택**
  ```python
  def connect_to_vm(pharmacy_id, vmid):
      # 1. pharmacy_id로 Proxmox 호스트 정보 조회
      host_info = get_proxmox_host_by_pharmacy(pharmacy_id)
      
      # 2. 해당 호스트에서 VM 정보 확인
      vm_info = get_vm_info(host_info, vmid)
      
      # 3. VNC 티켓 생성 및 연결
      vnc_ticket = create_vnc_ticket(host_info, vm_info)
      return vnc_ticket
  ```

- **다중 세션 관리**
  - 서로 다른 Proxmox 호스트의 여러 VM에 동시 VNC 접속
  - 세션별 독립적인 티켓 관리
  - 탭 기반 다중 VNC 창 지원

### 4. 모니터링 및 알림
- **리소스 모니터링**
  - 모든 Proxmox 호스트의 CPU, 메모리, 스토리지 사용량
  - VM별 리소스 사용 현황
  - 임계치 초과 시 알림

- **이벤트 로그**
  - VM 시작/정지 이력
  - VNC 접속 이력
  - 시스템 오류 및 복구 이력

## 🛠️ API 설계

### Proxmox 호스트 관리 API
```http
GET    /api/proxmox/hosts              # 호스트 목록 조회
POST   /api/proxmox/hosts              # 호스트 등록
PUT    /api/proxmox/hosts/{host_id}    # 호스트 정보 수정
DELETE /api/proxmox/hosts/{host_id}    # 호스트 삭제
GET    /api/proxmox/hosts/{host_id}/health # 호스트 상태 확인
```

### 통합 VM 관리 API
```http
GET    /api/vms                        # 모든 호스트의 VM 목록
GET    /api/vms/pharmacy/{pharmacy_id} # 특정 약국의 VM 목록
GET    /api/vms/sync                   # VM 정보 동기화
POST   /api/vms/batch/start            # 여러 VM 일괄 시작
POST   /api/vms/batch/stop             # 여러 VM 일괄 정지
```

### 동적 VNC 접속 API
```http
POST   /api/vnc/connect               # 동적 VNC 연결 생성
# Request Body:
{
    "pharmacy_id": 1,
    "vmid": 101,
    "vm_type": "kiosk"
}

GET    /api/vnc/sessions              # 활성 VNC 세션 목록
POST   /api/vnc/refresh/{session_id}  # VNC 티켓 새로고침 (기존)
```

## 🎨 UI/UX 설계

### 1. 대시보드 개선
```
┌─────────────────────────────────────────────────────────────┐
│ 🏥 PharmQ - 다중 Proxmox 관리 시스템                       │
├─────────────────────────────────────────────────────────────┤
│ 📊 전체 현황                                                │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐             │
│ │호스트수 │ │총VM수   │ │실행중   │ │오프라인 │             │
│ │  100    │ │  450    │ │  380    │ │   15    │             │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘             │
├─────────────────────────────────────────────────────────────┤
│ 🔍 검색 및 필터                                             │
│ [약국명/IP 검색____] [호스트상태▼] [VM타입▼] [VM상태▼]     │
└─────────────────────────────────────────────────────────────┘
```

### 2. 호스트 목록 페이지
```
┌─────────────────────────────────────────────────────────────┐
│ 🖥️ Proxmox 호스트 관리                    [+ 호스트 추가]    │
├─────────────────────────────────────────────────────────────┤
│ 약국명      │ IP주소        │ 상태   │ VM수 │ 마지막확인      │
├─────────────────────────────────────────────────────────────┤
│ 🟢 약국A    │ 100.64.0.10  │ 온라인 │ 5개  │ 1분전          │
│ 🔴 약국B    │ 100.64.0.11  │ 오프라인│ -   │ 30분전         │
│ 🟢 약국C    │ 100.64.0.12  │ 온라인 │ 3개  │ 2분전          │
└─────────────────────────────────────────────────────────────┘
```

### 3. 통합 VM 관리 페이지
```
┌─────────────────────────────────────────────────────────────┐
│ 🔧 통합 VM 관리                                             │
├─────────────────────────────────────────────────────────────┤
│ 📍 약국A (100.64.0.10) - 온라인                             │
│   ├── 🖥️ VM101: Kiosk-1    [실행중] [VNC] [정지]           │
│   ├── 🖥️ VM102: POS-System [정지됨] [시작] [VNC]           │
│   └── 🖥️ VM103: Backup     [실행중] [VNC] [정지]           │
├─────────────────────────────────────────────────────────────┤
│ 📍 약국C (100.64.0.12) - 온라인                             │
│   ├── 🖥️ VM201: Server     [실행중] [VNC] [정지]           │
│   └── 🖥️ VM202: Kiosk      [실행중] [VNC] [정지]           │
└─────────────────────────────────────────────────────────────┘
```

## 🔧 구현 단계

### Phase 1: 기반 시스템 확장 (1-2주)
1. **데이터베이스 스키마 확장**
   - 다중 호스트 테이블 생성
   - 기존 데이터 마이그레이션

2. **Proxmox 클라이언트 다중화**
   - 호스트별 클라이언트 풀 관리
   - 연결 관리 및 로드밸런싱

### Phase 2: 호스트 관리 시스템 (2-3주)
1. **호스트 등록/관리 기능**
   - CRUD API 구현
   - 관리 UI 개발

2. **상태 모니터링**
   - 헬스체크 시스템
   - 알림 기능

### Phase 3: 통합 VM 관리 (2-3주)
1. **다중 호스트 VM 조회**
   - 통합 대시보드
   - 검색/필터링 기능

2. **배치 작업 시스템**
   - 일괄 작업 API
   - 스케줄링 기능

### Phase 4: 고도화 기능 (2-3주)
1. **성능 최적화**
   - 캐싱 시스템
   - 비동기 처리

2. **보안 강화**
   - 접근 권한 관리
   - 감사 로그

## 🚨 고려사항

### 기술적 도전과제
1. **네트워크 지연**
   - Headscale VPN을 통한 다중 호스트 접근 시 지연 가능성
   - 연결 타임아웃 및 재시도 로직 필요

2. **확장성**
   - 100개 호스트 동시 관리 시 리소스 사용량
   - 동시 VNC 세션 수 제한 고려

3. **장애 처리**
   - 개별 호스트 오프라인 시 graceful degradation
   - 부분 장애 상황에서의 서비스 연속성

### 보안 고려사항
1. **인증 정보 관리**
   - 각 Proxmox 호스트별 패스워드 암호화 저장
   - API 토큰 순환 정책

2. **네트워크 보안**
   - Headscale 네트워크 내부 통신 암호화
   - VNC 세션 보안 강화

## 📈 성공 지표

### 기능적 지표
- ✅ 100개 Proxmox 호스트 동시 관리
- ✅ 1000개 이상 VM 통합 관리
- ✅ 동시 VNC 세션 50개 이상 지원
- ✅ 호스트 상태 확인 응답 시간 < 5초

### 성능 지표
- ✅ 대시보드 로딩 시간 < 3초
- ✅ VM 목록 조회 시간 < 5초
- ✅ VNC 연결 설정 시간 < 10초
- ✅ 시스템 가용성 99.5% 이상

## 🎯 결론

이 다중 Proxmox 호스트 관리 시스템을 통해 약국별로 분산된 IT 인프라를 중앙에서 효율적으로 관리할 수 있게 됩니다. Headscale 네트워크를 활용한 안전한 연결과 통합 관리 인터페이스를 제공하여 운영 효율성을 크게 향상시킬 수 있을 것입니다.

---

*이 기획서는 현재 단일 Proxmox 호스트 관리 시스템을 다중 호스트 환경으로 확장하기 위한 상세 계획을 담고 있습니다. 단계적 구현을 통해 안정적이고 확장 가능한 시스템을 구축할 수 있을 것입니다.*