리눅스 서버 504 Gateway Timeout 뜰 때 응답 지연부터 확인하는 법

리눅스 서버에서 504 Gateway Timeout 오류가 발생했을 때 응답 지연, upstream timeout, 애플리케이션 로그, nginx timeout 설정을 확인하는 순서를 설명하는 대표 이미지

리눅스 서버에서 504 Gateway Timeout 오류가 뜨면 nginx나 웹서버가 죽은 것처럼 보일 수 있습니다. 하지만 서버 운영 중 만나는 504 오류는 앞단 웹서버가 뒤쪽 WAS나 애플리케이션 서버의 응답을 기다리다가 시간이 초과될 때 자주 발생합니다. 이번 글에서는 504 오류가 났을 때 바로 재기동하지 않고, 응답 지연, 애플리케이션 로그, DB 지연, timeout 설정을 어떤 순서로 확인하면 안전한지 정리해보겠습니다.

504 Gateway Timeout은 무슨 뜻일까?

504 Gateway Timeout은 앞단 서버가 뒤쪽 서버의 응답을 기다렸지만, 정해진 시간 안에 응답을 받지 못했다는 뜻입니다.

예를 들면 이런 흐름입니다.

사용자
→ nginx
→ WAS 또는 애플리케이션
→ DB 또는 외부 API

 

이때 nginx는 요청을 받았지만, 뒤쪽 애플리케이션이 너무 늦게 응답하면 504가 발생할 수 있습니다.

즉, 504는 “아예 연결이 안 됨”보다는 연결은 됐지만 응답이 늦음에 가까운 경우가 많습니다.

502, 503, 504는 헷갈리기 쉽습니다

초보 운영자 입장에서는 502, 503, 504가 비슷하게 보일 수 있습니다.

502: 앞단과 뒤쪽 서버 연결 문제 가능성
503: 서비스가 요청을 받을 준비가 안 된 상태 가능성
504: 뒤쪽 서버 응답이 늦어서 timeout 가능성

 

그래서 504가 떴을 때는 “nginx가 죽었나?”보다 먼저
뒤쪽 서비스가 왜 늦게 응답했는지를 확인하는 게 좋습니다.

초보 운영자가 하기 쉬운 실수

504가 뜨면 급한 마음에 이렇게 하기 쉽습니다.

 

systemctl restart nginx
systemctl restart example-app

 

물론 상황에 따라 재기동이 필요할 수도 있습니다.
하지만 504는 단순 프로세스 장애보다 DB 지연, 외부 API 지연, 애플리케이션 처리 지연, timeout 설정 문제일 가능성이 있습니다.

원인을 보지 않고 재기동하면 일시적으로 좋아질 수는 있어도, 다시 같은 시간대에 504가 반복될 수 있습니다.

운영에서는 이번에도 먼저 확인해야 합니다.

1단계. curl로 504 상태코드 확인하기

브라우저 화면만 보지 말고 curl로 상태코드를 확인합니다.

 

curl -I http://example.com/api/report

 

예시 결과입니다.

 

HTTP/1.1 504 Gateway Timeout
Server: nginx
Content-Type: text/html

 

여기서 볼 것은 두 가지입니다.

1. 실제 상태코드가 504인지
2. 응답을 준 서버가 nginx인지

 

Server: nginx가 보인다고 해서 nginx 자체가 원인이라는 뜻은 아닙니다.
nginx가 뒤쪽 애플리케이션의 응답을 기다리다 timeout이 나서 504를 반환했을 수 있습니다.

2단계. 특정 URL만 느린지 확인하기

504는 전체 서비스에서 발생할 수도 있고, 특정 API에서만 발생할 수도 있습니다.

아래처럼 경로별로 확인합니다.

 

curl -I http://example.com/
curl -I http://example.com/login
curl -I http://example.com/api/users
curl -I http://example.com/api/report

 

예를 들어 결과가 이렇게 나올 수 있습니다.

/                 → 200 OK
/login            → 200 OK
/api/users        → 200 OK
/api/report       → 504 Gateway Timeout

 

이 경우 서버 전체 장애라기보다 /api/report 요청 처리 시간이 오래 걸리는 상황일 수 있습니다.

특정 API만 504라면 해당 기능의 애플리케이션 로그, DB 쿼리, 외부 연동을 먼저 봐야 합니다.

3단계. 응답 시간을 같이 확인하기

504는 응답 지연이 핵심이므로 시간도 같이 봐야 합니다.

 

time curl -I http://example.com/api/report

 

또는 curl에서 응답 시간을 표시할 수 있습니다.

 

curl -o /dev/null -s -w "time_total: %{time_total}\n" http://example.com/api/report

 

예시입니다.

time_total: 60.124321

 

60초 근처에서 끊긴다면 nginx나 로드밸런서의 timeout 설정과도 관련이 있을 수 있습니다.

운영 서버에서는 “안 된다”뿐 아니라
몇 초 뒤에 안 되는지가 중요한 단서가 됩니다.

4단계. nginx access.log 확인하기

nginx access log에서 504가 찍힌 요청을 확인합니다.

 

tail -n 100 /var/log/nginx/access.log

 

예시입니다.

192.0.2.10 - - [04/Jul/2026:14:00:00 +0900] "GET /api/report HTTP/1.1" 504 167 "-" "Mozilla/5.0"

 

여기서 확인할 것은 다음입니다.

어떤 URL이 504인지
특정 시간대에 몰리는지
GET인지 POST인지
응답 시간이 로그에 남는지
특정 사용자 요청에서만 발생하는지

 

nginx 로그 포맷에 $request_time, $upstream_response_time이 포함되어 있다면 더 좋습니다.

예를 들어 이런 값이 보일 수 있습니다.

request_time=60.001 upstream_response_time=60.000

 

이런 경우 nginx가 뒤쪽 응답을 오래 기다리다 timeout이 난 상황을 의심할 수 있습니다.

5단계. nginx error.log 확인하기

error log에서는 timeout 관련 메시지를 확인합니다.

 

tail -n 100 /var/log/nginx/error.log

 

자주 볼 수 있는 메시지 예시입니다.

upstream timed out while reading response header from upstream

 

이 메시지는 nginx가 upstream 서버에 요청을 보냈지만, 응답 헤더를 제때 받지 못했다는 뜻입니다.

이 경우 확인 대상은 nginx 자체보다 뒤쪽입니다.

애플리케이션 처리 지연
DB 쿼리 지연
외부 API 응답 지연
서버 리소스 부족
timeout 설정 부족

 

6단계. upstream으로 직접 요청해보기

nginx를 거치지 않고 뒤쪽 애플리케이션에 직접 요청해봅니다.

 

curl -I http://127.0.0.1:8080/api/report

 

응답 시간을 같이 확인합니다.

 

curl -o /dev/null -s -w "time_total: %{time_total}\n" http://127.0.0.1:8080/api/report

 

만약 직접 호출도 오래 걸린다면 nginx보다 애플리케이션 또는 DB 쪽 지연 가능성이 큽니다.

반대로 직접 호출은 빠른데 nginx를 거치면 느리다면 nginx 설정, 네트워크 경로, 로드밸런서, 프록시 timeout 설정을 더 봐야 합니다.

7단계. 애플리케이션 로그 확인하기

504의 단서는 애플리케이션 로그에 남는 경우가 많습니다.

 

tail -n 200 /app/logs/application.log

 

systemd로 관리되는 서비스라면:

 

journalctl -u example-app -n 200 --no-pager

 

찾아볼 단서는 이런 것들입니다.

처리 시간이 긴 요청
DB query timeout
Connection timed out
외부 API timeout
Thread pool exhausted
Request timeout
Slow query

 

로그에서 504 발생 시간대와 같은 시각에 오류나 지연 메시지가 있는지 봐야 합니다.

 

grep -i "timeout\|slow\|error\|exception" /app/logs/application.log | tail -n 50

 

8단계. DB 지연 여부 확인하기

504는 DB 응답 지연 때문에 발생하는 경우가 많습니다.

애플리케이션 로그에서 이런 메시지를 볼 수 있습니다.

Query timeout
Too many connections
Lock wait timeout
Connection pool exhausted

 

DB 서버에 직접 접근할 수 있는 권한이 있다면, DB 상태나 slow query log를 확인해야 합니다.
다만 운영 DB에서는 무거운 조회를 함부로 실행하면 안 됩니다.

운영자 입장에서는 먼저 애플리케이션 로그에서 DB 관련 오류를 찾고, 필요하면 DB 담당자에게 아래처럼 전달하는 것이 안전합니다.

14:00 전후 /api/report 요청에서 504 발생
애플리케이션 로그에 DB query timeout 확인
해당 시간대 DB slow query 또는 connection 상태 확인 요청

 

9단계. 외부 API 지연 확인하기

애플리케이션이 외부 API를 호출하는 구조라면, 외부 연동 지연도 504 원인이 될 수 있습니다.

예를 들어 결제, 인증, 문자, 파일 변환, 외부 조회 API 같은 연동이 있을 수 있습니다.

애플리케이션 로그에서 이런 단서를 확인합니다.

External API timeout
Read timed out
Connection timed out
HTTP 504 from upstream

 

외부 API가 느리면 내부 애플리케이션도 응답을 못 하고, 결국 앞단 nginx에서 504가 날 수 있습니다.

이때도 바로 서버 재기동보다, 어느 외부 연동에서 지연되는지 확인하는 것이 먼저입니다.

10단계. timeout 설정 확인하기

nginx에서 timeout 관련 설정을 확인합니다.

 

grep -R "proxy_read_timeout" /etc/nginx/
grep -R "proxy_connect_timeout" /etc/nginx/
grep -R "proxy_send_timeout" /etc/nginx/

 

예시입니다.

 

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_connect_timeout 5s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}

 

여기서 proxy_read_timeout은 nginx가 upstream 응답을 기다리는 시간과 관련됩니다.

하지만 timeout 값을 무작정 늘리는 것은 조심해야 합니다.
응답이 느린 원인을 해결하지 않고 timeout만 늘리면, 사용자는 더 오래 기다리고 서버 자원은 더 오래 묶일 수 있습니다.

먼저 실제로 왜 늦는지 확인한 뒤 조정해야 합니다.

11단계. 서버 리소스 확인하기

응답 지연은 CPU, 메모리, 디스크 I/O 문제에서도 생길 수 있습니다.

 

top
free -m
df -h

 

디스크 I/O가 의심될 때는 환경에 따라 iostat을 볼 수 있습니다.

 

iostat -x 1 3

 

다만 iostat 명령어가 설치되어 있지 않을 수 있습니다.
그럴 때는 top, 로그, 디스크 사용률, 애플리케이션 처리 지연 로그를 함께 봐야 합니다.

OOM 여부도 확인합니다.

 

dmesg -T | grep -i "out of memory\|killed process"

 

운영 서버에서 조심할 점

504가 났다고 바로 아래처럼 조치하는 것은 조심해야 합니다.

 

systemctl restart nginx
systemctl restart example-app

 

또 timeout을 무작정 크게 늘리는 것도 조심해야 합니다.

 

proxy_read_timeout 600s;

 

이런 설정은 일시적으로 504를 줄이는 것처럼 보일 수 있지만, 실제로는 느린 요청을 더 오래 붙잡아 서버 자원을 더 많이 사용할 수 있습니다.

운영에서는 먼저 아래를 확인하는 게 안전합니다.

어떤 URL에서 504가 나는지
몇 초 뒤 timeout이 나는지
upstream 직접 호출도 느린지
애플리케이션 로그에 지연 단서가 있는지
DB 또는 외부 API 지연이 있는지
서버 리소스가 부족한지

 

정리하면

504 Gateway Timeout은 앞단 서버가 뒤쪽 서버의 응답을 기다리다 시간 초과된 상황일 수 있습니다.

확인 순서는 이렇게 잡을 수 있습니다.

1. curl -I 로 504 상태코드 확인
2. 어떤 URL에서 504가 나는지 확인
3. curl 응답 시간 확인
4. nginx access.log 확인
5. nginx error.log에서 upstream timed out 확인
6. upstream 직접 curl 테스트
7. 애플리케이션 로그 확인
8. DB 지연 확인
9. 외부 API 지연 확인
10. timeout 설정 확인
11. CPU, 메모리, 디스크 리소스 확인

 

504 Gateway Timeout은 앞단 서버가 뒤쪽 서버의 응답을 기다리다가 시간이 초과됐다는 의미에 가깝습니다.

그래서 504가 보인다고 바로 서버를 재기동하기보다, 어느 구간에서 응답이 늦어지는지 먼저 확인하는 것이 좋습니다.

앞단 웹서버, 로드밸런서, upstream 애플리케이션, 네트워크 지연, 타임아웃 설정, 서버 리소스 상태를 나눠서 보면 원인을 더 안전하게 좁힐 수 있습니다.

특히 504는 “응답이 늦다”는 신호에 가깝기 때문에, 포트가 열려 있는지뿐 아니라 실제 HTTP 응답이 돌아오는지, 애플리케이션 로그에 지연이나 timeout 메시지가 남아 있는지도 함께 확인해야 합니다.

HTTP 오류 코드별 확인 순서를 한 번에 보고 싶다면 아래 글을 함께 보면 좋습니다.

https://opsnote.tistory.com/63

리눅스 서버 HTTP 응답 코드별 확인 순서 정리, 에러 코드만 봐도 방향이 보입니다

 

웹 장애 상황을 보고할 때 HTTP 코드를 어떻게 정리하면 좋은지는 아래 글에서 이어서 볼 수 있습니다.

https://opsnote.tistory.com/64

리눅스 서버 웹 장애 보고할 때 HTTP 코드 정리하는 법, 한눈에 보이는 오류 보고 가이드