headscale-tailscale-replacement/HEADSCALE_COMPLETE_GUIDE.md

🌐 FARMQ Headscale 완전 가이드

📚 목차

1. 개념 정리
2. 아키텍처 개요
3. 포트 구성
4. 설치 및 구성
5. 클라이언트 연결 워크플로우
6. 실제 사용 시나리오
7. 문제 해결

---

🧠 개념 정리

Tailscale vs Headscale vs Headplane

1. Tailscale (원본 서비스)

• 정의: 상용 VPN 서비스 (SaaS)
• 특징:
  • 클라우드 기반 coordination server 사용
  • 구독 기반 유료 서비스
  • 자동화된 관리
• 단점:
  • 데이터가 외부 서버를 거침
  • 비용 발생
  • 프라이버시 우려

2. Headscale (오픈소스 서버)

• 정의: Tailscale의 coordination server를 대체하는 오픈소스 구현
• 특징:
  • 자체 호스팅 가능
  • 완전한 프라이버시 제어
  • 무료 사용
  • REST API 제공
• 역할:
  • 클라이언트 인증 및 등록
  • IP 주소 할당
  • 라우팅 테이블 관리
  • 키 교환 coordination

3. Headplane (웹 UI)

• 정의: Headscale을 관리하기 위한 웹 인터페이스
• 특징:
  • 브라우저에서 노드 관리
  • 시각적 네트워크 상태 확인
  • 사용자 및 키 관리

4. 클라이언트 (Tailscale 클라이언트)

• 정의: 실제 VPN 연결을 담당하는 클라이언트 프로그램
• 중요: Tailscale의 클라이언트 소프트웨어를 그대로 사용
• 변경점: 서버 주소만 Headscale 서버로 지정

---

🏗️ 아키텍처 개요

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   클라이언트 PC    │    │   Headscale     │    │   클라이언트 PC    │
│                │    │   서버           │    │                │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ Tailscale   │◄────┼─┤ Headscale   │─┼────┤ │ Tailscale   │ │
│ │ Client      │ │    │ │ Server      │ │    │ │ Client      │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│                │    │ ┌─────────────┐ │    │                │
│                │    │ │ Headplane   │ │    │                │
│                │    │ │ Web UI      │ │    │                │
│                │    │ └─────────────┘ │    │                │
└─────────────────┘    └─────────────────┘    └─────────────────┘
       │                        │                        │
       └────────────────────────┼────────────────────────┘
                              │
                    ┌─────────────────┐
                    │  FARMQ Flask    │
                    │  Admin Panel    │
                    └─────────────────┘

데이터 흐름

1. 등록: 클라이언트 → Headscale 서버 (인증)
2. 키 교환: Headscale 서버 → 클라이언트들 (P2P 키 정보)
3. 실제 통신: 클라이언트 ↔ 클라이언트 (직접 P2P)
4. 관리: Headplane/Flask UI → Headscale API

---

🔌 포트 구성

현재 FARMQ 설정

서비스	포트	프로토콜	용도	접근
Headscale Server	8070	HTTP	클라이언트 등록/관리	클라이언트 ← → 서버
Headplane UI	3000	HTTP	웹 관리 인터페이스	관리자 → 웹브라우저
FARMQ Admin	5001	HTTP	한국어 관리 페이지	관리자 → 웹브라우저

중요한 포인트

• 클라이언트가 사용하는 포트: 8070 (Headscale 서버)
• 관리자가 사용하는 포트: 3000 (Headplane), 5001 (FARMQ Admin)
• 내부 컨테이너 포트: 8080 (Docker 내부에서만 사용)

---

🛠️ 설치 및 구성

1. 서버 구성 (이미 완료)

# 서버 시작
cd /srv/headscale-setup
docker-compose up -d

# 서비스 확인
docker-compose ps

2. 클라이언트 설치 과정

Step 1: Tailscale 클라이언트 설치

# Ubuntu/Debian
curl -fsSL https://tailscale.com/install.sh | sh

# 또는 수동 설치
curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/$(lsb_release -cs).noarmor.gpg | sudo tee /usr/share/keyrings/tailscale-archive-keyring.gpg >/dev/null
curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/$(lsb_release -cs).tailscale-keyring.list | sudo tee /etc/apt/sources.list.d/tailscale.list
sudo apt update
sudo apt install tailscale

Step 2: Headscale 서버에 등록

# 기본 명령어 형식
sudo tailscale up --login-server=http://[서버IP]:8070 --authkey=[PreAuth키]

# FARMQ 실제 명령어 예시
sudo tailscale up \
    --login-server=http://192.168.0.151:8070 \
    --authkey=YOUR_PREAUTH_KEY_HERE \
    --hostname=pharmacy-busan-pc1 \
    --accept-dns=false

---

🔄 클라이언트 연결 워크플로우

전체 프로세스

sequenceDiagram
    participant Admin as 관리자
    participant Server as Headscale 서버
    participant Client as 클라이언트 PC
    participant Network as VPN 네트워크

    Admin->>Server: 1. 사용자 생성
    Admin->>Server: 2. PreAuth 키 생성
    Admin->>Client: 3. PreAuth 키 전달
    Client->>Client: 4. Tailscale 클라이언트 설치
    Client->>Server: 5. 등록 요청 (PreAuth 키 포함)
    Server->>Client: 6. 인증 완료 및 설정 전달
    Client->>Network: 7. VPN 네트워크 참여
    Network->>Client: 8. 다른 노드들과 P2P 연결

상세 단계별 설명

1. 서버 측 작업 (관리자)

# 1-1. 사용자 생성 (한 번만)
docker exec headscale headscale users create pharmacy-busan

# 1-2. 사용자 목록 확인
docker exec headscale headscale users list

# 1-3. PreAuth 키 생성
docker exec headscale headscale preauthkeys create --user 1 --expiration 1h

# 출력 예시:
# f8d9c7e4b2a6c8f4d9e7b3a5c8f4d9e7b3a5c8f4d9e7b3a5c8f4d9e7b3a5c8f4

2. 클라이언트 측 작업

# 2-1. 기존 연결 해제 (있다면)
sudo tailscale logout
sudo tailscale down

# 2-2. Headscale 서버에 등록
sudo tailscale up \
    --login-server=http://192.168.0.151:8070 \
    --authkey=f8d9c7e4b2a6c8f4d9e7b3a5c8f4d9e7b3a5c8f4d9e7b3a5c8f4d9e7b3a5c8f4 \
    --hostname=pharmacy-busan-pc1 \
    --accept-dns=false

# 2-3. 연결 상태 확인
tailscale status

# 2-4. IP 주소 확인
tailscale ip -4

3. 결과 확인

# 서버에서 노드 목록 확인
docker exec headscale headscale nodes list

# 웹 UI에서 확인
# - Headplane: http://192.168.0.151:3000
# - FARMQ Admin: http://192.168.0.151:5001

---

🏥 실제 사용 시나리오

시나리오 1: 새 약국 등록

# 서버 작업 (관리자)
docker exec headscale headscale users create pharmacy-seoul
docker exec headscale headscale preauthkeys create --user [USER_ID] --expiration 2h

# 클라이언트 작업 (약국 PC)
curl -O http://192.168.0.151:8000/add-client.sh
chmod +x add-client.sh
./add-client.sh pharmacy-seoul pos-terminal-1
# PreAuth 키 입력 시 위에서 생성한 키 사용

시나리오 2: 여러 PC가 있는 약국

# 같은 사용자로 여러 머신 등록 가능
sudo tailscale up --login-server=http://192.168.0.151:8070 --authkey=[KEY] --hostname=busan-pos1
sudo tailscale up --login-server=http://192.168.0.151:8070 --authkey=[KEY] --hostname=busan-pos2
sudo tailscale up --login-server=http://192.168.0.151:8070 --authkey=[KEY] --hostname=busan-office

시나리오 3: 임시 접속 (노트북)

# 짧은 만료시간으로 키 생성
docker exec headscale headscale preauthkeys create --user [USER_ID] --expiration 30m

# 노트북에서 임시 연결
sudo tailscale up --login-server=http://192.168.0.151:8070 --authkey=[TEMP_KEY] --hostname=manager-laptop

---

🔍 상태 확인 및 관리

명령어 모음

# === 서버 측 (Headscale) ===

# 사용자 관리
docker exec headscale headscale users list
docker exec headscale headscale users create [username]

# 노드 관리
docker exec headscale headscale nodes list
docker exec headscale headscale nodes expire [node_id]

# PreAuth 키 관리
docker exec headscale headscale preauthkeys list --user [user_id]
docker exec headscale headscale preauthkeys create --user [user_id] --expiration [time]

# === 클라이언트 측 (Tailscale) ===

# 상태 확인
tailscale status          # 네트워크 상태 및 연결된 노드들
tailscale ip             # 내 IP 주소들
tailscale netcheck      # 네트워크 연결성 테스트
tailscale ping [node]   # 특정 노드 ping

# 연결 관리
tailscale up            # 연결 시작
tailscale down          # 연결 중단
tailscale logout        # 로그아웃

# 로그 확인
sudo journalctl -u tailscaled -f

웹 UI 접근

# Headplane (기본 관리 UI)
http://192.168.0.151:3000
# API 키: 8qRr1IB.tV95CmA0fLaCiGGIgBfeoN9daHceFkzI

# FARMQ 관리자 페이지 (한국어)
http://192.168.0.151:5001

---

⚠️ 중요한 주의사항

1. 포트 혼동 방지

• 클라이언트 등록: 8070 포트 사용
• 웹 관리: 3000, 5001 포트 사용
• Docker 내부: 8080 포트 (외부에서 직접 접근 불가)

2. PreAuth 키 보안

• 키는 일회용 또는 제한된 횟수만 사용 가능
• 짧은 만료시간 설정 권장 (1h ~ 24h)
• 키 노출 시 즉시 새 키 생성

3. 네트워크 구성

• 모든 클라이언트는 100.64.0.0/10 대역 IP 할당
• 첫 번째 클라이언트: 100.64.0.1 (서버 역할도 함)
• 이후 클라이언트들: 100.64.0.2, 100.64.0.3, ...

4. 방화벽 설정

# 서버 측 방화벽 (필요시)
sudo ufw allow 8070/tcp    # Headscale
sudo ufw allow 3000/tcp    # Headplane
sudo ufw allow 5001/tcp    # FARMQ Admin

# 클라이언트 측 (Tailscale이 자동 처리)
sudo ufw allow in on tailscale0

---

🚨 문제 해결

일반적인 문제들

1. "connection refused" 오류

# 원인: 서버 포트 접근 불가
# 해결:
docker-compose ps                    # 서버 실행 확인
sudo ufw status                     # 방화벽 확인
ping 192.168.0.151                  # 서버 연결 확인

2. "invalid auth key" 오류

# 원인: PreAuth 키 만료 또는 잘못된 키
# 해결:
docker exec headscale headscale preauthkeys create --user [user_id] --expiration 1h

3. "user not found" 오류

# 원인: 존재하지 않는 사용자
# 해결:
docker exec headscale headscale users list     # 사용자 확인
docker exec headscale headscale users create [username]  # 사용자 생성

4. IP 할당되지 않음

# 진단:
tailscale status        # 연결 상태 확인
tailscale netcheck     # 네트워크 테스트
sudo journalctl -u tailscaled -f  # 로그 확인

# 해결:
sudo systemctl restart tailscaled  # 서비스 재시작

로그 위치

# Headscale 서버 로그
docker logs headscale

# Headplane 로그
docker logs headplane

# Tailscale 클라이언트 로그
sudo journalctl -u tailscaled -f

---

📋 체크리스트

서버 설치 완료 확인

• Docker 및 Docker Compose 설치됨
• Headscale 컨테이너 실행 중 (포트 8070)
• Headplane 컨테이너 실행 중 (포트 3000)
• FARMQ Admin 실행 중 (포트 5001)
• 방화벽에서 필요 포트 열림

클라이언트 연결 확인

• Tailscale 클라이언트 설치됨
• 서버에 사용자 생성됨
• PreAuth 키 생성됨 (유효한 만료시간)
• tailscale up 명령어 성공
• tailscale status에서 다른 노드들 보임
• VPN IP 주소 할당됨 (100.64.0.x)

네트워크 연결 확인

• 서버 ping 성공 (ping 100.64.0.1)
• 다른 클라이언트와 ping 성공
• 웹 UI 접근 가능

---

🎯 다음 단계

1. 자동화 스크립트 활용: add-client.sh, create-preauth-key.sh 사용
2. 모니터링 설정: FARMQ Admin에서 실시간 상태 확인
3. 백업 전략: Headscale 설정 및 데이터베이스 백업
4. 확장: 새로운 약국 및 지점 추가

---

🎊 이제 완전한 프라이빗 VPN 네트워크를 운영할 수 있습니다!