headscale-tailscale-replacement/farmq-admin/Stable_PVE_Authentication_Strategy.md

# 안정적인 PVE 인증 정보 전달 전략
## 브라우저 WebSocket VNC 연결 개선 방안

### 🚨 현재 문제 상황

**간헐적 연결 실패 원인 분석:**
- 브라우저에서 PVE 인증 쿠키가 WebSocket 연결 시 불안정하게 전달됨
- NPM 리버스 프록시에서 인증 헤더 전달 불일치
- Proxmox 세션 만료 및 브라우저 쿠키 상태 변화
- CORS/보안 정책으로 인한 쿠키 차단

**Claude Code 환경 성공 요인:**
```python
headers = {'Cookie': f'PVEAuthCookie={client.ticket}'}
async with websockets.connect(websocket_url, ssl=ssl_context, additional_headers=headers)
```
→ **명시적 인증 헤더 전달로 100% 안정적 연결**

### 🎯 안정적인 인증 전략 옵션

#### 방법 1: Flask 백엔드 인증 프록시 (권장 ⭐⭐⭐⭐⭐)

**개념:**
- Flask가 Proxmox 인증을 대신 처리
- 브라우저는 Flask 세션만 관리
- Flask가 WebSocket을 Proxmox로 프록시

**장점:**
- ✅ 브라우저 보안 정책 우회
- ✅ 인증 상태 중앙 관리
- ✅ 세션 만료 자동 갱신 가능
- ✅ NPM 설정 변경 불필요

**구현 구조:**
```
브라우저 WebSocket → Flask WebSocket 프록시 → Proxmox VNC WebSocket
                   ↑ (PVE 인증 헤더 자동 추가)
```

#### 방법 2: Flask API를 통한 인증 토큰 전달 (보통 ⭐⭐⭐)

**개념:**
- Flask API로 PVE 인증 정보 조회
- JavaScript에서 받아서 WebSocket 연결 시 사용

**장점:**
- ✅ 기존 코드 수정 최소화
- ✅ 명시적 인증 제어

**단점:**
- ❌ 브라우저 JavaScript에 인증 정보 노출
- ❌ noVNC 라이브러리 제약 (커스텀 헤더 지원 제한)

#### 방법 3: NPM 설정 개선 (복잡함 ⭐⭐)

**개념:**
- Nginx 설정으로 WebSocket 인증 헤더 자동 추가

**단점:**
- ❌ NPM 설정 복잡도 증가
- ❌ 여전히 브라우저 보안 정책 제약
- ❌ 디버깅 어려움

### 🏆 권장 솔루션: Flask WebSocket 프록시

#### 아키텍처 설계
```
┌─────────────┐    WebSocket     ┌─────────────┐    WebSocket+Auth    ┌─────────────┐
│   브라우저   │ ────────────────→ │    Flask    │ ───────────────────→ │  Proxmox VE │
│  (noVNC)    │                  │   Proxy     │                     │ VNC Server  │
└─────────────┘                  └─────────────┘                     └─────────────┘
                                        ↑
                                   자동 PVE 인증
                                   헤더 추가 처리
```

#### 핵심 컴포넌트

**1. Flask WebSocket 프록시 엔드포인트**
```python
# 새로운 엔드포인트: /vnc/<vm_id>/proxy
@app.websocket('/vnc/<int:vm_id>/proxy')
async def vnc_websocket_proxy(vm_id):
    # 1. Flask 세션 검증
    # 2. Proxmox 인증 정보 준비
    # 3. Proxmox VNC WebSocket 연결 (PVE 쿠키 포함)
    # 4. 브라우저 ↔ Proxmox 간 데이터 양방향 중계
```

**2. 브라우저 WebSocket URL 변경**
```javascript
// 기존 (직접 Proxmox 연결)
const websocketUrl = 'wss://pve7.0bin.in:443/api2/json/nodes/pve7/qemu/102/vncwebsocket?...'

// 새로운 (Flask 프록시 경유)
const websocketUrl = 'wss://farmq.0bin.in/vnc/102/proxy'
```

### 🔧 현재 코드 개선 계획

#### Phase 1: Flask WebSocket 프록시 구현
```python
# app.py에 추가할 함수들
async def create_proxmox_vnc_connection(vm_id):
    """Proxmox VNC WebSocket 연결 생성 (인증 헤더 포함)"""
    
async def proxy_websocket_data(browser_ws, proxmox_ws):
    """브라우저와 Proxmox 간 WebSocket 데이터 중계"""
    
@app.websocket('/vnc/<int:vm_id>/proxy')
async def vnc_websocket_proxy(vm_id):
    """VNC WebSocket 프록시 메인 핸들러"""
```

#### Phase 2: 브라우저 클라이언트 수정
```javascript
// vnc_simple.html 수정 계획
// 1. WebSocket URL을 Flask 프록시로 변경
// 2. VNC 티켓 생성 로직 제거 (Flask에서 처리)
// 3. 연결 상태 관리 개선
```

#### Phase 3: 세션 관리 강화
```python
# 세션 만료 감지 및 자동 갱신
# Proxmox 인증 상태 모니터링
# 오류 상황 처리 및 복구
```

### 🎯 구현 우선순위

**즉시 구현 (High Priority):**
- [ ] Flask WebSocket 라이브러리 추가 (flask-socketio 또는 quart)
- [ ] VNC WebSocket 프록시 기본 구조 구현
- [ ] 브라우저 WebSocket URL 변경

**단계적 개선 (Medium Priority):**
- [ ] 세션 만료 자동 처리
- [ ] 연결 상태 모니터링
- [ ] 오류 복구 메커니즘

**최적화 (Low Priority):**
- [ ] 성능 튜닝 (연결 풀링, 캐싱)
- [ ] 로깅 및 모니터링 강화
- [ ] 다중 VM 동시 연결 지원

### 🔒 보안 고려사항

**인증 보안:**
- Flask 세션으로 사용자 권한 검증
- Proxmox 인증 정보는 서버 메모리에만 보관
- 브라우저에 민감 정보 노출 방지

**네트워크 보안:**
- Flask ↔ Proxmox 통신은 내부 네트워크
- SSL/TLS 종단간 암호화 유지
- CORS 정책 적절한 설정

### 📊 예상 효과

**안정성 개선:**
- ✅ 인증 실패로 인한 연결 오류 완전 제거
- ✅ 세션 만료 자동 처리
- ✅ 네트워크 오류 복구 능력 향상

**사용자 경험:**
- ✅ 일관된 연결 성공률
- ✅ 빠른 연결 속도 (중간 단계 제거)
- ✅ 오류 상황 사용자 친화적 처리

**유지보수성:**
- ✅ 중앙집중식 인증 관리
- ✅ 디버깅 용이성 향상
- ✅ 코드 복잡도 감소

### 🚀 다음 단계

1. **Flask WebSocket 라이브러리 선택 및 설치**
2. **간단한 프록시 프로토타입 구현**
3. **기본 연결 테스트**
4. **브라우저 클라이언트 수정**
5. **통합 테스트 및 검증**

**⚠️ 주의사항:**
이 변경은 아키텍처 수준의 개선이므로 충분한 테스트와 백업 계획이 필요합니다.

---

**💡 핵심 메시지:** 
Claude Code 환경에서 증명된 "명시적 PVE 인증 헤더 전달" 방식을 Flask 프록시를 통해 브라우저 환경에서도 안정적으로 구현하자는 것이 이 전략의 핵심입니다.