기술자료

적용 환경

가장 먼저 확인할 항목

먼저 Nginx 프로세스가 실행 중인지 확인합니다. 502 응답이 실제로 Nginx에서 반환되고 있다면 Nginx 자체는 동작 중인 경우가 많지만, 서비스 상태와 최근 오류를 함께 확인하면 진단 범위를 빠르게 좁힐 수 있습니다.

sudo systemctl status nginx --no-pager -l

정상적으로 실행 중이라면 서비스 상태에서 active (running)을 확인할 수 있습니다. Nginx가 실행되지 않는다면 502 문제를 분석하기 전에 Nginx의 시작 실패 원인부터 확인해야 합니다.

다음으로 현재 Nginx 설정 문법을 검사합니다.

sudo nginx -t

문법 검사가 성공해야 이후 설정 변경을 안전하게 다시 적용할 수 있습니다. 검사에 실패하면 출력되는 파일 경로와 줄 번호를 확인하여 먼저 설정 오류를 수정하십시오.

Nginx 오류 로그로 원인 확인

502 오류의 원인을 찾을 때 가장 먼저 볼 파일은 Nginx 오류 로그입니다. Ubuntu의 일반적인 패키지 구성에서는 /var/log/nginx/error.log를 확인할 수 있으며, 개별 가상 호스트에서 별도의 error_log 경로를 지정했다면 해당 파일을 확인해야 합니다.

최근 로그를 확인합니다.

sudo tail -n 100 /var/log/nginx/error.log

오류를 재현하면서 실시간으로 로그를 확인하려면 다음 명령을 사용할 수 있습니다.

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

systemd 저널의 Nginx 기록도 함께 확인하면 서비스 재시작 실패나 설정 로딩 문제를 찾는 데 도움이 됩니다.

sudo journalctl -u nginx --since "30 minutes ago" --no-pager

로그에 연결 거부, 업스트림 타임아웃, Unix 소켓을 찾지 못함, 권한 거부와 관련된 내용이 나타난다면 다음 단계에서 해당 업스트림의 상태와 실제 연결 지점을 확인합니다.

업스트림 서비스 상태 확인

Nginx가 리버스 프록시로 동작한다면 실제 웹 애플리케이션이 실행 중이어야 합니다. 예를 들어 Nginx 설정의 proxy_pass가 http://127.0.0.1:3000을 가리킨다면 127.0.0.1의 3000번 포트에서 백엔드 서비스가 실제로 요청을 받고 있어야 합니다.

현재 설정에서 HTTP 업스트림을 찾습니다.

sudo grep -R "proxy_pass" /etc/nginx/sites-enabled /etc/nginx/conf.d 2>/dev/null

확인된 주소가 예를 들어 127.0.0.1:3000이라면 Nginx를 거치지 않고 서버 내부에서 업스트림에 직접 요청해 봅니다.

curl -v http://127.0.0.1:3000/

직접 요청도 연결되지 않는다면 Nginx보다 백엔드 서비스의 중단, 잘못된 포트, 잘못된 바인딩 주소 또는 애플리케이션 자체 오류를 먼저 해결해야 합니다. 백엔드가 systemd 서비스라면 실제 서비스 이름을 확인한 뒤 다음과 같이 상태와 로그를 확인합니다.

sudo systemctl status YOUR_BACKEND_SERVICE --no-pager -l
sudo journalctl -u YOUR_BACKEND_SERVICE -n 100 --no-pager

YOUR_BACKEND_SERVICE는 실제 애플리케이션 서비스 이름으로 바꾸십시오. 서비스가 반복적으로 종료된다면 애플리케이션 로그와 메모리 부족 여부까지 함께 확인해야 합니다.

포트와 Unix 소켓 확인

TCP 포트를 사용하는 경우

백엔드 프로세스가 Nginx 설정에 지정된 포트에서 실제로 대기 중인지 확인합니다.

sudo ss -lntp

예를 들어 Nginx가 127.0.0.1:3000으로 요청을 전달하도록 설정되어 있는데 실제 애플리케이션은 8000번 포트에서 실행 중이라면 proxy_pass 주소와 실제 서비스 포트를 일치시켜야 합니다.

PHP-FPM과 Unix 소켓을 사용하는 경우

PHP 사이트에서는 fastcgi_pass가 Unix 소켓을 가리키는 경우가 많습니다. 현재 Nginx 설정에서 FastCGI 연결 위치를 확인합니다.

sudo grep -R "fastcgi_pass" /etc/nginx/sites-enabled /etc/nginx/conf.d 2>/dev/null

Ubuntu 22.04의 기본 PHP 계열을 사용하는 환경에서는 PHP 버전에 따라 /run/php/ 아래에 FPM 소켓이 생성될 수 있습니다. 실제 파일을 확인하고 Nginx 설정의 소켓 경로와 일치하는지 비교합니다.

ls -l /run/php/

PHP-FPM이 설치된 경우 현재 설치된 FPM 서비스도 확인할 수 있습니다.

systemctl list-units --type=service --all 'php*-fpm.service'

Nginx가 존재하지 않는 이전 PHP 버전의 소켓을 가리키고 있다면 실제 FPM 소켓 경로로 수정해야 합니다. 소켓 파일은 존재하지만 권한 관련 오류가 발생한다면 PHP-FPM 풀의 소켓 소유자·그룹·권한과 Nginx 워커 사용자를 함께 확인하십시오.

Nginx 업스트림 설정 확인

Ubuntu에서 Nginx의 주 설정 파일은 일반적으로 /etc/nginx/nginx.conf이며, 사이트별 설정은 /etc/nginx/sites-available/에 두고 /etc/nginx/sites-enabled/에서 활성화하는 구성이 일반적입니다. 실제로 로드되는 전체 설정을 확인하려면 다음 명령이 유용합니다.

sudo nginx -T

리버스 프록시 환경에서는 proxy_pass의 호스트와 포트가 실제 백엔드와 일치해야 합니다. 아래는 형식을 보여 주기 위한 예시입니다.

location / {
    proxy_pass http://127.0.0.1:3000;
}

FastCGI 환경에서는 fastcgi_pass의 소켓 또는 TCP 주소가 실제 PHP-FPM 설정과 일치해야 합니다. 아래 경로는 예시이므로 서버의 /run/php/에 존재하는 실제 소켓을 기준으로 설정해야 합니다.

fastcgi_pass unix:/run/php/php8.1-fpm.sock;

설정을 수정했다면 반드시 문법을 먼저 검사합니다.

sudo nginx -t

검사가 성공한 경우에만 기존 연결을 가능한 한 유지하면서 설정을 다시 읽도록 reload를 수행합니다.

sudo systemctl reload nginx

응답 지연과 타임아웃 확인

업스트림이 정상적으로 연결되지만 특정 요청에서만 502 오류가 발생한다면 응답 지연을 확인해야 합니다. Nginx 공식 문서에서 proxy_read_timeout과 fastcgi_read_timeout의 기본값은 각각 60초이며, 이는 업스트림에서 두 번의 연속적인 읽기 작업 사이에 허용되는 시간입니다.

먼저 Nginx 오류 로그에서 업스트림 타임아웃이 발생하는지 확인하고, 백엔드 애플리케이션의 처리 시간과 로그를 점검하십시오. 정상적인 업무 처리 자체가 60초보다 오래 걸리는 것이 확인된 경우에만 필요한 범위에서 타임아웃을 조정합니다.

HTTP 리버스 프록시에서 읽기 타임아웃을 120초로 늘리는 예시는 다음과 같습니다.

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_read_timeout 120s;
}

FastCGI 응답을 기다리는 시간을 조정해야 하는 경우에는 해당 FastCGI location 안에서 다음과 같이 설정할 수 있습니다.

fastcgi_read_timeout 120s;

해결 여부 확인

수정 후에는 Nginx 설정, 업스트림 서비스, 실제 HTTP 응답을 각각 확인해야 합니다.

1. Nginx 설정 문법이 정상인지 확인합니다.
2. 업스트림 서비스가 실제 포트 또는 소켓에서 실행 중인지 확인합니다.
3. Nginx를 거치지 않은 내부 직접 요청이 정상인지 확인합니다.
4. 마지막으로 Nginx를 통한 요청이 정상 HTTP 응답을 반환하는지 확인합니다.

sudo nginx -t
sudo systemctl is-active nginx
curl -I http://127.0.0.1/

가상 호스트가 특정 도메인에 따라 동작한다면 서버 내부에서 Host 헤더를 지정하여 확인할 수 있습니다.

curl -I -H "Host: server.example.com" http://127.0.0.1/

502가 사라지고 예상한 HTTP 상태 코드가 반환되며 Nginx 오류 로그에 새로운 업스트림 오류가 기록되지 않는지 확인하십시오.

증상별 점검표

설정 변경 후 문제가 생겼을 때 원상복구

502 해결 과정에서 proxy_pass, fastcgi_pass 또는 타임아웃 값을 변경한 뒤 문제가 더 커졌다면 변경한 사이트 설정을 이전 값으로 복원합니다. 설정 파일을 수정하기 전 백업해 두었다면 백업본을 복원한 뒤 문법 검사를 수행합니다.

sudo nginx -t

검사가 성공한 경우에만 Nginx 설정을 다시 읽습니다.

sudo systemctl reload nginx

원상복구 후에도 502가 계속된다면 Nginx 설정이 아니라 업스트림 서비스 자체의 상태와 로그를 다시 확인하십시오.

자주 묻는 질문

502 Bad Gateway가 나오면 Nginx를 재시작하면 해결되나요?

일시적인 상태라면 잠시 정상화될 수 있지만, 업스트림 서비스 중단이나 잘못된 포트·소켓 설정이 원인이라면 다시 발생합니다. 재시작보다 먼저 /var/log/nginx/error.log와 업스트림 상태를 확인하는 것이 좋습니다.

Nginx는 정상인데 PHP 사이트만 502가 발생하는 이유는 무엇인가요?

PHP-FPM 서비스가 중단되었거나 Nginx의 fastcgi_pass가 실제 PHP-FPM 소켓과 다른 경로를 가리키는 경우가 대표적입니다. /run/php/의 실제 소켓과 FPM 서비스 상태를 먼저 확인하십시오.

proxy_read_timeout을 크게 늘리면 502가 해결되나요?

업스트림이 정상적으로 처리하고 있지만 응답 간격이 기본 타임아웃보다 긴 경우에는 도움이 될 수 있습니다. 그러나 백엔드가 죽어 있거나 연결 자체가 거부되는 문제에는 효과가 없으므로 오류 로그와 백엔드 처리 시간을 먼저 확인해야 합니다.

외부에서는 502인데 백엔드에 직접 접속하면 정상입니다. 무엇을 확인해야 하나요?

Nginx가 사용하는 업스트림 주소와 실제 백엔드 주소가 일치하는지, Nginx 서버에서 해당 주소로 직접 연결할 수 있는지, Unix 소켓을 사용한다면 권한이 맞는지 확인하십시오. 여러 가상 호스트가 있다면 요청이 예상한 server 블록에 들어가는지도 nginx -T로 확인하는 것이 좋습니다.

공식 참고자료

• NGINX: ngx_http_proxy_module 공식 문서 — proxy_pass, proxy_connect_timeout, proxy_read_timeout 동작 확인. 조회일: 2026-08-16.
• NGINX: ngx_http_fastcgi_module 공식 문서 — fastcgi_pass, fastcgi_read_timeout 동작 확인. 조회일: 2026-08-16.
• NGINX: ngx_http_upstream_module 공식 문서 — 업스트림 서버 처리와 502 관련 동작 확인. 조회일: 2026-08-16.
• Ubuntu: How to configure nginx — Ubuntu의 Nginx 설정 구조 확인. 조회일: 2026-08-16.
• Canonical: Ubuntu release cycle — Ubuntu 22.04 LTS 지원 상태 확인. 조회일: 2026-08-16.