DevOps 지식 허브
DevOps 지식 허브

Nginx 504 게이트웨이 시간 초과 및 클라이언트 시간 초과 문제 해결

치명적인 `proxy_read_timeout` 늘리기, 버퍼링 최적화, Nginx와 업스트림 서버 간의 통신 오류 진단을 위한 오류 로그 사용법을 배우면서 504 게이트웨이 시간 초과를 포함한 Nginx 시간 초과를 마스터하세요. 이 가이드는 강력한 연결 처리를 위한 방법을 자세히 설명합니다.

62 조회수

Nginx 504 게이트웨이 시간 초과 및 클라이언트 시간 초과 문제 해결

Nginx는 높은 성능과 안정성으로 잘 알려져 있지만, 때로는 의사소통 오류를 나타내는 HTTP 상태 코드를 포함하여 답답한 오류를 발생시킬 수 있습니다. 가장 흔한 오류 중에는 504 게이트웨이 시간 초과 및 다양한 클라이언트 측 시간 초과가 있습니다. 이러한 문제는 거의 항상 Nginx가 백엔드 서비스(애플리케이션 서버 또는 다른 프록시 등)로부터 응답을 기다리는 시간과 클라이언트(브라우저 또는 업스트림 서비스)가 Nginx 자체를 기다리려는 시간 간의 불일치에서 비롯됩니다.

이 포괄적인 가이드에서는 이러한 시간 초과의 근본 원인을 진단하고 504 오류를 해결하며 전반적인 연결 안정성을 향상시키기 위한 구체적인 구성 조정을 제공합니다.

504 게이트웨이 시간 초과 오류 이해하기

504 Gateway Timeout 오류는 Nginx가 리버스 프록시 또는 게이트웨이 역할을 할 때 요청을 전달하는 업스트림 서버로부터 적시에 응답을 받지 못할 때 발생합니다. 간단히 말해, Nginx는 백엔드에 답변을 요청했고, 설정된 시간 동안 기다렸지만 응답이 오지 않아 포기한 것입니다.

이는 502 잘못된 게이트웨이(업스트림의 잘못된 응답을 의미) 또는 503 서비스 불가(업스트림이 과부하되었거나 사용할 수 없음을 의미)와는 구별됩니다.

업스트림 시간 초과를 제어하는 주요 지시문

요청을 프록시할 때 Nginx는 여러 가지 중요한 지시문을 사용하며, 주로 http, server 또는 location 블록 내에 있거나 특히 upstream 블록 내에 있습니다. 이러한 값을 조정하는 것이 504 오류를 해결하는 주요 방법입니다.

1. proxy_connect_timeout

업스트림 서버와의 연결 설정 시간 초과를 설정합니다. Nginx가 이 시간 내에 연결할 수 없으면 시간 초과 오류가 반환됩니다.

기본값: 60초

proxy_connect_timeout 60s;

2. proxy_send_timeout

업스트림 서버로의 두 번의 연속적인 쓰기 작업 간의 시간 초과를 설정합니다. 이는 큰 요청 본문을 보낼 때 관련이 있습니다.

기본값: 60초

proxy_send_timeout 60s;

3. proxy_read_timeout (504에 대한 가장 일반적인 수정 사항)

요청 헤더가 전송된 후 업스트림 서버로부터 응답을 기다리는 시간 초과를 설정합니다. 백엔드 애플리케이션이 요청을 처리하고 응답 본문을 생성하는 데 너무 오래 걸리면 이 지시문을 늘려야 합니다.

기본값: 60초

# 예: 느린 API에 대한 읽기 시간 초과를 120초로 늘리기
proxy_read_timeout 120s;

모범 사례: 애플리케이션이 기본 60초를 자주 초과하는 경우 이 값을 신중하게 늘리십시오. 너무 높은 값은 근본적인 백엔드 성능 문제를 가릴 수 있습니다.

클라이언트 측 시간 초과 처리

504는 Nginx-백엔드 통신과 관련이 있지만, 클라이언트 측 시간 초과는 Nginx가 백엔드와 통신을 완료하기도 전에 클라이언트(예: 브라우저, 모바일 앱 또는 Nginx에 요청하는 다른 서비스)가 기다리기를 포기할 때 발생합니다.

Nginx가 504를 기록하기 전에 클라이언트 시간 초과가 발생하는 경우, 클라이언트와 Nginx 간의 연결을 살펴봐야 합니다.

1. 클라이언트 측 Keepalive

클라이언트가 연결을 조기에 닫으면 Nginx가 오류를 받거나 클라이언트가 데이터를 기다리다 시간 초과될 수 있습니다.

클라이언트 측 연결 설정(구성 가능한 경우)이 너무 공격적이지 않은지 확인하십시오. 클라이언트가 다른 프록시 또는 로드 밸런서인 경우 Nginx의 send_timeout에 대한 시간 초과 설정을 확인하십시오.

2. Nginx send_timeout

이 지시문은 Nginx가 클라이언트가 데이터를 승인하거나 수신하기를 기다리는 시간(클라이언트로의 두 번의 연속적인 쓰기 작업 간의 시간)을 제어합니다.

기본값: 60초

# Nginx가 응답을 보내는 동안 클라이언트가 시간 초과되는 경우 이 값을 설정하십시오.
send_timeout 120s;

대용량 응답에 대한 버퍼링 최적화

때로는 처리 시간이 너무 오래 걸려서가 아니라, Nginx가 업스트림 응답을 버퍼링하기 시작했다가 연결 시간 초과 전에 버퍼 쓰기를 완료하지 못해서 시간 초과가 발생하기도 합니다. 이는 특히 대용량 응답을 처리할 때 관련이 있습니다.

Nginx는 업스트림에서 받은 데이터를 클라이언트로 보내기 전에 임시로 저장하는 버퍼를 사용합니다. 응답이 매우 큰 경우 이러한 버퍼가 초과되어 복잡한 처리 또는 지연 시간이 발생할 수 있습니다.

주요 버퍼링 지시문

이 지시문은 일반적으로 location 블록 또는 server 블록 내에 설정됩니다.

지시문 목적
proxy_buffers 업스트림으로부터 응답 헤더를 읽는 데 사용되는 버퍼의 수와 크기를 설정합니다. 형식: number size;
proxy_buffer_size 응답 헤더를 읽는 데 사용되는 첫 번째 버퍼의 크기를 설정합니다.
proxy_max_temp_file_size 응답이 사용 가능한 버퍼를 초과하면 Nginx는 임시 파일에 씁니다. 이는 이러한 임시 파일의 최대 크기를 설정합니다.

대량/대용량 응답에 대한 예제 구성:

location /api/heavy_report {
    proxy_pass http://backend_app;

    # 읽기 시간 초과 늘리기
    proxy_read_timeout 180s;

    # 잠재적으로 큰 응답 본문에 대한 버퍼링 조정
    # 8개의 버퍼 사용, 각각 최대 1MB(1024k)
    proxy_buffers 8 1024k;
    proxy_buffer_size 256k;

    # 버퍼가 초과되면 최대 500MB의 임시 파일 허용
    proxy_max_temp_file_size 500m;
}

버퍼링 팁: 백엔드 응답이 실제로 매우 큰 경우(예: 수 GB), 매우 큰 응답을 버퍼링하면 Nginx 서버에서 상당한 메모리를 소비할 수 있으므로 정적 콘텐츠를 제공하거나 스트리밍을 직접 구현하는 것을 고려하십시오.

문제 해결 단계 및 로그 분석

시간 초과를 해결하려면 지연이 발생한 위치를 정확히 파악해야 합니다. 클라이언트 -> Nginx 또는 Nginx -> 백엔드.

1단계: Nginx 오류 로그 확인

Nginx 오류 로그는 Nginx가 백엔드를 기다리다 시간 초과되었는지 여부를 판단하는 결정적인 소스입니다.

다음과 같은 문구가 포함된 항목을 찾으십시오.

  • upstream timed out (110: Connection timed out)
  • upstream prematurely closed connection while reading response header from upstream

이러한 메시지가 보이면 문제는 proxy_read_timeout 또는 백엔드의 처리 시간과 관련이 있습니다.

2단계: 백엔드 애플리케이션 로그 확인

Nginx가 시간 초과되면(로그에 504 표시), 즉시 업스트림 서비스(예: PHP-FPM 로그, Gunicorn 로그, Java 애플리케이션 서버 로그)의 로그를 확인하십시오. 요청이 백엔드에 도달했는지, 그리고 완료하는 데 얼마나 걸렸는지 확인해야 합니다.

  • 백엔드 로그에 요청이 구성된 proxy_read_timeout보다 더 오래 걸렸다고 표시되면 Nginx 시간 초과를 늘리십시오.
  • 백엔드 로그에 요청이 빠르게 완료되었다고 표시되면 Nginx와 백엔드 간의 네트워크 지연 문제이거나 Nginx를 마주보는 잘못 구성된 클라이언트 시간 초과일 수 있습니다.

3단계: X-Upstream-Response-Time 헤더 사용 (선택 사항)

자세한 진단을 위해 액세스 로그 형식에서 $upstream_response_time 변수를 사용하여 업스트림이 응답하는 데 걸린 정확한 시간을 기록할 수 있습니다. 이는 백엔드의 실제 성능을 확인하는 데 도움이 됩니다.

nginx.conf 파일:

log_format proxy_detailed '$remote_addr - $remote_user [$time_local] "$request" '
                        '$status $body_bytes_sent "$http_referer" '
                        '"$http_user_agent" $request_time $upstream_response_time';

access_log /var/log/nginx/access.log proxy_detailed;

$upstream_response_time을 분석하면 Nginx 자체의 시간 초과 설정과 관계없이 Nginx가 기다린 정확한 시간을 볼 수 있습니다.

요약 및 변경 사항 적용

Nginx 시간 초과 문제를 해결하는 것은 일반적으로 클라이언트의 기대치와 백엔드의 처리 능력 간의 균형을 맞추는 작업입니다. 관계를 기억하십시오.

  • 504 시간 초과: 백엔드가 너무 느리거나 Nginx가 기다리는 동안 네트워크 링크가 실패함 (proxy_read_timeout).
  • 클라이언트 시간 초과: 클라이언트가 Nginx를 기다리다 포기함 (send_timeout 또는 클라이언트 설정).

구성 변경(예: 시간 초과 증가 또는 버퍼 크기 조정)을 한 후에는 항상 구성 구문을 테스트하고 Nginx를 다시 로드하십시오.

sudo nginx -t
sudo systemctl reload nginx

수정 사항을 적용한 후에는 로그를 주의 깊게 모니터링하십시오. 시간 초과를 무분별하게 늘리면 최적화가 아닌 구성 임시방편이 필요한 근본적인 시스템 성능 병목 현상을 가릴 수 있습니다.