pve9-repo-fix/VNC/README.md

# PharmQ noVNC 자동 설치 스크립트

각 약국 Proxmox Host에 noVNC over WebSocket을 자동으로 설치하는 대화형 스크립트입니다.

## 📦 개요

이 스크립트는 Proxmox VE 환경에서 실행 중인 VM의 VNC 화면을 웹 브라우저로 제공하는 시스템을 자동으로 설치합니다.

**주요 기능:**
- ✅ 대화형 설치 (VM 자동 감지 및 선택)
- ✅ Python 가상환경 자동 구성
- ✅ systemd 서비스 자동 등록
- ✅ 방화벽 설정 (Tailscale VPN 전용)
- ✅ 헬스체크 및 상태 확인
- ✅ 재설치 및 업데이트 지원

## 🚀 빠른 설치

### 원클릭 설치 (curl)

```bash
curl -fsSL https://git.0bin.in/thug0bin/pve9-repo-fix/raw/branch/main/VNC/pharmq-novnc-setup.sh | bash
```

### 수동 다운로드 후 설치

```bash
wget https://git.0bin.in/thug0bin/pve9-repo-fix/raw/branch/main/VNC/pharmq-novnc-setup.sh
chmod +x pharmq-novnc-setup.sh
./pharmq-novnc-setup.sh
```

## 📋 사전 요구사항

### 필수 조건
- ✅ Proxmox VE 환경
- ✅ Root 권한
- ✅ 실행 중인 VM (VNC 활성화)
- ✅ 인터넷 연결

### 자동 설치되는 패키지
- `python3`, `python3-venv`, `python3-pip`
- `git`, `curl`
- `websockify`
- Flask 및 관련 Python 패키지

## 🎯 설치 과정

### 1단계: 스크립트 실행

```bash
curl -fsSL https://git.0bin.in/thug0bin/pve9-repo-fix/raw/branch/main/VNC/pharmq-novnc-setup.sh | bash
```

### 2단계: VM 선택

스크립트가 자동으로 실행 중인 VM 목록을 표시합니다:

```
실행 중인 VM 목록:

  1) VM 201 - PharmQ Server (VM 201) (VNC: 5988)
  2) VM 202 - PharmQ Client (VM 202) (VNC: 5989)

VM1 선택 (번호 입력): 1
VM2를 추가하시겠습니까? [y/N]: y
VM2 선택 (번호 입력): 2
```

### 3단계: 약국 정보 입력

```
약국 코드 (예: P0014): P0014
약국 이름 (예: 늘기쁨약국): 늘기쁨약국
Proxmox 호스트 IP [192.168.0.200]: (Enter)
Proxmox 사용자명 [root@pam]: (Enter)
Proxmox 비밀번호: ********
```

### 4단계: 자동 설치

- ✅ 패키지 설치
- ✅ pharmq-novnc 다운로드
- ✅ Python 가상환경 구성
- ✅ 설정 파일 생성
- ✅ systemd 서비스 등록
- ✅ 서비스 시작

### 5단계: 완료

```
═══════════════════════════════════════════════════════════════════
                    설치가 완료되었습니다!
═══════════════════════════════════════════════════════════════════

설정 요약:
  약국 코드: P0014
  약국 이름: 늘기쁨약국
  설치 경로: /srv/pharmq-novnc

VM 설정:
  VM1: 201 - PharmQ Server (VM 201)
    - VNC 포트: 5988
    - WebSocket 포트: 6085
  VM2: 202 - PharmQ Client (VM 202)
    - VNC 포트: 5989
    - WebSocket 포트: 6086

접속 URL:
  로컬 헬스체크: http://localhost:6000/health
  VM1 noVNC: http://localhost:6000/
  VM2 noVNC: http://localhost:6000/vnc2

Gateway를 통한 접속 (외부):
  https://gateway.pharmq.kr/api/novnc/P0014/vnc1
  https://gateway.pharmq.kr/api/novnc/P0014/vnc2
```

## 🔧 설치 후 확인

### 서비스 상태 확인

```bash
systemctl status pharmq-vnc-app.service
systemctl status pharmq-websockify-vnc1.service
systemctl status pharmq-websockify-vnc2.service
```

### 포트 리스닝 확인

```bash
ss -tlnp | grep -E "6000|6085|6086"
```

### 헬스체크

```bash
curl http://localhost:6000/health
```

**정상 응답 예시:**
```json
{
  "status": "healthy",
  "pharmacy_id": "P0014",
  "pharmacy_name": "늘기쁨약국",
  "vms": [
    {
      "id": 201,
      "name": "PharmQ Server (VM 201)",
      "vnc_connected": true
    },
    {
      "id": 202,
      "name": "PharmQ Client (VM 202)",
      "vnc_connected": true
    }
  ]
}
```

## 🌐 접속 방법

### 1. 로컬 접속 (Proxmox Host 내부)

```
http://localhost:6000/          # VM1
http://localhost:6000/vnc2      # VM2
http://localhost:6000/health    # 헬스체크
```

### 2. Tailscale VPN을 통한 직접 접속

```
http://100.64.0.24:6000/        # VM1 (약국 VPN IP 사용)
http://100.64.0.24:6000/vnc2    # VM2
```

### 3. Gateway를 통한 접속 (권장)

```
https://gateway.pharmq.kr/api/novnc/P0014/vnc1    # VM1
https://gateway.pharmq.kr/api/novnc/P0014/vnc2    # VM2
```

## 🔒 보안 설정

스크립트 실행 중 방화벽 설정 옵션:

```
방화벽 설정을 진행하시겠습니까? [y/N]: y
```

이 옵션을 선택하면:
- ✅ Tailscale VPN(`tailscale0`)에서만 접근 허용
- ✅ 외부 인터넷에서 직접 접근 차단
- ✅ SSH 접속은 영향 없음

### 수동 방화벽 설정

```bash
# Tailscale VPN 인터페이스에서만 허용
ufw allow in on tailscale0 to any port 6000,6085,6086 proto tcp

# 외부 접근 차단
ufw deny 6000/tcp
ufw deny 6085/tcp
ufw deny 6086/tcp

# 방화벽 활성화
ufw enable
```

## 🔄 재설치 및 업데이트

### 재설치

스크립트를 다시 실행하면 기존 설치를 감지하고 옵션을 제공합니다:

```bash
curl -fsSL https://git.0bin.in/thug0bin/pve9-repo-fix/raw/branch/main/VNC/pharmq-novnc-setup.sh | bash
```

```
✅ PharmQ noVNC가 이미 설치되어 있습니다!

현재 설정:
  약국 코드: P0014
  약국 이름: 늘기쁨약국

다음 중 선택하세요:
  1) 상태 확인
  2) 재설치 (기존 설정 백업 후 새로 설치)
  3) 종료

선택 [1/2/3]:
```

### 서비스 재시작

```bash
# 전체 서비스 재시작
systemctl restart pharmq-websockify-vnc1.service
systemctl restart pharmq-websockify-vnc2.service
systemctl restart pharmq-vnc-app.service
```

### 설정 파일 수동 편집

```bash
nano /srv/pharmq-novnc/config.json
systemctl restart pharmq-vnc-app.service
```

## 📊 관리 명령어

### 상태 확인

```bash
/srv/pharmq-novnc/scripts/check-status.sh
```

### 로그 확인

```bash
# 실시간 로그
journalctl -u pharmq-vnc-app.service -f
journalctl -u pharmq-websockify-vnc1.service -f

# 최근 로그
journalctl -u pharmq-vnc-app.service -n 100
```

### 서비스 중지

```bash
systemctl stop pharmq-vnc-app.service
systemctl stop pharmq-websockify-vnc1.service
systemctl stop pharmq-websockify-vnc2.service
```

### 서비스 비활성화

```bash
systemctl disable pharmq-vnc-app.service
systemctl disable pharmq-websockify-vnc1.service
systemctl disable pharmq-websockify-vnc2.service
```

## 🐛 트러블슈팅

### 문제: 서비스가 시작되지 않음

```bash
# 로그 확인
journalctl -xeu pharmq-vnc-app.service

# 수동 테스트
source /srv/pharmq-novnc/venv/bin/activate
cd /srv/pharmq-novnc
python3 app.py
```

### 문제: VNC 화면이 검은색

```bash
# VM 상태 확인
qm status 201
qm status 202

# VNC 포트 확인
nc -zv localhost 5988
nc -zv localhost 5989

# Websockify 재시작
systemctl restart pharmq-websockify-vnc1.service
systemctl restart pharmq-websockify-vnc2.service
```

### 문제: Gateway에서 502 에러

```bash
# 약국 서버 헬스체크
curl http://localhost:6000/health

# Tailscale 연결 확인
tailscale status

# Flask App 재시작
systemctl restart pharmq-vnc-app.service
```

### 문제: 포트 충돌

```bash
# 포트 사용 중인 프로세스 확인
ss -tlnp | grep 6000
ss -tlnp | grep 6085
ss -tlnp | grep 6086

# 프로세스 종료
kill <PID>
```

## 📁 디렉토리 구조

```
/srv/pharmq-novnc/
├── app.py                          # Flask 애플리케이션
├── config.json                     # 설정 파일
├── requirements.txt                # Python 패키지 목록
├── venv/                           # Python 가상환경
├── static/                         # 정적 파일 (CSS, JS)
├── templates/                      # HTML 템플릿
├── systemd/                        # systemd 서비스 파일
│   ├── pharmq-vnc-app.service
│   ├── pharmq-websockify-vnc1.service
│   └── pharmq-websockify-vnc2.service
└── scripts/
    ├── check-status.sh            # 상태 확인 스크립트
    └── restart-all.sh             # 전체 재시작 스크립트
```

## 🔗 관련 문서

- **pharmq-novnc 리포지토리**: https://git.0bin.in/thug0bin/pharmq-novnc
- **Gateway 통합 문서**: /srv/docs/VNCoverVPN.md
- **Frontend 통합 가이드**: pharmq_on CloudBillingService 컴포넌트

## 📞 지원

설치 중 문제 발생 시:

1. 스크립트 로그 저장:
   ```bash
   script /tmp/install-log.txt
   curl -fsSL https://git.0bin.in/.../pharmq-novnc-setup.sh | bash
   exit
   ```

2. 서비스 로그 수집:
   ```bash
   journalctl -u pharmq-vnc-app.service -n 100 > /tmp/vnc-app.log
   journalctl -u pharmq-websockify-vnc1.service -n 100 > /tmp/vnc1.log
   ```

3. PharmQ 개발팀에 문의

## 🎯 setupScripts.ts 통합

프론트엔드 [setupScripts.ts](pharmq_on/src/constants/setupScripts.ts)에 추가:

```typescript
{
  id: 'pharmq-novnc-setup',
  title: '5단계: PharmQ noVNC 설치',
  emoji: '🖥️',
  description: 'VM VNC 화면을 웹 브라우저로 제공 (대화형 설치)',
  command: 'curl -fsSL https://git.0bin.in/thug0bin/pve9-repo-fix/raw/branch/main/VNC/pharmq-novnc-setup.sh | bash',
  category: 'core',
  step: 5,
  details: {
    prerequisite: '⚠️ 1단계(Repository Fix) + 2단계(VPN 등록) 완료 필수',
    problemDescription: [
      'VM VNC 화면에 직접 접근하기 어려움',
      '중앙 관리자가 약국 PC 화면을 원격으로 확인 필요',
      'VNC 프로토콜을 웹 브라우저에서 사용 불가'
    ],
    features: [
      'VM 자동 감지 및 선택',
      'noVNC over WebSocket 설치',
      'Proxmox API 통합 (마우스 리셋)',
      'systemd 서비스 자동 등록',
      '방화벽 설정 (Tailscale VPN 전용)',
      'Gateway 연동 (https://gateway.pharmq.kr)'
    ],
    verification: [
      '설치 완료 후 표시되는 URL 확인',
      'curl http://localhost:6000/health',
      'https://gateway.pharmq.kr/api/novnc/P0014/vnc1 접속'
    ],
    warnings: [
      '1단계 + 2단계 완료 후 실행',
      'Proxmox VE 환경 필수',
      'Root 권한 필요',
      '실행 중인 VM이 있어야 함'
    ]
  }
}
```

---

**버전**: 1.0
**작성일**: 2025-11-21
**작성자**: PharmQ Development Team