Cloudflare Tunnels 터널 연결이 안 되는 문제

2023년 그 장애 때 cloudflared 컨테이너가 계속 QUIC 연결 타임아웃을 뱉으면서 사이트가 내려갔습니다. HTTP/2로 지정하니 연결이 복구됐죠. 이 조치는 진단 방법으로 쓸 수 있지만, 그걸로 통신사가 UDP를 차단했다고 단정할 수는 없고, 현재 버전이 자동으로 폴백하지 않는다고 봐서도 안 됩니다.

로그가 말해주는 것

당시 핵심 오류는 이랬습니다.

TEXT

Failed to create new quic connection
failed to dial to edge with quic: timeout: no recent network activity

이건 이번 QUIC 연결이 성공하지 못했다는 뜻일 뿐, 이 두 줄만 보고 통신사가 UDP를 차단했다고 단정할 수는 없습니다. 호스트 방화벽, 라우터, 네트워크 정책, 당시 링크 상황 모두 점검해볼 필요가 있습니다.

QUIC은 UDP 기반이고, cloudflared가 QUIC을 쓸 때는 아웃바운드 UDP 7844가 필요합니다. HTTP/2는 아웃바운드 TCP 7844를 씁니다. 현재 --protocol auto가 기본값이고, QUIC을 시도한 뒤 연결이 안 되면 HTTP/2로 폴백합니다. QUIC 타임아웃이 계속된다고 해서 소프트웨어가 자동 전환을 지원하지 않는다고 이해하면 안 됩니다.

설명 이미지: cloudflared: auto가 현재 기본 프로토콜 선택

임시로 HTTP/2 지정하기

로그에 QUIC 타임아웃이 계속 찍히면 --protocol http2를 명시적으로 지정해서 복구되는지 지켜볼 수 있습니다. 아래는 token 파일을 사용해서 tunnel token을 Compose 명령에 직접 노출하지 않는 방식입니다.

YAML

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: unless-stopped
    command: tunnel --no-autoupdate --protocol http2 run --token-file /run/secrets/tunnel_token
    volumes:
      - ./tunnel-token:/run/secrets/tunnel_token:ro

--token-file은 cloudflared 2025.4.0 이상이 필요합니다. 먼저 자기 token이 담긴 실제 파일을 준비하고, 필요한 계정만 읽을 수 있게 권한을 설정하세요. 컨테이너 실행 사용자가 그 파일을 읽을 수 있는지도 확인해야 합니다. root만 읽을 수 있게 해놓고 비root 컨테이너가 열려고 하면 안 되니까요. 이 파일을 Git에 커밋하거나 공개 디렉터리에 동기화하면 안 됩니다.

BASH

docker compose up -d
docker compose logs --tail=100 cloudflared

컨테이너를 다시 만들기 전에 쓸 수 있는 관리 진입점이 있는지 확인하세요. 성공 로그에는 Registered tunnel connection과 사용된 프로토콜이 보여야 합니다. 이건 관찰 방법이지, 이 글에서 새로 실행한 결과 스크린샷이 아닙니다.

HTTP/2도 그에 맞는 TCP 아웃바운드 연결이 필요합니다. TCP 7844까지 막혀 있다면 파라미터를 바꿔도 해결되지 않습니다. Tunnel은 집 라우터에 인바운드 7844 포트 매핑을 추가할 필요가 없습니다.

터널은 온라인인데 사이트는 여전히 안 열릴 때

cloudflared에서 Cloudflare 엣지까지 연결이 정상이라는 건 첫 구간이 정상이라는 뜻일 뿐입니다. cloudflared가 자기가 설정한 오리진에 접근할 수 있는지도 확인해야 합니다.

cloudflared가 Docker 안에 있으면 오리진에 localhost라고 쓰는 건 자기 컨테이너를 가리키는 것이지 NAS가 아닙니다. 오리진이 다른 컨테이너라면 적절한 같은 Docker 네트워크에 두고 서비스 이름을 쓰세요. 오리진이 LAN 머신에 있다면 컨테이너에서 실제로 도달 가능한 주소와 포트를 사용하세요. 그리고 인증서 검증을 전부 꺼버리기보다는 오리진 프로토콜과 인증서를 확인하세요.

이 글은 그때의 장애 경과를 바탕으로 현재 기본 프로토콜 동작, 포트, 자격 증명 처리를 설명합니다. 설정 예시는 문서와 대조해 확인했지만, 실제 Tunnel에서 직접 테스트하지는 않았습니다.

참고: 실행 파라미터, 방화벽 요구 사항.