estudy 한국어/English

Nginx 502·504 차이

1,359 단어·3 분·원문(.md)

Nginx는 가볍고 높은 성능을 자랑하는 오픈소스 Web Server다.

초기에는 정적파일 html, image등을 서비스하는 웹서버로 시작했으나 현재는 리버스 프록시, 로드밸런서 http cache등의 역할을 수행하는 인프라 소프트웨어로 쓰인다.

  • 이벤트 기반 아키텍처: 아파치와 같은 기존 웹 서버가 요청 하나당 하나의 스레드/프로세스를 할당하는 방식과 달리 nginx는 비동기 이벤트 기반 구조를 가진다. 적은 메모리로 수많은 동시연결을 처리할 수 있다.
  • 리버스 프록시: 클라이언트의 요청을 직접 처리하지 않고 뒤에 있는 백엔드 애플리케이션 서버로 전달한뒤 그 결과를 받아 다시 클라이언트에게 전달하는 문지기 역할을 한다.

502 Bad Gateway vs 504 Gateway Timeout 차이 #

이 두 에러는 모두 nginx가 리버스 프록시로 동작할 때, nginx와 백엔드 서버 간의 통신 과정에서 발생한다. nginx 자체의 문제가 아니라 nginx가 바라보는 뒷단 서버의 상태 때문에 발생한다는 공통점이 있지만 원인은 명확하게 다르다.

502 Bad Gateway (응답불량) #

nginx가 백엔드 서버로 요청을 보냈지만, 유효하지않은 응답을 받았거나 아예 연결조차 하지 못했을 때 발생한다. 즉, 백엔드 서버가 죽어있거나 통신이 불가능한 상태.

  • 주요원인
    • 백엔드 애플리케이션 tomcat, nodejs 등이 프로세스가 죽어 다운된 경우
    • nginx 설정 nginx.conf에 백엔드 서버의 포트나 ip가 잘못 입력됨
    • 백엔드 서버가 너무 많은 트래픽을 받아 더 이상 connection을 수립할 수 없음

504 Gateway Timeout #

Nignx가 백엔드 서버로 요청을 보내고 연결까지 성공했지만 백엔드 서버가 정해진 시간 내에 응답을 주지 못했을 때 발생한다.

nginx는 이 정도 기다렸으면 됐다 하고 클라이언트에게 504를 뱉는다.

  • 주요원인
    • 백엔드 서버에서 실행중인 로직이 복잡한 데이터베이스 쿼리나 무한루프등에 걸려 오래걸려 타임아웃남
    • 백엔드 서버가 의존하는 외부 api 호출이 지연되는 경우
    • nginx의 프록시 타임아웃 설정 proxy_read_timeout 시간이 너무 짧게 설정됨

즉 502는 백엔드 서버와 통신 불가능하고 비정상적인 상태의 응답이라 nginx가 연결도 하지 못한 상태고 해결방향은 백엔드 프로세스 재시작혹은 포트확인, 방화벽 점검등이 있다.

504는 백엔드 서버 응답이 너무 늦어 timeout이 난 상황이고 연결은 성공했으나 응답 대기중에 지쳐서 포기한상태다. 백엔드 로직 성능 튜닝, nginx 타임아웃을 늘려본다거나 그런 접근을 할 수 있다.


Nginx 프록시 설정 예시 (nginx.conf or default.conf) #

504 에러가 자주 발생하여 대기 시간을 늘려주거나, 502 에러를 방지하기 위해 백엔드 설정을 점검할때 사용하는 설정 파일 구조다.

http {
    # 백엔드 서버 그룹 정의 (502 에러 발생 시 여기 IP/Port 확인 필요)
    upstream backend_servers {
        server 127.0.0.1:8080; # 예: Spring Boot 또는 Node.js 포트
    }

    server {
        listen 80;
        server_name mywebsite.com;

        location /api/ {
            # 리버스 프록시 설정
            proxy_pass http://backend_servers;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;

            # 504 Gateway Timeout 방지를 위한 타임아웃 설정 (기본값 보통 60초)
            proxy_connect_timeout 90s; # 백엔드와 연결을 맺는 데까지 기다리는 시간
            proxy_send_timeout    90s; # 백엔드로 요청을 보내는 데까지 기다리는 시간
            proxy_read_timeout    120s; # 백엔드로부터 응답을 읽어오는 데까지 기다리는 시간 (중요!)
        }
    }
}

원인 파악 접근관련해서도 알아보자 에러 원인 파악을 위해 에러가 발생했을때 서버 터미널에서 즉각적으로 확인할 수 있는 명령어들을 보자.

# nginx 로그를 먼저 확인 
tail -f /var/log/nginx/error.log

# 502 예시
[error] 1234#0: *5678 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.10, server: mywebsite.com, request: "GET /api/data HTTP/1.1", upstream: "http://127.0.0.1:8080/api/data"

# 504 예시
[error] 1234#0: *5679 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 192.168.1.10, server: mywebsite.com, request: "GET /api/heavy-job HTTP/1.1", upstream: "http://127.0.0.1:8080/api/heavy-job"

포트 확인도 해주면 좋다

# 8080 포트가 정상적으로 열려있고 리스닝 중인지 확인
netstat -tulpn | grep 8080
# 또는
ss -tulpn | grep 8080

tcp  0  0 127.0.0.1:8080  0.0.0.0:* LISTEN  5432/java

위처럼 결과가 나오면 정상인데 아무것도 안뜨면 백 서버가 다운된 것이다.

SRE/question/q_37.md