headscale-tailscale-replacement/FARMQ_ADMIN_MACHINE_NAME_FIX_PLAN.md

FarmQ Admin 머신 이름 표시 문제 해결 계획

📋 문제 상황

현재 FarmQ Admin의 머신 관리 페이지에서 머신 이름이 hostname으로만 표시되고 있어, Magic DNS에서 사용되는 실제 노드 이름(given_name)과 일치하지 않는 문제가 발생하고 있습니다.

🔍 문제 분석

1. 현재 상황

Headscale CLI API 실제 데이터:

{
  "id": 1,
  "name": "0bin-Ubuntu-VM",           // ❌ 실제 Magic DNS에서 사용되는 이름
  "given_name": "0bin-ubuntu-vm",     // ✅ Magic DNS 접두어 (pev.headscale.local)
  "ip_addresses": ["100.64.0.1"],
  "user": {"name": "myuser"},
  "online": true
}

FarmQ Admin 현재 표시:

<strong>{{ machine_data.machine_name or machine_data.hostname }}</strong>
<div class="small text-muted">{{ machine_data.hostname }}</div>

2. 문제의 근본 원인

A. 데이터베이스 스키마 불일치

Headscale 모델:

# models/headscale_models.py
class Node:
    hostname = Column(String)      # 시스템 호스트명 (0bin-Ubuntu-VM)
    given_name = Column(String)    # 사용자 지정 이름 (0bin-ubuntu-vm) - Magic DNS용

FarmQ 모델:

# models/farmq_models.py
class MachineProfile:
    hostname = Column(String)      # hostname으로 복사됨
    machine_name = Column(String)  # hostname으로 중복 저장됨 ❌

B. 동기화 로직 문제

# utils/database_new.py (line 343)
machine_data = {
    'hostname': node.hostname,          # "0bin-Ubuntu-VM"
    'machine_name': node.hostname,      # ❌ hostname 중복! given_name이어야 함
    'tailscale_ip': node.ipv4,
}

C. 템플릿 표시 문제

<!-- templates/machines/list.html (line 115) -->
<strong>{{ machine_data.machine_name or machine_data.hostname }}</strong>
<!-- 현재: "0bin-Ubuntu-VM" (hostname) -->
<!-- 원하는: "0bin-ubuntu-vm" (given_name) -->

✅ 해결 방안

1. 즉시 수정 (Quick Fix)

A. 데이터베이스 동기화 로직 수정

# farmq-admin/utils/database_new.py
def get_all_machines_with_details():
    machine_data = {
        'hostname': node.hostname,           # 시스템 호스트명
        'machine_name': node.given_name,     # ✅ Magic DNS 이름으로 변경
        'display_name': node.given_name or node.hostname,  # 표시용 이름
        'tailscale_ip': node.ipv4,
    }

B. FarmQ 모델 동기화 수정

# models/farmq_models.py - sync_machine_from_headscale
machine = MachineProfile(
    hostname=headscale_node_data.get('hostname'),
    machine_name=headscale_node_data.get('given_name'),  # ✅ given_name 사용
    tailscale_ip=headscale_node_data.get('ipv4'),
)

C. 템플릿 표시 개선

<!-- templates/machines/list.html -->
<strong>{{ machine_data.machine_name or machine_data.hostname }}</strong>
<div class="small text-muted">
    <i class="fas fa-network-wired"></i> {{ machine_data.machine_name }}.headscale.local
</div>
<div class="small text-muted">
    <i class="fas fa-server"></i> {{ machine_data.hostname }}
</div>

2. 근본적 개선 (Long-term)

A. 필드 명칭 명확화

class MachineProfile:
    system_hostname = Column(String)     # 시스템 호스트명 (0bin-Ubuntu-VM)
    headscale_name = Column(String)      # Headscale given_name (0bin-ubuntu-vm)
    magic_dns_name = Column(String)      # Magic DNS 전체 이름 (0bin-ubuntu-vm.headscale.local)
    display_name = Column(String)        # 사용자 표시용 이름

B. Magic DNS 정보 표시 강화

<div class="machine-info">
    <h5>{{ machine.display_name }}</h5>
    <div class="dns-info">
        <code>{{ machine.magic_dns_name }}</code>
        <button class="btn btn-sm" onclick="copyToClipboard('{{ machine.magic_dns_name }}')">
            <i class="fas fa-copy"></i>
        </button>
    </div>
    <div class="system-info small text-muted">
        시스템: {{ machine.system_hostname }}
    </div>
</div>

🚀 구현 단계

Phase 1: 긴급 수정 (1-2시간)

1. 데이터 동기화 로직 수정

   # 파일: farmq-admin/utils/database_new.py
   # 라인: 343
   'machine_name': node.given_name,  # hostname → given_name
   

2. 템플릿 표시 개선

   # 파일: farmq-admin/templates/machines/list.html
   # Magic DNS 정보 추가 표시
   

3. 동기화 함수 수정

   # 파일: farmq-admin/models/farmq_models.py
   # sync_machine_from_headscale 함수 수정
   

Phase 2: 표시 개선 (2-3시간)

1. Magic DNS 정보 강화 표시

   • .headscale.local 접미사 자동 표시
   • 클립보드 복사 기능
   • 연결 테스트 기능

2. 필터링 기능 추가

   • Magic DNS 이름으로 검색
   • 온라인/오프라인 필터
   • 사용자별 필터

Phase 3: 구조적 개선 (4-6시간)

1. 데이터베이스 스키마 개선

   • 필드명 명확화
   • Magic DNS 전용 필드 추가
   • 인덱스 최적화

2. API 통합 개선

   • Headscale CLI 응답 캐싱
   • 실시간 상태 업데이트
   • WebSocket을 통한 실시간 알림

📊 예상 결과

Before (현재)

머신 이름: 0bin-Ubuntu-VM        # hostname (시스템명)
호스트명: 0bin-Ubuntu-VM         # 중복 정보
Magic DNS: 사용불가 ❌           # given_name 정보 부족

After (수정 후)

머신 이름: 0bin-ubuntu-vm        # given_name (Magic DNS용)
Magic DNS: 0bin-ubuntu-vm.headscale.local ✅
시스템명: 0bin-Ubuntu-VM         # hostname (참고 정보)
IP 주소: 100.64.0.1             # 현재와 동일

🧪 테스트 계획

1. 데이터 검증

# 테스트 스크립트
def test_machine_name_mapping():
    nodes = headscale_session.query(Node).all()
    for node in nodes:
        print(f"ID: {node.id}")
        print(f"Hostname: {node.hostname}")      # 0bin-Ubuntu-VM
        print(f"Given Name: {node.given_name}")  # 0bin-ubuntu-vm
        print(f"Magic DNS: {node.given_name}.headscale.local")
        print("---")

2. Magic DNS 연결 테스트

# 각 노드별 Magic DNS 테스트
ping 0bin-ubuntu-vm.headscale.local
ping pev.headscale.local
ping pqserver.headscale.local

3. UI 표시 확인

• 머신 목록에서 올바른 이름 표시
• Magic DNS 주소 복사 기능
• 연결 상태와 일치성 확인

📝 체크리스트

코드 수정

• farmq-admin/utils/database_new.py - 동기화 로직 수정
• farmq-admin/models/farmq_models.py - 모델 동기화 수정
• farmq-admin/templates/machines/list.html - 표시 개선
• farmq-admin/templates/machines/detail.html - 상세 페이지 수정

테스트

• 데이터베이스 동기화 테스트
• Magic DNS 이름 표시 확인
• UI 표시 정상성 확인
• 기존 기능 호환성 테스트

문서화

• 변경사항 README 업데이트
• API 문서 갱신
• 사용자 가이드 수정

🔧 구현 파일 목록

수정할 파일들

1. farmq-admin/utils/database_new.py (라인 343)

   • machine_name 필드를 given_name으로 변경

2. farmq-admin/models/farmq_models.py (라인 445)

   • 동기화 시 given_name 사용

3. farmq-admin/templates/machines/list.html (라인 115-119)

   • Magic DNS 정보 추가 표시

4. farmq-admin/templates/machines/detail.html

   • 상세 페이지 Magic DNS 정보 개선

새로 추가할 기능

• Magic DNS 주소 클립보드 복사
• 연결 테스트 버튼
• 실시간 온라인 상태 표시

💡 장기적 개선사항

1. Headscale API 직접 통합

현재 CLI 기반 → REST API 직접 호출로 전환하여 성능 개선

2. 실시간 모니터링

WebSocket을 통한 실시간 노드 상태 업데이트

3. Magic DNS 관리 기능

• 노드 이름 변경
• Magic DNS 도메인 설정
• DNS 해석 테스트 도구

📅 구현 일정

단계	작업	소요시간	완료일
Phase 1	긴급 수정	2시간	당일
Phase 2	표시 개선	3시간	1일
Phase 3	구조 개선	6시간	2-3일

---

작성일: 2025년 9월 13일 업데이트: FarmQ Admin 머신 이름 표시 문제 분석 및 해결 계획 수립 완료