Nginx 502 Bad Gateway 오류 해결: IT 관리자를 위한 완벽 가이드
웹 서비스 운영 중 Nginx에서 "502 Bad Gateway" 오류를 마주하는 것은 흔한 일입니다. 이 오류는 사용자 경험을 저해하고 서비스 가용성을 떨어뜨리므로 신속한 해결이 중요합니다. 이 글에서는 502 Bad Gateway 오류의 원인을 분석하고, 단계별 해결 방법과 예방 조치를 상세히 안내합니다.
목차
에러 현상
웹 브라우저에서 다음과 같은 오류 메시지를 보게 됩니다:
502 Bad Gateway
nginx/1.18.0 (Ubuntu)
또는 다음과 같은 메시지가 표시될 수도 있습니다:
Bad Gateway
The server returned an invalid or incomplete response.
이 오류는 Nginx 서버가 upstream 서버(예: 백엔드 API 서버, WAS)로부터 유효한 응답을 받지 못했을 때 발생합니다. 주로 웹 서비스의 프론트엔드 역할을 하는 Nginx가 백엔드 서버와 통신하는 과정에서 문제가 발생했을 때 나타납니다. 발생 환경은 Ubuntu, CentOS 등 다양한 Linux 배포판에서 Nginx를 사용하는 환경이며, 특히 트래픽이 많은 서비스에서 자주 발생할 수 있습니다.
원인 분석
502 Bad Gateway 오류는 다양한 원인으로 발생할 수 있습니다. 주요 원인과 빈도 순으로 분석해 보겠습니다.
1. 다운 또는 과부하
가장 흔한 원인은 Nginx가 프록시하는 upstream 서버가 다운되었거나 과부하 상태인 경우입니다. 서버가 다운되면 Nginx는 응답을 받을 수 없으므로 502 오류를 반환합니다. 과부하 상태에서는 서버가 요청을 처리하는 데 시간이 오래 걸리거나 응답을 제대로 생성하지 못할 수 있습니다. upstream 서버의 CPU, 메모리 사용량이 높거나, 네트워크 연결에 문제가 있는 경우에도 발생할 수 있습니다.
2. 잘못된 설정
Nginx 설정 파일 (nginx.conf)의 proxy_pass 설정이 잘못된 경우에도 502 오류가 발생할 수 있습니다. proxy_pass는 Nginx가 요청을 전달할 upstream 서버의 주소와 포트를 지정하는 지시어입니다. 주소가 잘못되었거나, 포트 번호가 틀렸거나, upstream 서버가 응답하지 않는 경우 502 오류가 발생합니다. upstream 서버의 URL 스킴(http/https)이 일치하지 않는 경우에도 문제가 발생할 수 있습니다.
3. 또는 네트워크 문제
방화벽 설정이나 네트워크 문제로 인해 Nginx와 upstream 서버 간의 통신이 차단될 수 있습니다. 방화벽이 Nginx 서버에서 upstream 서버로의 트래픽을 막거나, upstream 서버에서 Nginx 서버로의 응답을 막는 경우 502 오류가 발생합니다. 또한, 네트워크 장비(라우터, 스위치 등)의 설정 오류나 네트워크 케이블의 문제로 인해 통신이 불가능할 수도 있습니다.
4. Nginx 설정 오류 (버퍼 크기, 타임아웃 등)
Nginx 설정 중 버퍼 크기나 타임아웃 설정이 너무 낮게 설정되어 있는 경우, upstream 서버의 응답이 느려지면 Nginx가 응답을 기다리지 못하고 502 오류를 반환할 수 있습니다. 특히 큰 파일을 전송하거나, 응답 시간이 오래 걸리는 API를 사용하는 경우에 문제가 될 수 있습니다.
해결 방법
각 원인별로 502 Bad Gateway 오류를 해결하는 방법을 단계별로 안내합니다.
1. 상태 확인 및 복구
upstream 서버가 정상적으로 작동하는지 확인하는 것이 가장 중요합니다.
-
upstream 서버에 직접 접속하여 서버 프로세스가 실행 중인지 확인합니다.
bash ssh user@upstream_server_ip sudo systemctl status your_app_service정상 작동 시 다음과 유사한 결과가 나타납니다.
● your_app_service.service - Your Application Service Loaded: loaded (/etc/systemd/system/your_app_service.service; enabled; vendor preset: enabled) Active: active (running) since Tue 2023-10-24 10:00:00 UTC; 1h ago Main PID: 1234 (your_app) Tasks: 20 Memory: 100.0M CPU: 10.000s CGroup: /system.slice/your_app_service.service
* 서버가 다운된 경우, 서버를 재시작하거나 필요한 서비스를 다시 시작합니다.bash sudo systemctl restart your_app_service
* 서버가 과부하 상태인 경우, 서버의 CPU, 메모리 사용량을 줄이거나, 서버를 증설합니다. 로드 밸런서를 사용하여 트래픽을 분산하는 것도 좋은 방법입니다.```bash
CPU 사용량 확인
top
메모리 사용량 확인
free -m
```
2. 설정 확인 및 수정
Nginx 설정 파일 (nginx.conf)에서 proxy_pass 설정이 올바른지 확인합니다.
-
upstream 서버의 주소와 포트가 정확하게 입력되었는지 확인합니다.
nginx location / { proxy_pass http://upstream_server_ip:upstream_server_port; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }
* upstream 서버가 HTTPS를 사용하는 경우, proxy_pass URL도 HTTPS로 시작해야 합니다.
* proxy_pass 뒤에 trailing slash(/)가 필요한지 확인합니다. location 블록에 slash가 있다면, proxy_pass에는 slash가 없어야 합니다. 반대로 location 블록에 slash가 없다면, proxy_pass에는 slash가 있어야 합니다.
* 설정 변경 후 Nginx를 재시작하여 변경 사항을 적용합니다.bash sudo nginx -t # 설정 파일 문법 오류 확인 sudo systemctl restart nginx
3. 설정 확인 및 수정
방화벽이 Nginx와 upstream 서버 간의 통신을 차단하고 있는지 확인합니다.
-
Nginx 서버와 upstream 서버 간의 방화벽 규칙을 확인하여 필요한 포트가 열려 있는지 확인합니다. 일반적으로 HTTP는 80포트, HTTPS는 443포트를 사용합니다. upstream 서버가 다른 포트를 사용하는 경우, 해당 포트도 열려 있어야 합니다.
```bash
UFW 방화벽 상태 확인 (Ubuntu)
sudo ufw status
방화벽 포트 열기
sudo ufw allow 80
sudo ufw allow 443
sudo ufw enable
``````powershell
PowerShell을 사용하여 Windows 방화벽 규칙 확인
Get-NetFirewallRule | Where-Object {$_.DisplayName -like "nginx
'B2B Solution > 트러블슈팅' 카테고리의 다른 글
| Docker 컨테이너 빌드 실패! 원인 분석 및 해결 가이드 (Dockerfile 오류, 권한 문제) (0) | 2026.03.07 |
|---|---|
| 쿠버네티스 Pod CrashLoopBackOff 완벽 해결 가이드 (원인 분석 및 단계별 조치) (0) | 2026.03.07 |
| SSH 접속 시 "Permission denied" 에러 완벽 해결 가이드 (원인 분석 & 단계별 조치) (0) | 2026.03.05 |
| SSL 인증서 오류 해결 가이드: IT 관리자를 위한 완벽 분석 및 해결책 (0) | 2026.03.02 |
| macOS - 맥북 Python version 2.7에서 최신 3.xx 변경 방법 (2) | 2021.10.28 |