여기서는 멈추세요
- 명령 출력의 서버·서비스·경로가 예상 대상과 다르면 변경 단계로 넘어가지 않습니다.
- 현재 접속 세션, 백업 또는 콘솔 복구 경로를 확보하지 못했다면 상태 변경 명령을 실행하지 않습니다.
WEB GATEWAY
NGINX 502·504 오류를 진단할 때
프록시 자체, upstream 포트, 애플리케이션 응답과 타임아웃을 분리해 확인합니다.502 Bad Gateway504 Gateway Timeoutnginxupstream프록시 오류
환경NGINX reverse proxy · systemd 애플리케이션
분류웹·보안
검토일2026-08-27
진행5단계 · 조회 우선
SAFE OPERATING BOUNDARY
중단·복구 기준부터 확인하세요
복구 기준
변경 전 설정과 출력값을 기록하고, 예상과 다른 결과가 나오면 추가 변경을 멈춘 뒤 승인된 운영 복구 절차로 되돌립니다.
담당자에게 전달할 자료
- 장애 발생 시각·정상화 시각과 원문 오류 메시지
- 민감정보를 제거한 조회 명령 출력과 변경 전후 차이
- 조치 후 동일 조건으로 수행한 재검증 결과
BEFORE YOU START
이런 증상에서 시작합니다
- 502 Bad Gateway
- 504 Gateway Timeout
- 배포 후 프록시 실패
CHECK THE BRANCH
놓치기 쉬운 원인 분기
connect() failed 또는 refused
upstream 미기동, 포트 불일치, 주소 바인딩 문제를 우선 확인합니다. 타임아웃을 늘려도 해결되지 않습니다.
upstream timed out
upstream이 연결 또는 응답 제한 시간 안에 처리하지 못한 경우입니다. DB·외부 API·애플리케이션 지연을 먼저 측정합니다.
upstream prematurely closed connection
애플리케이션 종료, OOM, 예외 또는 응답 중 연결 종료를 의심하고 같은 시각의 upstream 로그를 대조합니다.
FOLLOW THE FLOW
순서대로 확인하기
조회시스템을 변경하지 않는 확인 단계
NGINX 설정과 상태 확인
먼저 프록시 설정 자체가 유효한지 봅니다.
설정 문법 검사
sudo nginx -t서비스 상태
systemctl status nginx --no-pager -l결과 읽기
syntax is ok와 test is successful이 모두 나와야 합니다.
다음 판단
실패하면 reload하지 말고 표시된 파일과 줄을 수정합니다.
조회시스템을 변경하지 않는 확인 단계
오류 로그에서 upstream 원인 확인
장애 시각 주변의 첫 upstream 오류를 찾습니다.
최근 NGINX 오류
sudo tail -n 120 /var/log/nginx/error.log현재 부팅 로그
journalctl -u nginx -b -n 100 --no-pager결과 읽기
Connection refused는 미기동·포트 불일치, timed out은 지연·타임아웃 가능성이 큽니다.
다음 판단
로그에 표시된 upstream 주소와 포트를 기록합니다.
조회시스템을 변경하지 않는 확인 단계
upstream 포트와 직접 응답 확인
예시 3000을 실제 upstream 포트로 바꿉니다.
포트 리스닝 확인
sudo ss -lntp | grep ':3000 '로컬 직접 요청
curl -i --max-time 10 http://127.0.0.1:3000/결과 읽기
직접 요청도 실패하면 NGINX가 아니라 애플리케이션 문제입니다.
다음 판단
애플리케이션 서비스 로그로 이동합니다.
조회시스템을 변경하지 않는 확인 단계
애플리케이션 상태 확인
SERVICE_NAME을 실제 upstream unit으로 바꿉니다.
upstream 서비스
systemctl status SERVICE_NAME --no-pager -l최근 로그
journalctl -u SERVICE_NAME --since '-15 min' --no-pager결과 읽기
재시작 루프, DB 연결 실패, 메모리 종료 여부를 확인합니다.
다음 판단
원인을 수정하고 로컬 직접 요청이 성공하는지 먼저 봅니다.
변경데이터·서비스 상태가 달라질 수 있는 단계
안전하게 반영하고 외부 검증
nginx -t가 성공한 경우에만 reload합니다.
변경 단계입니다. 실행 전 대상 이름과 경로, 서비스 중단 영향, 복구 방법을 다시 확인하세요.
무중단 설정 반영
sudo systemctl reload nginx외부 헤더 확인
curl -I --max-time 10 https://example.com/결과 읽기
정상 상태 코드와 응답 시간, 오류 로그 미증가를 확인합니다.
다음 판단
504가 반복되면 타임아웃을 늘리기 전에 upstream 지연 원인을 분석합니다.
PRIMARY REFERENCES
공식 문서
- NGINX 공식 관리자 가이드
- curl 공식 매뉴얼
- systemd systemctl 공식 매뉴얼
- systemd journalctl 공식 매뉴얼
- NGINX — proxy module
배포판과 버전에 따라 옵션·로그 위치가 다를 수 있습니다. 실행 전 서버의 --help와 로컬 매뉴얼을 함께 확인하세요.