headscale-tailscale-replacement/FARMQ_HEADPLANE_CUSTOMIZATION_PLAN.md

🏥 팜큐(FARMQ) Headplane 커스터마이징 기획서

📋 프로젝트 개요

회사 현황

• 회사명: 팜큐(FARMQ)
• 사업 규모: 약국 100개소
• 인프라: 각 약국마다 Proxmox 호스트 PC 납품
• 관리 대상: 약국별 VM 환경 원격 관리
• 네트워크: WireGuard 기반 Headscale + Headplane 전환 완료

현재 환경

• ✅ Headscale 서버: http://192.168.0.151:8070 (정상 운영)
• ✅ Headplane UI: http://192.168.0.151:3000/admin/ (정상 운영)
• ✅ VPN 네트워크: 100.64.0.0/10 대역 할당
• ✅ 기본 기능: Machine/User 관리 가능

개선 목표

현재 기본 Headplane UI를 팜큐 전용 약국 관리 시스템으로 확장

🎯 요구사항 분석

1. 데이터 확장 요구사항

현재 User 테이블 구조

User    | Role      | Created At  | Last Seen
myuser  | Unmanaged | 2025.9.9    | Connected

확장 요구사항

User     | 약국명    | 사업자번호     | Role      | Created At  | Last Seen
myuser   | 서울약국   | 123-45-67890  | Unmanaged | 2025.9.9    | Connected

Machine 정보 확장 요구사항

• 현재: Machine 이름만 관리
• 확장 후:
  • 약국명 연동
  • PC 사양 정보 (CPU, RAM, Storage)
  • Proxmox 호스트 정보
  • 실시간 하드웨어 모니터링

2. 모니터링 요구사항

• Proxmox API 연동: CPU 온도, 사용률, VM 상태
• 실시간 대시보드: 약국별 시스템 현황
• 알림 시스템: 장애 발생 시 실시간 알림

🏗️ 아키텍처 설계

시스템 구조

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Headplane UI  │───►│  Custom Backend  │───►│  Proxmox Hosts  │
│  (Frontend)     │    │   (API Server)   │    │  (100개 약국)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │                       ▼                       │
         │              ┌──────────────────┐             │
         └─────────────►│   Headscale DB   │◄────────────┘
                        │   (Extended)     │
                        └──────────────────┘

데이터베이스 확장 설계

새로운 테이블: pharmacy_info

CREATE TABLE pharmacy_info (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(255) UNIQUE REFERENCES users(name),
    pharmacy_name VARCHAR(255) NOT NULL,
    business_number VARCHAR(20),
    address TEXT,
    phone VARCHAR(20),
    manager_name VARCHAR(100),
    proxmox_host VARCHAR(255),
    proxmox_api_token TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

새로운 테이블: machine_specs

CREATE TABLE machine_specs (
    id SERIAL PRIMARY KEY,
    machine_id BIGINT REFERENCES machines(id),
    pharmacy_id INTEGER REFERENCES pharmacy_info(id),
    cpu_model VARCHAR(255),
    cpu_cores INTEGER,
    ram_gb INTEGER,
    storage_gb INTEGER,
    gpu_model VARCHAR(255),
    last_updated TIMESTAMP DEFAULT NOW()
);

새로운 테이블: monitoring_data

CREATE TABLE monitoring_data (
    id SERIAL PRIMARY KEY,
    machine_id BIGINT REFERENCES machines(id),
    cpu_usage DECIMAL(5,2),
    memory_usage DECIMAL(5,2),
    disk_usage DECIMAL(5,2),
    cpu_temperature INTEGER,
    network_rx_bytes BIGINT,
    network_tx_bytes BIGINT,
    vm_count INTEGER,
    vm_running INTEGER,
    collected_at TIMESTAMP DEFAULT NOW()
);

🛠️ 구현 방안

방안 1: Headplane 포크 + 직접 수정 (권장)

장점: 완전한 커스터마이징 가능
단점: 업스트림 업데이트 반영 어려움
개발 기간: 2-3주

구현 단계:

1. 포크 및 개발환경 구성
2. 데이터베이스 스키마 확장
3. API 엔드포인트 추가
4. UI 컴포넌트 커스터마이징
5. Proxmox API 연동 모듈 개발
6. 모니터링 대시보드 구현

방안 2: 별도 관리 시스템 + Headplane 연동

장점: 기존 Headplane 유지, 독립적 개발
단점: 시스템 분리로 복잡도 증가
개발 기간: 3-4주

방안 3: Headplane 플러그인 시스템 구축

장점: 모듈러 구조, 확장성 좋음
단점: 플러그인 시스템 자체 개발 필요
개발 기간: 4-5주

📋 세부 기능 명세

1. 약국 정보 관리

1-1. 약국 등록/수정 화면

┌─────────────────────────────────────┐
│ 약국 정보 등록                       │
├─────────────────────────────────────┤
│ 약국명: [서울중앙약국           ]    │
│ 사업자번호: [123-45-67890       ]   │
│ 주소: [서울시 강남구...        ]    │
│ 전화번호: [02-1234-5678        ]    │
│ 담당자: [홍길동               ]     │
│ Proxmox 호스트: [192.168.1.100 ]   │
│ API 토큰: [********************]   │
│                                     │
│ [저장] [취소]                       │
└─────────────────────────────────────┘

1-2. 사용자 테이블 확장

User     | 약국명      | 사업자번호     | 전화번호      | Role      | Last Seen
pharmacy1| 서울중앙약국 | 123-45-67890  | 02-1234-5678 | Active    | 5분 전
pharmacy2| 부산해운약국 | 987-65-43210  | 051-9876-5432| Active    | 1시간 전

2. 머신 정보 확장

2-1. 머신 상세 정보 화면

┌─────────────────────────────────────┐
│ 머신 상세 정보: pharmacy1-main       │
├─────────────────────────────────────┤
│ 약국명: 서울중앙약국                 │
│ IP 주소: 100.64.0.15               │
│ 마지막 접속: 2분 전                 │
│                                     │
│ 하드웨어 정보:                      │
│ CPU: Intel i7-12700 (12코어)       │
│ RAM: 32GB                          │
│ Storage: 1TB NVMe SSD              │
│                                     │
│ 실시간 모니터링:                    │
│ CPU 사용률: ████████░░ 80%         │
│ CPU 온도: 65°C                     │
│ 메모리 사용률: ██████░░░░ 60%      │
│ 디스크 사용률: ███░░░░░░░ 30%      │
│                                     │
│ VM 상태:                           │
│ 총 VM: 5개 | 실행중: 4개 | 정지: 1개│
└─────────────────────────────────────┘

3. 통합 대시보드

3-1. 메인 대시보드 레이아웃

┌────────────────────────────────────────────────────────────┐
│ 팜큐 약국 관리 시스템                    [사용자: admin]   │
├────────────────────────────────────────────────────────────┤
│ 📊 전체 현황                                               │
│ ┌──────────┬──────────┬──────────┬──────────────────────┐  │
│ │총 약국 수 │온라인    │오프라인   │평균 CPU 온도         │  │
│ │   100    │   95     │    5     │       62°C           │  │
│ └──────────┴──────────┴──────────┴──────────────────────┘  │
│                                                            │
│ 🚨 알림                                                    │
│ • 부산해운약국: CPU 온도 85°C (경고)                      │
│ • 대구중앙약국: 디스크 사용률 95% (위험)                  │
│                                                            │
│ 📈 약국별 상태                                             │
│ ┌─────────────┬────────┬────────┬────────┬──────────────┐ │
│ │약국명        │상태    │CPU온도  │메모리   │마지막 접속    │ │
│ ├─────────────┼────────┼────────┼────────┼──────────────┤ │
│ │서울중앙약국   │🟢 온라인│  65°C  │  80%   │    2분 전    │ │
│ │부산해운약국   │🟡 경고  │  85°C  │  60%   │    5분 전    │ │
│ │대구중앙약국   │🔴 위험  │  70°C  │  95%   │   10분 전    │ │
│ └─────────────┴────────┴────────┴────────┴──────────────┘ │
└────────────────────────────────────────────────────────────┘

4. Proxmox API 연동

4-1. 데이터 수집 프로세스

# proxmox_monitor.py
class ProxmoxMonitor:
    def collect_host_info(self, proxmox_host, api_token):
        """Proxmox 호스트 정보 수집"""
        # CPU 온도, 사용률
        # 메모리 사용률
        # 디스크 사용률
        # VM 상태 및 개수
        # 네트워크 트래픽
        
    def collect_vm_info(self, proxmox_host, vm_id):
        """개별 VM 정보 수집"""
        # VM 상태 (running, stopped)
        # 리소스 할당량
        # 실제 리소스 사용량

🔧 기술 스택

Frontend (Headplane 기반)

• React 19.1.0 + TypeScript
• Tailwind CSS (스타일링)
• React Router (라우팅)
• Chart.js (모니터링 차트)
• Socket.io Client (실시간 업데이트)

Backend (확장 API 서버)

• Node.js + Express.js 또는 Python FastAPI
• PostgreSQL (확장된 데이터베이스)
• Socket.io (실시간 통신)
• Proxmox API Client
• Cron Jobs (주기적 데이터 수집)

모니터링 스택

• Proxmox API (호스트 정보)
• Glances API (시스템 메트릭)
• InfluxDB (시계열 데이터 저장)
• Redis (캐싱 및 실시간 데이터)

📅 개발 로드맵

Phase 1: 기반 구축 (1주)

• Headplane 포크 및 개발환경 구성
• 데이터베이스 스키마 설계 및 확장
• 기본 약국 정보 CRUD API 구현
• UI 기본 레이아웃 수정

Phase 2: 핵심 기능 (2주)

• 사용자 테이블에 약국 정보 연동
• 머신 정보 확장 및 UI 개선
• Proxmox API 연동 모듈 개발
• 기본 모니터링 대시보드 구현

Phase 3: 고도화 (1주)

• 실시간 모니터링 구현
• 알림 시스템 구축
• 통합 대시보드 완성
• 성능 최적화 및 테스트

Phase 4: 배포 및 운영 (1주)

• 프로덕션 환경 배포
• 100개 약국 데이터 마이그레이션
• 운영 매뉴얼 작성
• 사용자 교육 및 피드백 수집

💰 예상 비용 및 리소스

개발 리소스

• 개발 기간: 4-5주
• 개발자: 풀스택 개발자 1명
• 디자이너: UI/UX 디자이너 0.5명

인프라 비용

• 확장 서버: 추가 서버 인스턴스 (모니터링 데이터 처리)
• 데이터베이스: PostgreSQL + InfluxDB
• 스토리지: 시계열 데이터 저장용

🚀 시작하기

1단계: 요구사항 확정

• 약국 정보 필드 최종 확정
• 모니터링 지표 우선순위 결정
• UI/UX 디자인 컨셉 결정

2단계: 개발환경 구성

• Headplane 포크 및 클론
• 로컬 개발환경 세팅
• 테스트용 Proxmox 호스트 준비

3단계: 프로토타입 개발

• 약국 정보 등록 화면 구현
• 기본 모니터링 기능 구현
• 초기 버전 데모

📊 성공 지표

기능적 지표

• 100개 약국 정보 완전 등록
• 실시간 모니터링 정확도 95% 이상
• 알림 반응 시간 1분 이내
• 시스템 가용성 99.5% 이상

사용성 지표

• 관리자 업무 효율 50% 향상
• 장애 발견 시간 80% 단축
• 사용자 만족도 4.5/5.0 이상

📝 체크리스트

즉시 검토 필요사항

• 현재 Headscale DB 구조 분석
• Proxmox API 접근 권한 확인
• 약국별 네트워크 접근성 테스트
• 추가 하드웨어 리소스 요구사항 검토

장기적 고려사항

• 확장성: 약국 수 증가 대비
• 보안: 약국 데이터 보호
• 백업: 중요 데이터 백업 전략
• 업데이트: 원활한 시스템 업데이트 방안

---

📅 작성일: 2025-09-09
👤 작성자: Claude Code Assistant
🏢 대상: 팜큐(FARMQ) - 약국 IT 인프라 관리 시스템