504 Gateway Timeout 체크리스트

Problem

프록시는 응답을 줬고, 그 응답이 504 Gateway Timeout이었습니다. RFC 9110 §15.6.5를 문자 그대로 읽어보면, 게이트웨이가 “필요한 upstream 서버로부터 제때(timely) 응답을 받지 못했다”는 뜻입니다. 핵심은 제때입니다. 504는 “백엔드에 닿지 못했다”가 아니라 “닿았고, 기다렸고, 끝까지 답이 오지 않았다”입니다. 가장 쓸모 있는 증거는 504가 돌아오기까지 요청이 얼마나 매달려 있었는가입니다.

Symptoms

• HTTP Check에서 최종 코드가 504인데, 지연 시간이 의심스러울 만큼 딱 떨어집니다 — 보통 30초, 60초, 100초쯤.
• edge나 프록시 자체는 살아 있습니다. 연결이 끊긴 게 아니라 HTTP 오류 페이지를 받았습니다.
• 느린 엔드포인트에서 더 심합니다 — 리포트, 내보내기, 검색처럼 실제 작업이 도는 경로. 정적 페이지는 멀쩡합니다.
• 502(프록시가 잘못된/빈 응답을 받음)도 아니고, 클라이언트단 ERR_CONNECTION_TIMED_OUT(SYN이 아예 응답을 못 받음)도 아닙니다.

Top 3 Causes

1. upstream이 죽은 게 아니라 느림 - 프록시의 read timeout을 넘깁니다. nginx는 proxy_read_timeout, proxy_connect_timeout, proxy_send_timeout 기본값이 모두 60초이고, AWS ALB는 idle timeout 기본 60초, 대상 연결 타임아웃 10초입니다. 무거운 쿼리에서 65초 걸리는 백엔드는 시계처럼 정확히 504를 만듭니다.
2. 프록시가 upstream에 제때 연결조차 못 함 - connect timeout입니다. 백엔드가 포화됐거나 accept 큐가 가득 찼거나, 설정된 upstream 주소가 틀렸거나 방화벽에 막혔습니다. 프록시는 연결 대기 시간을 다 쓰고 포기합니다.
3. 체인 안의 타임아웃 불일치 - 모든 hop(CDN → 로드밸런서 → 앱 서버 → DB)이 각자 시계를 들고 있고, 가장 짧은 것이 먼저 발동합니다. 정당하게 90초가 필요한 요청이 60초 프록시 뒤에 있으면, 개별 구성요소가 아무리 멀쩡해도 항상 504가 납니다.

시계 팁: 504 직전의 지연을 보세요. nginx나 ALB에서 60초쯤이면 read timeout을 정조준한 것입니다 — 방화벽이 아니라 느린 쿼리를 고치거나 한계를 올리세요.

Diagnose with DechoNet

• HTTP Check로 최종 코드가 504인지, 그리고 요청이 얼마나 걸리는지 확인합니다. 딱 떨어지는 초 단위에 돌아오는 504는 우연이 아니라 타임아웃이 발동한 것입니다.
• Port Check로 upstream/origin 포트가 실제 도달 가능한지 확인합니다. connect timeout 원인과 read timeout 원인을 분리해 줍니다. 포트가 열려 있다면 프록시는 백엔드에 닿을 수 있고, 문제는 라우팅이 아니라 지연입니다.
• DNS Lookup으로 프록시가 살아 있는 origin을 가리키는지, 조용히 연결을 삼키는 옛 주소를 가리키는지 확인합니다.

포트가 타임아웃이 아니라 닫힘/거부로 나오면 이는 타임아웃이 아니라 도달성 문제입니다 — open port 443 closed 체크리스트로 넘어가세요. 브라우저가 HTTP 코드조차 못 받고 ERR_CONNECTION_TIMED_OUT으로 실패하면 클라이언트-edge 구간 문제입니다 — ERR_CONNECTION_TIMED_OUT 해결을 보세요.

Resolution Checklist

• 실패하는 경로의 실제 응답 시간을 측정합니다. 프록시 read timeout 근처면 원인을 찾은 것입니다.
• 프록시 타임아웃 설정(proxy_read_timeout, ALB idle timeout)을 실제 백엔드 지연과 비교합니다. 한계를 올리는 건 임시방편이고, 느린 경로를 고치는 게 진짜 해결입니다.
• 느린 엔드포인트를 프로파일링합니다 — 누락된 인덱스, N+1 쿼리, 블로킹 외부 API 호출. 504는 대개 네트워크 의상을 입은 성능 버그입니다.
• upstream 포트가 도달 가능하고 백엔드가 포화되지 않았는지(accept 큐 가득 참, 워커/커넥션 풀 고갈) 확인합니다.
• 체인 전체를 따라가며 타임아웃을 정렬해, 바깥 프록시가 정당하게 시간이 필요한 안쪽 hop보다 짧지 않게 만듭니다.
• HTTP Check를 다시 실행합니다. 정상이라면 타임아웃에 딱 붙어서가 아니라 그보다 한참 아래에서 응답이 돌아옵니다.

When to Escalate

• 504가 특정 무거운 엔드포인트를 따라다니면 그 upstream 담당자에게 넘기세요. 이는 애플리케이션 성능 문제이고, 프록시 타임아웃을 올리는 건 고통을 뒤로 미루는 것일 뿐입니다.
• managed 로드밸런서나 CDN이 앞단에 있고 타임아웃 설정 권한이 본인이 아니라면 플랫폼/인프라 담당자에게 에스컬레이션합니다.
• 504가 간헐적이고 트래픽 급증과 맞물린다면 단일 장애가 아니라 용량·포화 문제로 다루세요 — autoscaling, 커넥션 풀, DB 경합을 봐야 합니다.