Files

thug0bin c42d1b70ea Add troubleshooting docs: Caddy+Headscale proxy, NAT hairpinning, ODBC conflict

- caddy-headscale-proxy.md: HTTP redirect + HTTP/2 Upgrade header conflict fix
- nat-hairpinning.md: Same-LAN public IP access issue and auto-detection
- odbc-freetds-conflict.md: FreeTDS vs ODBC Driver 18 for MSSQL named instances
- README.md: Install script commands (individual + unified) and doc index

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-06 15:37:16 +00:00

3.5 KiB

Raw Permalink Blame History

Caddy + Headscale 리버스 프록시 트러블슈팅

날짜: 2026-04-06 환경: Caddy v2.11.2, Headscale 0.26.1 (Docker), Tailscale 1.96.4

증상

외부 노드에서 tailscale up --login-server=http://head.pharmq.kr 실행 시 무한 대기 또는 실패.

PBS-LXC, 약국 PVE 등 외부 노드에서 Headscale 등록 불가
Headscale Docker 재시작 후 기존 노드 재연결 실패
Caddy 로그에 502 Bad Gateway 다수 발생

원인: 2가지 문제

문제 1: HTTP → HTTPS 강제 리다이렉트 (308)

Caddy 동작: TLS 설정이 있는 도메인은 자동으로 HTTP(80) → HTTPS(443) 308 리다이렉트 생성

# Tailscale 클라이언트 요청
POST http://head.pharmq.kr/ts2021

# Caddy 응답
HTTP/1.1 308 Permanent Redirect
Location: https://head.pharmq.kr/
Server: Caddy

왜 문제인가: Tailscale 클라이언트는 --login-server=http://...로 설정되면 HTTP를 기대함. HTTPS 리다이렉트를 자동으로 따라가지 못함.

해결: http:// 전용 블록을 별도로 추가

http://head.pharmq.kr {
    reverse_proxy 192.168.0.100:8070
}

문제 2: HTTP/2에서 Upgrade 헤더 호환 불가 (502)

Caddy 동작: HTTPS 연결에서 백엔드로 프록시할 때 HTTP/2를 사용

# Tailscale TS2021 프로토콜 요청
POST /ts2021 HTTP/1.1
Connection: upgrade
Upgrade: tailscale-control-protocol

# Caddy가 h2로 변환하여 백엔드에 전달 → 에러
http2: invalid Upgrade request header: ["tailscale-control-protocol"]
→ 502 Bad Gateway

왜 문제인가: HTTP/2 스펙(RFC 7540)에서 Connection과 Upgrade 헤더는 hop-by-hop이라 금지됨. Tailscale TS2021은 HTTP/1.1 Upgrade 메커니즘에 의존.

Caddy 로그 (실제):

{
  "level": "error",
  "msg": "http2: invalid Upgrade request header: [\"tailscale-control-protocol\"]",
  "request": {
    "method": "POST",
    "uri": "/ts2021",
    "headers": {
      "Connection": ["upgrade"],
      "Upgrade": ["tailscale-control-protocol"]
    }
  },
  "status": 502
}

해결: 백엔드 연결을 HTTP/1.1로 강제 + 스트리밍 즉시 전달

head.pharmq.kr {
    reverse_proxy 192.168.0.100:8070 {
        flush_interval -1
        transport http {
            versions 1.1
        }
    }
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
}

최종 Caddyfile 설정

# Headscale — HTTP (리다이렉트 없이 직접 프록시)
http://head.pharmq.kr {
    reverse_proxy 192.168.0.100:8070
}

# Headscale — HTTPS (HTTP/1.1 강제, TS2021 Upgrade 호환)
head.pharmq.kr {
    reverse_proxy 192.168.0.100:8070 {
        flush_interval -1
        transport http {
            versions 1.1
        }
    }

    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
}

검증 방법

# HTTP 프록시 확인 (리다이렉트 없어야 함)
curl -v http://head.pharmq.kr 2>&1 | grep -E "HTTP|Location|Server"
# 기대: HTTP/1.1 404 Not Found, Server 없거나 Via: 1.1 Caddy

# HTTPS 프록시 확인
curl -sk https://head.pharmq.kr/ts2021 2>&1 | head -5
# 502가 아니어야 함

# Tailscale 등록 테스트
tailscale up --login-server=http://head.pharmq.kr \
  --authkey=<KEY> --accept-routes --accept-dns=false

참고

Docker 포트 매핑: 호스트 8070 → 컨테이너 8080
Headscale config: listen_addr: 0.0.0.0:8080
같은 LAN에서는 NAT Hairpinning 문제로 http://192.168.0.100:8070 직접 사용 필요 (nat-hairpinning.md 참조)

3.5 KiB Raw Permalink Blame History