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

안정적인 PVE 인증 정보 전달 전략

브라우저 WebSocket VNC 연결 개선 방안

🚨 현재 문제 상황

간헐적 연결 실패 원인 분석:

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

Claude Code 환경 성공 요인:

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 프록시 엔드포인트

# 새로운 엔드포인트: /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 변경

// 기존 (직접 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 프록시 구현

# 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: 브라우저 클라이언트 수정

// vnc_simple.html 수정 계획
// 1. WebSocket URL을 Flask 프록시로 변경
// 2. VNC 티켓 생성 로직 제거 (Flask에서 처리)
// 3. 연결 상태 관리 개선

Phase 3: 세션 관리 강화

# 세션 만료 감지 및 자동 갱신
# 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 프록시를 통해 브라우저 환경에서도 안정적으로 구현하자는 것이 이 전략의 핵심입니다.