headscale-tailscale-replacement/QUICK_INSTALL_GUIDE.md

🚀 팜큐 Headscale 원클릭 설치 가이드

새로운 리눅스 서버를 팜큐 네트워크에 한 번의 명령으로 등록하는 방법입니다.

🎯 원클릭 설치 명령어

방법 1: curl 사용 (권장)

curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | sudo bash

방법 2: wget 사용

wget -qO- https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | sudo bash

방법 3: 스크립트 다운로드 후 실행

wget https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh
chmod +x quick-install.sh
sudo ./quick-install.sh

✨ 자동으로 수행되는 작업

1. 🔍 시스템 분석

• 운영체제 자동 감지 (Ubuntu, Debian, CentOS, RHEL, Rocky, Fedora, Arch)
• 시스템 요구사항 확인
• 네트워크 연결 상태 점검

2. 📦 Tailscale 설치

• Ubuntu/Debian: APT 리포지토리 추가 및 설치
• CentOS/RHEL/Rocky: YUM/DNF 리포지토리 추가 및 설치
• Fedora: DNF 패키지 관리자로 설치
• Arch Linux: Pacman으로 설치
• 기타 배포판: Universal Binary 직접 다운로드

3. 🔧 서비스 설정

• systemd 서비스 자동 등록
• tailscaled 데몬 시작 및 활성화
• 서비스 상태 확인 및 오류 처리

4. 🌐 Headscale 등록

• Pre-auth Key를 사용한 자동 등록
• 팜큐 Headscale 서버 (https://head.0bin.in)에 연결
• DNS 및 라우팅 설정 자동 적용

5. 🔒 방화벽 설정

• UFW (Ubuntu/Debian) 자동 설정
• firewalld (CentOS/RHEL/Fedora) 자동 설정
• Tailscale 포트 (41641/UDP) 자동 허용

6. ✅ 연결 검증

• IP 주소 할당 확인
• 네트워크 연결 테스트
• 다른 노드와의 통신 확인

🖥️ 지원하는 운영체제

OS	버전	설치 방법	상태
Ubuntu	18.04+	APT Repository	✅
Debian	10+	APT Repository	✅
CentOS	7, 8, 9	YUM/DNF Repository	✅
RHEL	7, 8, 9	YUM/DNF Repository	✅
Rocky Linux	8, 9	DNF Repository	✅
AlmaLinux	8, 9	DNF Repository	✅
Fedora	35+	DNF Package	✅
Arch Linux	Rolling	Pacman Package	✅
기타 배포판	-	Universal Binary	⚠️

📋 설치 예시 출력

$ curl -fsSL https://git.0bin.in/.../quick-install.sh | sudo bash

============================================
팜큐(FARMQ) Headscale 원클릭 설치
============================================

📋 감지된 OS: ubuntu 22.04 (jammy)

🔧 시스템 요구사항 확인 중...
✅ 시스템 요구사항 확인 완료

🔧 Tailscale 클라이언트 설치 중...
📋 Ubuntu/Debian용 Tailscale 설치 중...
✅ Tailscale 설치 완료
📋 설치된 버전: 1.52.1

🔧 Tailscale 서비스 시작 중...
✅ Tailscaled 서비스가 실행 중입니다.

🔧 Headscale 서버에 등록 중...
📋 Headscale 서버: https://head.0bin.in
📋 Pre-auth Key: 8b3df41d***************
🔧 등록 명령 실행 중...
✅ Headscale 등록 성공!

🔧 방화벽 설정 확인 중...
📋 UFW 방화벽 감지됨
📋 Tailscale 트래픽 허용 중...
✅ 방화벽 설정 완료

🔧 연결 상태 확인 중...
✅ Headscale 네트워크 연결 완료!
📋 할당된 IPv4: 100.64.0.5
📋 할당된 IPv6: fd7a:115c:a1e0::5

🔧 네트워크 연결 테스트 중...
✅ 팜큐 네트워크(100.64.0.0/10) 연결 정상!

============================================
팜큐 Headscale 설치 완료!
============================================

🎉 설치가 성공적으로 완료되었습니다!

📋 시스템 정보:
   호스트명: pharmacy-server-01
   Tailscale IP: 100.64.0.5
   OS: ubuntu 22.04
   Headscale 서버: https://head.0bin.in

🔧 유용한 명령어:
   tailscale status       # 연결 상태 확인
   tailscale ip          # 할당된 IP 확인
   tailscale ping <node> # 다른 노드와 연결 테스트
   tailscale logout      # 네트워크에서 해제

🌐 팜큐 관리자 페이지:
   http://192.168.0.151:5002
   http://192.168.0.151:5002/vms (VM 관리)

============================================
설치 완료 - 팜큐 네트워크를 사용할 수 있습니다!
============================================

🔧 설치 후 확인 명령어

연결 상태 확인

tailscale status

할당된 IP 주소 확인

tailscale ip

네트워크 테스트

# 다른 노드로 ping 테스트
tailscale ping 100.64.0.1

# 또는 노드명으로 테스트
tailscale ping desktop-emjd1dc

서비스 상태 확인

systemctl status tailscaled
journalctl -u tailscaled -f  # 실시간 로그

🚨 문제해결

1. 설치 중 권한 오류

# 해결방법: sudo 권한으로 실행
sudo curl -fsSL https://git.0bin.in/.../quick-install.sh | sudo bash

2. 네트워크 연결 실패

# 방화벽 상태 확인
sudo ufw status
sudo firewall-cmd --list-all

# 수동 포트 허용
sudo ufw allow 41641/udp
sudo firewall-cmd --add-port=41641/udp --permanent

3. Pre-auth Key 만료

# 새로운 키 생성이 필요한 경우
# Headscale 서버에서 실행:
docker exec headscale headscale preauthkeys create --user 1 --expiration 7d --reusable

4. 수동 등록 필요시

# 자동 등록 실패 시 수동 실행
tailscale up --login-server="https://head.0bin.in" --authkey="YOUR_KEY_HERE"

📊 현재 네트워크 정보

• Headscale 서버: https://head.0bin.in
• Flask 관리 페이지: http://192.168.0.151:5002
• 네트워크 대역: 100.64.0.0/10
• Pre-auth Key 유효기간: 7일 (재사용 가능)

🔄 기존 서버 업데이트

이미 등록된 서버에서 스크립트를 다시 실행하면:

1. 기존 연결 감지
2. 사용자 확인 후 재등록 옵션 제공
3. 또는 기존 연결 유지

📞 지원

문제가 발생하면 다음 정보와 함께 연락주세요:

1. OS 정보: cat /etc/os-release
2. Tailscale 버전: tailscale version
3. 오류 로그: journalctl -u tailscaled --no-pager
4. 네트워크 상태: tailscale status

---

🎯 목표: 새로운 서버를 30초 만에 팜큐 네트워크에 연결!