502 Bad Gateway

이 오류의 의미와 확인 방법

• 브라우저에 502 Bad Gateway 또는 Bad Gateway가 표시되며, 경우에 따라 Nginx, Apache, Cloudflare 또는 다른 프록시의 브랜딩이 함께 표시됩니다.
• 여러 사용자에게 영향을 주거나, 배포 또는 설정 변경 후 시작되거나, 트래픽 증가 중에 나타납니다.
• 백엔드 worker, 메모리, CPU 또는 데이터베이스 연결이 고갈되면 간헐적으로 발생할 수 있습니다.
• 프록시 로그에 upstream 연결 실패, 타임아웃, 읽을 수 없는 status line, 잘못된 응답, 너무 큰 헤더 또는 소켓 오류가 기록됩니다.
• origin에 직접 요청하면 정상적으로 처리되지만 CDN을 통한 동일한 요청에서 502가 반환된다면 CDN-to-origin 액세스, firewall, TLS 또는 라우팅 문제일 가능성이 있습니다.

가능성이 높은 순서의 주요 원인

1. 중지되었거나 충돌하는 백엔드: PHP-FPM, Node.js, Gunicorn 또는 다른 애플리케이션 프로세스가 중지되었거나, crash loop 상태이거나, 배포 후 시작에 실패했습니다.
2. 백엔드 과부하 또는 타임아웃: worker, 메모리, CPU, 데이터베이스 연결 또는 다른 dependency가 고갈되어 프록시가 제때 응답을 가져오지 못합니다.
3. 잘못된 upstream 설정: 프록시가 잘못된 호스트, 포트, 컨테이너 주소, Unix socket 또는 애플리케이션 경로를 대상으로 합니다.
4. 소켓 또는 내부 firewall 액세스 실패: 소켓 권한, network policy, firewall 또는 security-group 변경으로 인해 프록시가 백엔드에 연결하지 못합니다.
5. 유효하지 않거나 너무 큰 백엔드 응답: 애플리케이션이 잘못된 출력, 사용할 수 없는 status line 또는 프록시가 허용할 수 있는 크기보다 큰 헤더를 전송합니다.
6. CDN-to-origin 연결 실패: CDN이 origin에 연결하지 못하거나 origin firewall에 의해 차단되었거나, origin 설정에서 요구하는 HTTPS 연결을 수립하지 못합니다.

해결 방법

1. 502가 어디에서 생성되는지 확인

오류 페이지에 Nginx, Apache, Cloudflare, hosting platform 또는 다른 중간 서버의 브랜딩이 표시되는지 확인하세요. 모든 route에서 오류가 발생하는지, 아니면 특정 애플리케이션 경로에서만 발생하는지 파악하고, 오류 발생 시간과 영향을 받은 URL을 기록하세요. 이렇게 하면 해당 요청을 올바른 로그와 대조할 수 있습니다.

2. 백엔드 프로세스와 로그 확인

권한이 있는 서버 또는 hosting-panel 액세스를 사용해 애플리케이션 프로세스가 실행 중이며 작업을 수락하고 있는지 확인하세요. crash loop, 치명적인 애플리케이션 오류, out-of-memory 종료, 누락된 dependency 또는 startup 실패가 로그에 기록되어 있는지 검토하세요.

예를 들어 읽기 전용 서비스 확인은 다음과 같습니다.

systemctl status php8.2-fpm
systemctl status nginx
pm2 status

설치된 PHP-FPM 버전과 process manager를 사용하세요. 위 이름을 그대로 복사하지 마세요. 백엔드가 중지되었거나 crash loop 상태라면 먼저 근본 원인을 해결하세요. 그런 다음에만 일반적인 변경 절차에 따라 해당 서비스를 재시작하는 것을 고려하세요. 재시작하면 요청이 중단되고 유용한 runtime context가 사라질 수 있으므로, 먼저 권한을 확인하고 관련 로그를 수집해야 합니다.

3. 프록시 오류 로그 확인

로그의 timestamp를 실패한 요청과 대조하세요. Nginx의 경우 일반적으로 /var/log/nginx/error.log에 해당하는 설정된 오류 로그를 확인합니다. mod_proxy 또는 mod_proxy_fcgi를 사용하는 Apache의 경우 Apache 오류 로그를 확인하세요.

다음과 같은 차이를 유용하게 확인할 수 있습니다.

• connect() failed: 프록시가 설정된 upstream에 연결할 수 없습니다.
• upstream timed out: 백엔드 또는 dependency 중 하나가 너무 느리거나 과부하 상태입니다.
• upstream sent too big header: 응답 헤더가 설정된 프록시 buffer 크기를 초과했습니다.
• status line을 읽는 중 발생한 오류: 백엔드가 연결을 종료했거나 유효하지 않은 응답을 반환했습니다.

정확한 로그 위치와 메시지 형식은 서버와 hosting platform에 따라 다릅니다.

4. upstream 호스트, 포트 또는 소켓 확인

reverse-proxy 설정을 검토하세요. Nginx에서는 proxy_pass 또는 upstream block을 확인합니다. Apache에서는 ProxyPass, ProxyPassMatch 및 PHP-FPM 연결 설정을 확인합니다.

필요한 경우 읽기 전용 listener 확인과 로컬 요청을 수행하세요.

ss -tlnp
curl http://127.0.0.1:PORT

PORT를 설정된 애플리케이션 포트로 바꾸세요. 애플리케이션이 Unix socket을 사용하는 경우 해당 경로가 존재하고 프록시 프로세스가 액세스할 수 있는지 확인하세요. PHP-FPM에서는 pool의 listen 설정이 Apache 또는 Nginx에 설정된 주소나 socket과 일치해야 합니다. 이 확인을 위해 내부 테스트 endpoint를 public으로 노출하지 마세요.

5. 과부하, dependency 및 타임아웃 조사

백엔드가 실행 중이지만 트래픽 급증이나 느린 요청과 함께 오류가 발생한다면 CPU, 메모리, worker 수, 데이터베이스 연결, queue depth 및 hosting-panel 리소스 제한을 확인하세요. 프로세스가 실행 중이어도 추가 작업을 수락하지 못할 수 있습니다.

근거 없이 프록시 타임아웃이나 buffer 크기를 늘리지 마세요. 로그에서 너무 큰 헤더가 확인되면 애플리케이션 응답을 조사하고 관련 Nginx proxy_buffer_size 및 proxy_buffers 설정을 검토하세요. 설정 변경이 필요하다면 승인된 변경 절차에 따라 검증하고 적용하세요. 권한 없이 production 프록시를 reload하지 마세요.

6. origin과 CDN 경로 비교

Cloudflare 또는 다른 CDN이 사이트 앞에 있는 경우, 권한을 확인한 후 올바른 origin 주소와 Host header를 사용해 origin에 직접 요청하세요. 그 결과를 public 요청 결과와 비교합니다.

• origin에서도 실패: origin의 애플리케이션, 프록시, 소켓, 포트, firewall 및 리소스 상태를 조사하세요.
• origin은 정상이나 CDN에서 실패: CDN-to-origin firewall 규칙, origin 연결 가능성, 라우팅 및 CDN의 origin SSL/TLS mode를 확인하세요. origin이 CDN이 요구하는 protocol과 certificate 설정을 제공하는지 확인합니다.

7. 원인 수정 후 재테스트

먼저 origin이 예상한 응답을 반환하는지 확인하세요. 그런 다음 reverse proxy 또는 CDN을 통해 요청을 테스트합니다. 일부 URL에서만 실패한다면 문제를 전체 장애로 간주하지 말고 해당 URL의 애플리케이션 route, 응답 크기, 인증 요구 사항 및 백엔드 dependency를 비교하세요.

8. hosting-panel 제한 확인

cPanel, Plesk 또는 유사한 shared hosting 환경에서는 PHP-FPM 및 resource-usage 로그를 검토하세요. 계정이 provider가 적용한 process, 메모리 또는 동시성 제한에 도달했을 수 있습니다. 제한을 변경할 수 없다면 오류 발생 시간, 영향을 받은 route 및 관련 로그 메시지를 hosting provider에 전달하여 infrastructure-level 기록을 확인하도록 요청하세요.

예방 및 해결 확인 방법

• 애플리케이션을 process supervision 환경에서 실행하고, 자동 재시작에만 의존하지 말고 반복되는 충돌을 모니터링하세요.
• 요청에 영향을 주기 전에 메모리, CPU, worker 사용량, 데이터베이스 연결, queue depth 및 hosting-panel 제한을 모니터링하세요.
• 애플리케이션, 프록시, load balancer 및 CDN 사이에 의도적이고 호환되는 타임아웃을 설정하세요. 상태가 좋지 않은 백엔드를 숨기기 위해 타임아웃을 무작정 늘리지 마세요.
• 배포 및 설정 변경 후 예상되는 애플리케이션 포트 또는 socket을 확인하세요.
• origin TLS, firewall 규칙 또는 프록시 설정을 변경한 후 대표적인 route를 origin에 직접 연결하고 CDN을 통해 테스트하세요.
• 간헐적인 502 응답을 백엔드 이벤트와 대조할 수 있도록 프록시 및 애플리케이션 로그를 동기화된 timestamp와 함께 보관하세요.
• 해당 환경의 담당 service, upstream 주소, socket 권한 및 승인된 복구 절차를 문서화하세요.

자주 묻는 질문