Nginx 502 Bad Gateway 오류 수정: 단계별 가이드
Nginx 502 오류를 추적하려면 설정, 업스트림 상태, 로그, 소켓, Docker 네트워킹 및 타임아웃 증상을 확인하세요.
Nginx 502 Bad Gateway 오류 수정: 단계별 가이드
Nginx 502 Bad Gateway 오류를 수정하려면 Nginx가 일반적으로 메신저일 뿐이며, 실패의 원천이 아니라는 점을 이해하는 것에서 시작합니다. 502는 Nginx가 업스트림 서비스와 통신을 시도했지만 유효한 응답을 받지 못했음을 의미합니다.
해당 업스트림 서비스는 Node.js 앱, PHP-FPM, Gunicorn, Puma, 컨테이너 또는 다른 HTTP 서버일 수 있습니다. 여러분의 임무는 핸드오프가 실패하는 지점을 찾는 것입니다.
Nginx에서 502 Bad Gateway의 의미
Nginx는 일반적으로 애플리케이션 서버 앞에 위치합니다. 공개 트래픽을 수락하고, TLS를 처리하며, 정적 파일을 제공하고, 동적 요청을 업스트림으로 전달합니다.
업스트림 연결이 실패하거나 Nginx가 사용할 수 없는 응답을 반환할 때 502가 나타납니다. 일반적인 원인은 다음과 같습니다:
- 애플리케이션 프로세스가 중지되었습니다.
- Nginx가 잘못된 포트나 소켓을 가리키고 있습니다.
- Unix 소켓에 잘못된 권한이 있습니다.
- 업스트림 서비스가 요청 중에 충돌합니다.
- 방화벽이나 컨테이너 네트워크가 연결을 차단합니다.
- 업스트림이 유효하지 않은 HTTP 응답을 보냅니다.
실패하는 정확한 요청 경로부터 시작하세요. /api만 502를 반환하고 정적 페이지가 로드된다면, 정적 파일 제공은 정상이며 프록시나 앱 백엔드가 문제일 가능성이 높습니다. 모든 페이지가 실패한다면, 문제는 더 광범위한 Nginx, DNS 또는 업스트림 가용성 문제일 수 있습니다.
1단계: Nginx 상태 및 설정 확인
먼저 Nginx가 실행 중인지 확인합니다:
systemctl status nginx
그런 다음 설정을 테스트합니다:
nginx -t
설정 테스트가 실패하면 애플리케이션을 추적하기 전에 먼저 수정하세요. Nginx가 이전 설정으로 계속 실행 중일 수 있거나, 리로드 시 실패할 수 있습니다.
설정 테스트가 성공한 후 Nginx를 리로드합니다:
systemctl reload nginx
영향을 이해하지 못한 채 바쁜 서버에서 무턱대고 재시작하지 마세요. 설정 변경 후 리로드는 일반적으로 충분하며 덜 방해가 됩니다.
다음으로, 활성 서버 블록을 검사합니다. proxy_pass, fastcgi_pass 또는 uwsgi_pass를 찾으세요. 일반적인 리버스 프록시는 다음과 같을 수 있습니다:
location / {
proxy_pass http://127.0.0.1:3000;
}
이는 Nginx가 로컬 포트 3000에서 애플리케이션을 예상한다는 의미입니다. 앱이 실제로 3001에서 수신 대기 중이거나 Docker 네트워크 내부에서만 수신 대기 중이라면 Nginx는 실패합니다.
더 많은 명령 중심 확인은 Nginx 설정 테스트 명령어를 참조하세요.
2단계: 업스트림 서비스 확인
이제 Nginx 호스트에서 직접 업스트림을 테스트합니다. Nginx가 127.0.0.1:3000으로 프록시하는 경우 다음을 실행합니다:
curl -i http://127.0.0.1:3000/
실패하면 문제는 브라우저나 공개 DNS가 아닙니다. 백엔드가 다운되었거나, 다른 곳에서 수신 대기 중이거나, 요청을 거부하기 때문에 Nginx가 백엔드에 도달할 수 없습니다.
애플리케이션 프로세스를 확인합니다:
ss -ltnp
예상 포트를 찾으세요. 서비스가 Unix 소켓을 사용하는 경우 소켓 경로를 확인합니다:
ls -l /run/app/app.sock
Nginx 작업자 사용자가 해당 소켓에 액세스할 수 있어야 합니다. 많은 Linux 시스템에서 Nginx는 www-data, nginx 또는 서비스별 사용자로 실행됩니다. 소켓이 다른 사용자 소유이고 필요에 따라 그룹 읽기 또는 쓰기가 가능하지 않으면 Nginx가 권한 오류를 기록하고 502를 반환할 수 있습니다.
PHP-FPM 설정의 경우 풀이 실행 중인지 확인합니다:
systemctl status php-fpm
서비스 이름에는 배포판에 따라 php8.2-fpm과 같은 버전이 포함될 수 있습니다.
3단계: Nginx 오류 로그 읽기
Nginx 오류 로그는 일반적으로 어떤 실패 모드를 다루고 있는지 알려줍니다. 일반적인 로그 메시지는 다음과 같습니다:
connect() failed (111: Connection refused) while connecting to upstream
이는 Nginx가 호스트에 도달했지만 해당 포트에서 연결을 수락하는 것이 없음을 의미합니다.
upstream timed out while reading response header from upstream
이는 Nginx가 연결되었지만 백엔드가 제 시간에 응답하지 않았음을 의미합니다.
permission denied while connecting to upstream
이는 종종 Unix 소켓 권한이나 SELinux와 같은 보안 제어를 가리킵니다.
최근 오류를 확인하려면:
tail -n 100 /var/log/nginx/error.log
systemd 기반 시스템에서는 다음을 확인할 수도 있습니다:
journalctl -u nginx -n 100
로그의 타임스탬프를 브라우저 요청 시간과 일치시키세요. 이렇게 하면 더 이상 관련 없는 오래된 오류를 추적하지 않게 됩니다.
더 깊은 로그 작업 흐름은 Nginx 오류 로그 분석을 참조하세요.
4단계: 가장 일반적인 근본 원인 수정
실패 모드를 알게 되면, 그에 맞는 가장 작은 수정을 적용하세요.
앱이 실행 중이 아닌 경우 애플리케이션 서비스를 시작하거나 재시작합니다:
systemctl restart your-app
그런 다음 Nginx를 통해 테스트하기 전에 curl로 업스트림을 테스트합니다.
Nginx가 잘못된 포트를 가리키는 경우 proxy_pass 대상을 업데이트하고 Nginx를 리로드합니다. 앱과 Nginx가 IPv4 대 IPv6에 대해 일치하는지도 확인하세요. 127.0.0.1에서 수신 대기하는 앱은 ::1에서만 수신 대기하는 앱과 다릅니다.
Docker가 관련된 경우 Nginx가 호스트에서 실행되는지 컨테이너 내부에서 실행되는지 확인합니다. 컨테이너 내부의 127.0.0.1은 해당 컨테이너를 가리키며 호스트가 아닙니다. Docker 서비스 이름, 브리지 네트워크 또는 게시된 포트가 필요할 수 있습니다.
업스트림이 타임아웃되면 애플리케이션 로그를 확인합니다. 백엔드가 데이터베이스 쿼리, 외부 API 호출 또는 시작 작업에 막혀 있을 수 있습니다. Nginx 타임아웃을 늘리면 증상이 숨겨질 수 있지만, 손상되었거나 과부하된 앱을 수정하지는 않습니다.
전문가에게 문의해야 할 때
502 오류가 프로덕션에 영향을 미치고 로그, 업스트림 상태 및 최근 배포를 확인한 후에도 원인이 명확하지 않은 경우 시니어 엔지니어나 호스팅 제공업체에 문의하세요. 또한 문제가 로드 밸런서, 컨테이너 오케스트레이션, SELinux 정책 또는 높은 트래픽 타임아웃 튜닝과 관련된 경우 도움을 받으세요.
프로덕션 시스템의 경우 반복적인 무작위 재시작을 피하세요. 이는 증거를 지우고 중단을 이해하기 더 어렵게 만들 수 있습니다.
502 Bad Gateway 오류는 요청 경로를 순서대로 추적하면 수정할 수 있습니다. Nginx가 유효한지 확인하고, 업스트림을 직접 테스트하고, 정확한 오류 로그 줄을 읽고, 실패에 맞는 수정을 적용하세요. 이 접근 방식은 타임아웃을 변경하거나 서비스를 무작정 재시작하는 것보다 더 빠르고 안전합니다.