TROUBLESHOOTING / CLOUDFLARE TUNNEL + DOCKER

Tunnel은 Healthy인데
앱은 502인가요?

Tunnel의 Healthy 상태는 cloudflared가 Cloudflare에 연결됐다는 뜻입니다. 설정된 로컬 서비스까지 연결된다는 보장은 아닙니다. 다음 점검은 Cloudflare DNS를 바꾸기 전에 cloudflared와 origin 사이에서 시작하세요.

먼저 응답을 구분하세요

Tunnel connector가 연결되지 않은 상태를 우선 의심합니다. cloudflared 프로세스와 Tunnel 연결 상태, 최근 로그를 확인하세요.

Connector는 Cloudflare에 연결됐지만, Tunnel route에 적힌 Service URL에 도달하지 못했을 수 있습니다. 프로토콜, 주소, 포트, 컨테이너 간 네트워크를 점검합니다.

요청이 Traefik까지 왔다면 Host 규칙, entrypoint, 라우터와 서비스 설정을 확인하세요. 404는 매칭되는 라우터가 없는 경우, 503은 라우터가 사용할 준비된 서버를 찾지 못한 경우일 수 있습니다.

잘못된 주소: cloudflared가 별도 컨테이너라면 그 컨테이너의 localhost는 cloudflared 자신입니다. 다른 컨테이너는 공유 Docker 네트워크에서 확인 가능한 서비스 이름과 포트를 써야 할 수 있습니다.
잘못된 포트: 호스트에 공개한 포트와 컨테이너 내부에서 앱이 듣는 포트는 다를 수 있습니다. 앱의 실제 listen 포트를 Compose 설정과 대조하세요.
공유되지 않은 네트워크: cloudflared, Traefik, 앱이 서로 다른 Docker 네트워크에 있으면 서비스 이름을 찾지 못하거나 연결할 수 없습니다.
HTTP/HTTPS 불일치: Tunnel의 Service URL 프로토콜이 origin이 제공하는 프로토콜과 맞는지 확인하세요. HTTPS origin이면 인증서 이름과 검증 설정도 따로 확인해야 합니다.

공개 hostname은 접근 제어가 아닙니다. 라우팅을 고치는 과정에서 관리자 화면, 데이터베이스, 내부 API를 공개하지 마세요. 필요한 인증 정책을 별도로 확인하세요.

아래 명령은 Compose 앱 상태와 마지막 로그 일부를 확인합니다. 서비스 이름은 실제 프로젝트 설정에 맞게 바꾸세요. 로그에 토큰, 쿠키, 내부 주소가 보이면 공유 전에 가리세요.

# 앱과 connector 상태 docker compose ps # 최근 로그만 확인; 비밀 값이 있으면 외부 공유 금지 docker compose logs --tail=60 cloudflared traefik app

로그에서 connection refused, 이름 해석 실패, 잘못된 프로토콜, 인증서 오류를 찾아 Service URL의 host·scheme·port와 비교합니다. 설정을 바꾸기 전에 현재 응답을 만든 계층부터 확인하세요.

한 번의 정상 응답은 그 시점의 경로를 확인한 것입니다. 지속적인 가용성을 보장하지는 않습니다.

공개 hostname과 화면에 표시된 오류만으로 먼저 범위를 확인할 수 있습니다. 진단은 앱 한 개와 hostname 한 개의 서면 점검입니다. 비밀번호, API 토큰, 개인 키는 보내지 마세요.