headscale-tailscale-replacement/TROUBLESHOOTING_DATABASE_FOREIGN_KEY.md

Headscale 데이터베이스 외래키 제약조건 문제 해결 기록

🔍 문제 상황

발생한 오류

backend error: handling register with auth key: registering node: failed register(save) node in the database: SQL logic error: foreign key mismatch - "pharmacy_info" referencing "users" (1)

증상

• Windows Tailscale 클라이언트 연결 시 Google SSO 로그인만 표시됨
• tailscale up --login-server 명령어 실행 시 위 오류 발생
• Headscale 컨테이너 로그에서 foreign key mismatch 오류 지속 발생

원인 분석

1. Flask Admin 앱 개발 과정에서 추가된 커스텀 테이블들이 Headscale 스키마와 충돌

   • pharmacy_info 테이블이 users 테이블을 참조하는 외래키 제약조건 설정
   • machine_specs, monitoring_data 테이블도 유사한 외래키 제약조건 존재

2. Headscale이 자체 사용자 관리 스키마를 가지고 있어 외부 테이블의 외래키 참조 거부

   • Headscale은 내부적으로 users, machines, nodes 등의 테이블을 관리
   • 외부에서 추가된 테이블이 이들을 참조할 때 스키마 불일치 발생

🛠️ 해결 과정

1단계: 문제 테이블 식별

# 문제가 되는 테이블들 확인
cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE '%pharmacy%'")
problem_tables = cursor.fetchall()
# 결과: ['pharmacy_info', 'machine_specs', 'monitoring_data']

2단계: 데이터베이스 정리 스크립트 실행

python3 clean-database.py

스크립트 수행 작업:

1. 백업 생성: db.sqlite.clean_backup.20250909_170759
2. 외래키 제약조건 비활성화: PRAGMA foreign_keys = OFF
3. 문제 테이블 제거:
   • DROP TABLE IF EXISTS pharmacy_info
   • DROP TABLE IF EXISTS machine_specs
   • DROP TABLE IF EXISTS monitoring_data
4. 변경사항 커밋 및 무결성 검사

3단계: Headscale 서비스 재시작

cd /srv/headscale-setup && docker-compose restart headscale

✅ 해결 결과

Before (문제 상황):

2025-09-09T17:07:02+09:00 FTL Migration failed: SQL logic error: foreign key mismatch - "pharmacy_info" referencing "users" (1)

After (해결 후):

2025-09-09T17:08:42+09:00 INF Using policy manager version: 2
2025-09-09T17:08:42+09:00 INF Starting Headscale commit=474ea236d0c6d393dbcf7baa98da240ad20c1b66 version=0.26.1
2025-09-09T17:08:46+09:00 INF node has connected, mapSession: 0xc000172600, chan: 0xc000286d90 node=DESKTOP-EMJD1DC node.id=2
2025-09-09T17:08:48+09:00 INF node has connected, mapSession: 0xc00021b680, chan: 0xc000251180 node=0bin-Ubuntu-VM node.id=1

성공 지표:

• ✅ Headscale 정상 시작
• ✅ Windows 클라이언트 (DESKTOP-EMJD1DC) 연결 성공
• ✅ Ubuntu VM 클라이언트 (0bin-Ubuntu-VM) 연결 유지
• ✅ Health check 통과: {"status":"pass"}

📚 교훈 및 베스트 프랙티스

1. Headscale과 커스텀 애플리케이션 분리 원칙

❌ 잘못된 접근: Headscale DB에 직접 외래키 제약조건으로 연결
✅ 올바른 접근: 별도 데이터베이스 또는 느슨한 결합 방식 사용

2. 외래키 제약조건 설계 시 고려사항

• Headscale 스키마 독립성 유지
• 별도 데이터베이스 사용 또는 ID 참조만 사용 (외래키 제약조건 없이)
• 마이그레이션 전 스키마 호환성 검증

3. 향후 개발 가이드라인

# 권장하지 않음
pharmacy_info = Table('pharmacy_info',
    Column('user_id', Integer, ForeignKey('users.id'))  # ❌
)

# 권장 방법
pharmacy_info = Table('pharmacy_info', 
    Column('headscale_user_id', Integer)  # ✅ 단순 참조, 제약조건 없음
)

4. 데이터베이스 백업 중요성

• 모든 스키마 변경 전 백업 생성 필수
• 백업 파일명에 타임스탬프 포함으로 버전 관리
• 롤백 절차 사전 준비

🔧 복구 방법 (필요시)

만약 문제가 재발하거나 백업에서 복원해야 할 경우:

# 백업에서 복원
cp /srv/headscale-setup/data/db.sqlite.clean_backup.20250909_170759 /srv/headscale-setup/data/db.sqlite

# 컨테이너 재시작  
cd /srv/headscale-setup && docker-compose restart headscale

📝 관련 파일들

• 해결 스크립트: /srv/headscale-setup/clean-database.py
• 백업 파일: /srv/headscale-setup/data/db.sqlite.clean_backup.20250909_170759
• Docker Compose: /srv/headscale-setup/docker-compose.yml
• 로그 위치: docker logs headscale

---

문제 해결일: 2025-09-09
해결 소요시간: ~30분
영향 범위: Windows/Ubuntu 클라이언트 연결 복구