thug0bin/headscale-tailscale-replacement
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7aa08682b8
headscale-tailscale-replace.../FARMQ_HEADPLANE_CUSTOMIZATION_PLAN.md
시골약사 247b9dbee7 🏥 Add FARMQ Headplane customization business plan 
Comprehensive business plan for customizing Headplane for FARMQ:
- Company overview: 100 pharmacies with Proxmox infrastructure
- Current system analysis: Working Headscale + Headplane setup
- Enhancement requirements: Pharmacy info, machine specs, monitoring
- Database schema design: pharmacy_info, machine_specs, monitoring_data
- Implementation approaches: Fork vs separate system vs plugin
- Technical specifications: React frontend + API backend + Proxmox integration
- Development roadmap: 4-5 weeks phased implementation
- Success metrics and cost analysis

Ready for pharmacy management system development based on existing Headplane.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-09 15:34:12 +09:00

349 lines
14 KiB
Markdown
Raw Blame History

# 🏥 팜큐(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`
```sql
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`
```sql
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`
```sql
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. 데이터 수집 프로세스
```python
# 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 인프라 관리 시스템
Reference in New Issue View Git Blame Copy Permalink