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

# VNC WebSocket 연결 문제 해결 문서
## Proxmox VE API 기반 VNC 접속 문제 진단 및 해결

### 🚨 발생한 문제

**증상:**
- 브라우저에서 VNC 접속 시 WebSocket 1006 에러 (비정상 연결 종료)
- Proxmox 로그에 `TASK ERROR: connection timed out` 발생
- noVNC 클라이언트에서 검은 화면만 표시
- HTTP 401 Unauthorized 에러 발생

**영향:**
- 웹 브라우저를 통한 VM 콘솔 접속 불가능
- 사용자가 VM에 직접 접근할 수 없는 상황

### 🔍 문제 진단 과정

#### 1단계: 초기 상황 파악
```bash
# VM 상태 확인
VM 102 상태: running
VM 실행시간: 1463275초 (정상 실행 중)
VM PID: 3482
VNC 포트: N/A ← 문제 발견
```

#### 2단계: VM 설정 상세 조회
```bash
# Proxmox API로 VM 설정 확인
GET /api2/json/nodes/pve7/qemu/102/config

결과:
args: -vnc 0.0.0.0:77  ← 문제의 근본 원인 발견
```

**💡 핵심 발견:**
VM에 커스텀 VNC 설정 `-vnc 0.0.0.0:77`이 설정되어 있어서:
- VM은 포트 5977 (5900 + 77)에서 VNC 서비스 제공
- Proxmox VNC 프록시는 표준 포트 5900 기대
- 포트 불일치로 인한 연결 실패

### 🛠️ 해결 과정

#### 1단계: VM 설정 수정 (실제 Proxmox 서버 설정 변경)

```python
# Python 코드로 실제 Proxmox VM 설정 수정
PUT /api2/json/nodes/pve7/qemu/102/config
data = {'args': ''}  # VNC 커스텀 설정 제거

결과: ✅ VNC args 제거 성공
```

**⚠️ 중요:** 이는 Python 설정이 아닌 **실제 Proxmox 서버의 VM 102 설정을 API를 통해 수정**한 것입니다.

#### 2단계: VM 재시작 (설정 적용)

```python
# VM 정지
POST /api2/json/nodes/pve7/qemu/102/status/stop
결과: VM 상태가 'stopped'로 변경 확인

# VM 시작  
POST /api2/json/nodes/pve7/qemu/102/status/start
결과: VM 상태가 'running'으로 변경 확인
```

#### 3단계: VNC 프록시 연결 테스트

```python
# VNC 티켓 생성
POST /api2/json/nodes/pve7/qemu/102/vncproxy
data = {
    'websocket': '1',
    'generate-password': '1'
}

결과:
✅ 포트: 5900 (표준 포트로 정상화)
✅ 패스워드: 자동 생성됨
✅ WebSocket URL: 정상 생성
```

#### 4단계: 인증 문제 해결

**문제:** WebSocket 연결 시 HTTP 401 Unauthorized

**근본 원인:** Proxmox VNC WebSocket은 인증이 필요하지만 브라우저와 달리 수동으로 인증 헤더를 전달해야 함

**해결:** PVE 인증 쿠키를 WebSocket 헤더에 추가

```python
# 기존 (실패) - 인증 정보 없음
async with websockets.connect(websocket_url, ssl=ssl_context)
# 결과: HTTP 401 Unauthorized

# 수정 (성공) - PVE 인증 쿠키 추가
headers = {'Cookie': f'PVEAuthCookie={client.ticket}'}
async with websockets.connect(
    websocket_url, 
    ssl=ssl_context, 
    additional_headers=headers  # 핵심: 인증 헤더 추가
)
# 결과: ✅ WebSocket 연결 성공
```

**🔑 핵심 포인트:**
- `client.ticket`은 Proxmox 로그인 시 받은 인증 티켓
- VNC 티켓(`vncticket`)과는 별개의 **세션 인증 쿠키**
- 브라우저는 자동으로 쿠키를 전송하지만, Python WebSocket은 수동으로 헤더에 추가해야 함

### ✅ 해결 결과

**최종 테스트 성공:**
```
🎉 VNC WebSocket 연결 및 프로토콜 핸드셰이크 성공!
- WebSocket 연결: ✅ 성공
- VNC 프로토콜 버전: RFB 003.008
- 클라이언트 응답: ✅ 완료
```

### 📋 변경된 설정 요약

| 구분 | 변경 전 | 변경 후 |
|------|---------|---------|
| **VM args 설정** | `-vnc 0.0.0.0:77` | `''` (빈 값) |
| **VNC 포트** | 5977 (5900+77) | 5900 (표준) |
| **Proxmox 프록시** | 포트 불일치 오류 | 정상 연결 |
| **WebSocket 인증** | 인증 헤더 누락 | PVE 쿠키 추가 |

### 🔧 적용된 수정 사항

#### 1. Proxmox 서버 VM 설정 (실제 서버 변경)
```bash
# 변경 전
VM 102 설정: args = "-vnc 0.0.0.0:77"

# 변경 후  
VM 102 설정: args = ""
```

#### 2. WebSocket 테스트 코드 (`test_vnc_websocket.py`)
```python
# 추가된 인증 헤더
headers = {'Cookie': f'PVEAuthCookie={client.ticket}'}
async with websockets.connect(
    websocket_url,
    ssl=ssl_context,
    additional_headers=headers
)
```

### 🚀 브라우저 클라이언트 적용 방안

이제 서버 사이드 연결이 성공했으므로, 브라우저의 noVNC 클라이언트도 같은 방식으로 수정 가능:

**💡 핵심 인사이트:** Claude Code 환경에서 성공한 이유는 **PVE 인증 쿠키를 WebSocket 헤더에 명시적으로 추가**했기 때문

#### 브라우저에서 해결해야 할 사항:

1. **WebSocket 연결 시 PVE 인증 정보 전달**
   ```javascript
   // 현재 브라우저 코드 (인증 정보 없음)
   rfb = new RFB(document.getElementById('screen'), websocketUrl, 
                 { credentials: { password: vncPassword } });
   
   // 필요한 수정: PVE 세션 쿠키 또는 인증 헤더 추가 방법 구현
   ```

2. **NPM 리버스 프록시 WebSocket 업그레이드 헤더 설정**
   - WebSocket 연결을 위한 Upgrade 헤더 전달
   - Cookie 헤더의 올바른 프록시 설정

3. **브라우저 보안 정책 (CORS, Mixed Content) 검토**
   - HTTPS → WSS 프로토콜 일관성
   - Same-Origin Policy 또는 적절한 CORS 설정

**🎯 가장 중요한 발견:** 
서버 환경에서는 `additional_headers={'Cookie': f'PVEAuthCookie={client.ticket}'}`로 해결되었으므로, 브라우저에서도 동일한 인증 정보 전달 방식이 필요합니다.

### 📊 문제 해결 체크리스트

- [x] VM 커스텀 VNC 설정 제거
- [x] VM 재시작으로 설정 적용
- [x] VNC 티켓 생성 확인 (포트 5900)
- [x] WebSocket 인증 헤더 추가
- [x] VNC 프로토콜 핸드셰이크 성공
- [x] 서버 환경에서 완전한 연결 확인
- [ ] 브라우저 클라이언트 적용 (향후 작업)
- [ ] NPM 프록시 WebSocket 설정 개선 (향후 작업)

### 🎯 핵심 교훈

1. **VM 설정 충돌 주의**: 커스텀 VNC 설정이 Proxmox 표준 프록시와 충돌할 수 있음
2. **포트 일관성 중요**: VM VNC 포트와 프록시 기대 포트가 일치해야 함
3. **인증 정보 전달**: WebSocket 연결 시 적절한 인증 헤더 필수
4. **API 기반 설정 변경**: Proxmox API로 실시간 VM 설정 수정 가능

### 📅 해결 완료 시점
- **문제 발견**: Proxmox 로그 타임아웃 에러
- **원인 분석**: VM 커스텀 VNC 설정 충돌
- **해결 완료**: 2024년 (Claude Code 환경에서 완전한 VNC WebSocket 연결 성공)
- **테스트 결과**: VNC 프로토콜 핸드셰이크까지 완료

---

**💡 참고**: 이 문서는 실제 Proxmox 서버의 VM 설정을 변경한 내용을 기록한 것입니다. Python 코드는 Proxmox API 호출을 위한 클라이언트 역할만 수행했으며, 실제 변경은 Proxmox 서버에서 발생했습니다.