HTTP 504 Gateway Timeout 오류의 원인과 해결 방법

1. 증상 및 오류 메시지

HTTP 504 Gateway Timeout 오류는 웹 서버가 요청을 처리하는 동안 응답을 제때 받지 못했을 때 발생합니다. 이 오류는 주로 프록시 서버가 업스트림 서버로부터 응답을 기다리다가 시간 초과가 발생했을 때 나타납니다. 사용자는 다음과 같은 메시지를 보게 됩니다:

504 Gateway Timeout
HTTP 504
Gateway Timeout (504)

이러한 오류는 일반적으로 서버의 응답 시간이 너무 길거나, 네트워크 문제, 또는 서버의 과부하로 인해 발생합니다.

2. 원인

HTTP 504 오류의 주요 원인은 다음과 같습니다:

느린 업스트림 처리: 백엔드 서버가 복잡한 쿼리나 무거운 작업을 처리하고 있을 때, 응답이 지연될 수 있습니다.
짧은 프록시 타임아웃: 프록시 서버의 타임아웃 설정이 너무 짧아, 정상적인 작업이 완료되기 전에 응답을 포기하게 됩니다.
서버 과부하: 요청이 밀리거나 큐에 쌓여서 응답이 지연될 수 있습니다.
DB 또는 외부 서비스 지연: 데이터베이스 쿼리가 느리거나 외부 API 호출이 지연될 때 발생할 수 있습니다.
네트워크 지연: 프록시와 업스트림 서버 간의 네트워크 문제가 발생할 수 있습니다.

3. 확인 명령어

문제를 진단하기 위해 다음과 같은 명령어를 사용하여 응답 시간을 측정할 수 있습니다:

curl -o /dev/null -s -w "time_total: %{time_total}s\n" http://127.0.0.1:3000/slow

이 명령어는 특정 URL에 대한 응답 시간을 측정하여, 응답이 지연되고 있는지 확인하는 데 유용합니다. 또한, Nginx의 에러 로그를 확인하여 다음과 같은 메시지를 찾을 수 있습니다:

upstream timed out (110: Connection timed out) while reading response header from upstream

4. 해결 절차

504 Gateway Timeout 오류를 해결하기 위해 다음 단계를 따르세요:

업스트림 응답 시간 확인: 요청이 느린지 확인하기 위해 직접 요청하여 응답 시간을 측정합니다. 느린 쿼리나 작업이 있는지 확인합니다.
프록시 타임아웃 설정 변경: Nginx 설정 파일에서 타임아웃 값을 늘려줍니다. 예를 들어:
```
proxy_read_timeout 300;
proxy_send_timeout 300;
proxy_connect_timeout 300;
```
슬로우 쿼리 최적화: 데이터베이스 쿼리를 최적화하거나 인덱스를 추가하여 응답 속도를 개선합니다.
비동기 처리: 무거운 작업은 비동기로 처리하여 사용자가 즉시 응답을 받을 수 있도록 합니다.
서버 리소스 모니터링: 서버의 리소스를 모니터링하여 과부하를 방지합니다.

5. 흔한 실수

타임아웃만 늘리기: 타임아웃을 늘리는 것이 임시방편일 뿐, 근본적인 문제를 해결하지 못합니다. 느린 쿼리나 작업을 개선해야 합니다.
업스트림 서버의 상태 확인 소홀: 업스트림 서버가 정상적으로 작동하는지 확인하지 않으면 문제를 놓칠 수 있습니다.
네트워크 문제 간과: 프록시와 업스트림 간의 네트워크 문제를 간과하지 않도록 주의해야 합니다.

6. 재발 방지 체크리스트

업스트림 응답 시간을 정기적으로 모니터링합니다.
슬로우 쿼리 로그를 활성화하여 문제를 조기에 발견합니다.
비동기 작업을 통해 사용자 경험을 개선합니다.
Nginx의 타임아웃 설정을 합리적으로 조정합니다.
서버 리소스를 정기적으로 점검하여 과부하를 방지합니다.

이러한 절차를 통해 HTTP 504 Gateway Timeout 오류를 효과적으로 해결하고 재발을 방지할 수 있습니다.

실무 적용 체크리스트

HTTP 504 gateway timeout 원인과 해결을 적용하기 전에 현재 운영 환경의 기준값과 예외 상황을 먼저 정리합니다.
변경 전후로 확인할 지표를 정하고, 문제가 생겼을 때 되돌릴 수 있는 절차를 문서화합니다.
한 번에 모든 서버나 서비스에 적용하기보다 작은 범위에서 검증한 뒤 점진적으로 확대합니다.
담당자, 확인 시간, 장애 판단 기준을 명확히 남겨 같은 문제가 반복될 때 빠르게 대응할 수 있게 합니다.