History

Claude aede1e9197 Fix Korean character encoding in config parsing UTF-8 인코딩 명시적 지정: - open() 함수에 encoding='utf-8' 추가 - 약국 이름이 잘리는 문제 해결 (예: 태령약 → 태령약국) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>		2025-11-21 14:02:42 +00:00
..
pharmq-novnc-setup.sh	Fix Korean character encoding in config parsing	2025-11-21 14:02:42 +00:00
README.md	Add PharmQ noVNC auto-installation script	2025-11-21 11:17:16 +00:00

README.md

PharmQ noVNC 자동 설치 스크립트

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

📦 개요

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

주요 기능:

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

🚀 빠른 설치

원클릭 설치 (curl)

curl -fsSL https://git.0bin.in/thug0bin/pve9-repo-fix/raw/branch/main/VNC/pharmq-novnc-setup.sh | 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단계: 스크립트 실행

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

🔧 설치 후 확인

서비스 상태 확인

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

포트 리스닝 확인

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

헬스체크

curl http://localhost:6000/health

정상 응답 예시:

{
  "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 접속은 영향 없음

수동 방화벽 설정

# 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

🔄 재설치 및 업데이트

재설치

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

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]:

서비스 재시작

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

설정 파일 수동 편집

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

📊 관리 명령어

상태 확인

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

로그 확인

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

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

서비스 중지

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

서비스 비활성화

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

🐛 트러블슈팅

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

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

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

문제: VNC 화면이 검은색

# 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 에러

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

# Tailscale 연결 확인
tailscale status

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

문제: 포트 충돌

# 포트 사용 중인 프로세스 확인
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 컴포넌트

📞 지원

설치 중 문제 발생 시:

스크립트 로그 저장:

script /tmp/install-log.txt
curl -fsSL https://git.0bin.in/.../pharmq-novnc-setup.sh | bash
exit

서비스 로그 수집:

journalctl -u pharmq-vnc-app.service -n 100 > /tmp/vnc-app.log
journalctl -u pharmq-websockify-vnc1.service -n 100 > /tmp/vnc1.log

PharmQ 개발팀에 문의

🎯 setupScripts.ts 통합

프론트엔드 setupScripts.ts에 추가:

{
  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