Nginx 연결 거부 오류 로그 분석 및 문제 해결

Nginx 오류 로그를 분석하여 연결 거부 문제를 해결하면 일반적인 502 페이지에서 특정 백엔드 실패로 이동할 수 있습니다. "연결 거부"라는 문구는 일반적으로 Nginx가 업스트림 주소에 연결을 시도했지만 어떤 프로세스도 연결을 수락하지 않았음을 의미합니다.

이는 시간 초과, DNS 오류 또는 잘못된 응답과 다릅니다. 로그 패턴을 인식하면 문제를 신속하게 좁힐 수 있습니다.

"연결 거부"의 의미

Nginx 로그에서 일반적인 메시지는 다음과 같습니다:

connect() failed (111: Connection refused) while connecting to upstream

이는 운영 체제가 연결 시도를 거부했음을 의미합니다. Nginx가 대상 호스트에 도달했지만 대상 포트에서 수신 대기 중인 프로세스가 없거나 연결이 적극적으로 거부되었습니다.

Nginx가 다음과 같이 프록시할 때 이 오류가 발생할 수 있습니다:

proxy_pass http://127.0.0.1:3000;

하지만 애플리케이션이 중지되었거나 다른 포트에서 수신 대기 중인 경우입니다.

이 오류는 배포 후에 흔히 발생합니다. 프로세스 관리자가 앱을 다시 시작하지 못하거나, 컨테이너가 충돌하거나, 새 구성이 Nginx를 업데이트하지 않고 앱 포트를 변경할 수 있습니다.

모든 502 오류를 연결 거부로 처리하지 마십시오. 시간 초과 메시지는 다른 방향을 가리킵니다. 권한 거부 메시지는 종종 소켓 또는 보안 정책을 가리킵니다. 정확한 로그 텍스트가 중요합니다.

올바른 Nginx 오류 로그 찾기

기본 오류 로그 경로는 종종 다음과 같습니다:

/var/log/nginx/error.log

하지만 서버 블록은 사용자 정의 로그를 정의할 수 있습니다:

error_log /var/log/nginx/app-error.log warn;

기본 로그에 최근 항목이 표시되지 않으면 관련 Nginx 구성을 확인하십시오. 일부 시스템에서는 서비스 수준 메시지가 시스템 저널에도 나타납니다.

유용한 명령어는 다음과 같습니다:

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

그리고:

journalctl -u nginx -n 100

테스트할 때 브라우저나 curl로 하나의 요청을 트리거한 다음 즉시 최신 로그 줄을 확인하십시오. 그러면 사용자에게 표시되는 오류를 백엔드 실패와 훨씬 쉽게 연결할 수 있습니다.

좋은 로그 검토는 네 가지 정보를 캡처합니다:

실패한 요청의 타임스탬프.
업스트림 주소 및 포트.
요청 경로.
111: Connection refused와 같은 정확한 시스템 오류.

더 광범위한 Nginx 문제 해결은 Nginx 502 Bad Gateway 오류 수정을 참조하십시오.

로그 항목을 업스트림에 매핑

일반적인 로그 줄에는 다음과 같은 업스트림 값이 포함될 수 있습니다:

upstream: "http://127.0.0.1:3000/api/status"

이는 Nginx가 요청을 보낸 위치를 정확히 알려줍니다. 이제 해당 위치에서 수신 대기 중인 프로세스가 있는지 확인하십시오:

ss -ltnp

127.0.0.1:3000, 0.0.0.0:3000 또는 예상 주소를 찾으십시오. 포트가 없으면 앱이 Nginx가 예상하는 위치에서 수신 대기 중이 아닙니다.

업스트림을 직접 테스트하십시오:

curl -i http://127.0.0.1:3000/api/status

연결 거부로 실패하면 Nginx 없이 문제를 확인한 것입니다.

앱이 Docker에서 실행 중인 경우 127.0.0.1에 주의하십시오. 호스트에서 이는 호스트를 의미합니다. Nginx 컨테이너 내부에서는 Nginx 컨테이너 자체를 의미합니다. Compose 설정에서 Nginx는 일반적으로 다음과 같이 서비스 이름으로 프록시해야 합니다:

proxy_pass http://app:3000;

두 컨테이너가 동일한 Docker 네트워크를 공유하는 경우입니다.

Unix 소켓의 경우 로그는 포트 대신 경로를 가리킬 수 있습니다:

upstream: "http://unix:/run/app/app.sock:/"

이 경우 소켓이 존재하는지와 Nginx 작업자 사용자가 액세스할 수 있는지 확인하십시오.

일반적인 원인 및 해결 방법

가장 일반적인 원인은 중지된 백엔드 서비스입니다. 다음으로 확인하십시오:

systemctl status your-app

실패한 경우 다시 시작하기 전에 앱 로그를 읽으십시오. 다시 시작하면 사이트가 복구될 수 있지만 로그는 실패 이유를 설명합니다.

또 다른 일반적인 원인은 포트 불일치입니다. 예를 들어 앱이 포트 3000에서 8080으로 변경되었지만 Nginx가 여전히 3000으로 프록시하는 경우입니다. Nginx 업스트림 대상을 수정하거나 앱의 예상 포트를 복원하십시오.

세 번째 원인은 잘못된 인터페이스에 바인딩하는 것입니다. 127.0.0.1에서만 수신 대기하는 앱은 동일한 호스트의 로컬 Nginx에서 연결할 수 있습니다. 그러나 Nginx가 다른 컨테이너나 다른 서버에서 실행 중인 경우 루프백 주소를 통해 연결할 수 없습니다. 이러한 설정에서는 앱이 개인 네트워크 내에서 0.0.0.0에 바인딩해야 할 수 있습니다.

방화벽 규칙도 연결을 거부하거나 거절할 수 있으며, 특히 서버 간에 발생합니다. Nginx가 다른 호스트로 프록시하는 경우 업스트림 포트가 노트북뿐만 아니라 Nginx 머신에서도 열려 있는지 확인하십시오.

마지막으로 배포 타이밍으로 인해 일시적인 연결 거부 오류가 발생할 수 있습니다. Nginx가 새 앱 프로세스가 준비되기 전에 트래픽을 보내면 사용자가 간헐적으로 502 오류를 볼 수 있습니다. 상태 확인, 준비 상태 프로브 또는 정상 재시작 전략으로 이를 방지할 수 있습니다.

실용적인 문제 해결 흐름

로그에 연결 거부가 표시되면 다음 순서를 사용하십시오:

Nginx 오류 로그에서 업스트림 호스트와 포트를 복사합니다.
Nginx 서버에서 해당 정확한 업스트림으로 curl을 실행합니다.
ss -ltnp를 실행하여 프로세스가 수신 대기 중인지 확인합니다.
백엔드 서비스 상태와 애플리케이션 로그를 확인합니다.
Nginx proxy_pass 값을 앱의 실제 바인드 주소와 비교합니다.
구성이 올바르고 nginx -t가 통과한 후에만 Nginx를 다시 로드합니다.

이 흐름은 일반적인 실수를 방지합니다: 앱이 단순히 다운되었을 때 Nginx를 편집하는 것입니다. 또한 반대 실수, 즉 Nginx가 잘못된 위치를 가리키고 있을 때 앱을 반복적으로 다시 시작하는 것을 방지합니다.

명령 기본 사항은 Nginx 로그 모니터링 명령어를 참조하십시오.

전문가에게 문의해야 할 때

연결 거부 오류가 부하가 있을 때만 발생하거나, 여러 업스트림에서 발생하거나, 롤링 배포 중에 발생하는 경우 도움을 요청하십시오. 이러한 경우 프로세스 감독, 컨테이너 네트워킹, 로드 밸런서 상태 확인 또는 용량 제한이 관련될 수 있습니다.

업스트림이 프로덕션 결제, 인증 또는 고객 대면 API 서비스인 경우에도 에스컬레이션해야 합니다. 빠른 복구가 중요하지만 로그를 보존하고 실패를 이해하는 것도 중요합니다.

연결 거부는 신중히 읽으면 Nginx 오류 중 더 명확한 오류 중 하나입니다. 로그에서 업스트림을 찾고, 해당 대상을 직접 테스트하고, Nginx가 연결하지 못하게 하는 서비스, 포트, 인터페이스 또는 네트워크 경로를 수정하십시오. 로그는 이미 시작점을 제공합니다.