nginx: upstream에서 오는 502 Bad Gateway

안녕하세요, BlueByte입니다. nginx의 502 Bad Gateway는 nginx 자체는 멀쩡하다는 뜻입니다 — 뒤에 있는 upstream이 응답하지 않았거나, nginx가 쓸 수 없는 응답을 보낸 것입니다. 증상은 nginx -t는 통과하는데도 nginx가 502를 돌려주는 것입니다. 오늘은 502가 실제로 뜻하는 것, error log를 읽어 정확한 실패를 찾는 법, 원인별 해결, 그리고 예방까지 하나씩 짚어보겠습니다.

nginx의 502가 실제로 뜻하는 것

브라우저에는 짧은 페이지가 뜨고 access log에는 상태 코드가 기록됩니다:

203.0.113.7 - - [04/Sep/2026:11:20:03 +0900] "GET /api HTTP/1.1" 502 552 "-" "curl/8.4.0"

nginx는 요청을 받아 proxy_pass에 지정된 서버로 프록시하려 했지만, 연결하지 못했거나 유효하지 않다고 판단한 응답을 받았습니다. 이것은 nginx가 죽은 것이 아닙니다 — nginx는 살아서 응답하고 있고, 그 뒤의 게이트웨이가 문제입니다. 그래서 nginx를 재시작해도 대개 도움이 안 됩니다.

upstream을 못 쓰게 만드는 네 가지

502는 다음 중 하나에서 옵니다:

• upstream이 실행 중이 아님 또는 proxy_pass의 주소에서 리슨하지 않음 — 연결이 거부됨.
• proxy_pass가 틀린 호스트·포트·소켓을 가리킴 — nginx가 아무것도 없는 곳에 연결.
• upstream이 응답 도중 크래시하거나 연결을 닫음 — nginx가 비었거나 잘린 응답을 읽음.
• upstream의 응답 헤더가 proxy_buffer_size(기본 4k/8k)보다 큼 — nginx가 유효하지 않다고 거부.

살아 있지만 느린 upstream은 별개의 오류입니다 — 그건 504이며, 끝에서 다룹니다.

error log 읽기 — 정확한 실패를 알려준다

access log는 502를 보여주고, error log는 이유를 말해줍니다. 요청을 재현하면서 지켜보세요:

sudo tail -f /var/log/nginx/error.log

2026/09/04 11:20:03 [error] 812#812: *5 connect() failed (111: Connection refused)
  while connecting to upstream, client: 203.0.113.7, upstream: "http://127.0.0.1:8000/api"

괄호 안을 읽으세요. (111: Connection refused)는 리슨하는 게 없다는 뜻, upstream prematurely closed connection은 앱이 응답 도중 죽었다는 뜻, upstream sent too big header는 헤더가 버퍼를 넘쳤다는 뜻, (13: Permission denied)는 RHEL에서 보통 SELinux가 아웃바운드 연결을 막는다는 뜻입니다. upstream: 필드는 nginx가 시도한 정확한 주소를 출력하니, 앱이 실제로 리슨하는 곳과 맞는지 확인하세요.

원인별로 고치기: 죽은 upstream·틀린 주소·큰 헤더

1. upstream이 리슨하지 않음 — 포트에 무엇이 있는지 확인하고 앱을 시작합니다:

ss -ltnp | grep :8000
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/api

curl도 실패하면 nginx는 죄가 없습니다 — 앱을 고치세요. 정상 upstream은 200을 출력합니다.

2. 틀린 proxy_pass — 실제 주소로 가리키고 reload합니다:

location /api {
    proxy_pass http://127.0.0.1:8000;
}

3. 헤더가 너무 큼 — 해당 location의 버퍼를 키웁니다:

proxy_buffer_size 16k;
proxy_buffers 8 16k;

실제 사례: 앱이 죽어 소켓이 끊긴 경우

nginx 뒤의 Node 앱이 502를 내기 시작합니다. nginx -t는 정상이라 tail -f /var/log/nginx/error.log를 실행하니 connect() failed (111: Connection refused) while connecting to upstream: "http://127.0.0.1:3000/"가 보입니다. ss -ltnp | grep :3000을 실행하면 리슨하는 게 없습니다 — 앱 프로세스가 밤사이 종료돼 포트가 비었습니다. systemctl restart myapp으로 서비스를 재시작하고, curl http://127.0.0.1:3000/이 200을 돌려주자 502가 즉시 멈춥니다. nginx는 처음부터 사실을 보고하고 있었습니다: 닿을 게이트웨이가 없었던 것입니다.

프록시 경로를 끝까지 확인하기

설정을 검사하고 reload한 뒤 nginx를 통해 요청합니다:

sudo nginx -t && sudo nginx -s reload
curl -I https://example.com/api

HTTP/1.1 200 OK

공개 URL을 통해 200(또는 앱의 정상 상태)이 나오면 nginx가 upstream에 닿아 응답을 되돌려준 것입니다. 테스트하는 동안 error log를 열어 두세요 — 정상 요청은 새 [error] 줄을 남기지 않습니다.

502가 다시 생기지 않게 하기

upstream을 supervisor 아래에서 실행하세요 — systemd, 컨테이너 재시작 정책, 또는 프로세스 매니저 — 그러면 크래시가 나도 죽은 포트를 남기지 않고 재시작합니다. 헬스 체크를 추가해, 준비되지 않은 백엔드가 502를 내기 전에 로테이션에서 빠지게 하세요. RHEL/SELinux 호스트에서는 sudo setsebool -P httpd_can_network_connect 1로 nginx의 아웃바운드 연결을 한 번 허용하세요. proxy_buffer_size는 앱이 보내는 가장 큰 헤더에 맞춰 잡으세요 — 지나치게 큰 auth 토큰과 쿠키가 흔한 오버플로 원인입니다. 502가 간헐적이고 로그에 upstream prematurely closed connection이 보이면, 백엔드가 nginx가 재사용하기 전에 유휴 keepalive 연결을 닫고 있을 가능성이 큽니다 — proxy_http_version 1.1과 upstream의 keepalive 개수를 설정하거나, nginx가 오래된 연결을 고르지 않도록 백엔드의 유휴 타임아웃을 줄이세요.

502는 504와 무엇이 다른가

502 Bad Gateway는 upstream에 닿지 못했거나 유효하지 않은 응답을 받았다는 뜻입니다 — 연결이 실패했거나 응답이 깨진 것입니다. 504 Gateway Timeout은 upstream에 닿기는 했지만 너무 느렸다는 뜻입니다: proxy_connect_timeout·proxy_send_timeout·proxy_read_timeout(각 기본 60s) 안에 응답하지 않은 것입니다. error log가 upstream timed out이라고 하면 해당 타임아웃을 늘리거나 백엔드를 빠르게 만드세요 — 그건 504이지 502가 아닙니다.