DevOps 도구 및 베스트 프랙티스 마스터 - DevOps 지식 허브 DevOps 도구 및 베스트 프랙티스 마스터 - DevOps 지식 허브

Nginx 'Connection Refused' 오류 해결: 실전 문제 해결 가이드

서비스 상태, 수신 포트, 방화벽, 설정 및 업스트림을 확인하여 Nginx 연결 거부 오류를 해결합니다.

Nginx 'Connection Refused' 오류 해결: 실전 문제 해결 가이드

Nginx 뒤에서 실행 중인 서비스에 접근할 때 'Connection Refused' 오류가 발생하는 것은 흔하면서도 짜증나는 경험입니다. 'Timeout' 오류가 네트워크 지연이나 패킷 손실을 암시하는 반면, 'Connection Refused' 오류는 명확합니다. 운영 체제가 지정된 포트와 IP 주소에서 활성 상태로 수신 중인 애플리케이션이 없기 때문에 연결 시도를 즉시 거부한 것입니다.

이러한 즉각적인 거부는 문제를 몇 가지 중요한 영역으로 좁힙니다: 서비스가 중단되었거나, 방화벽이 로컬 트래픽을 차단하고 있거나, 구성이 존재하지 않는 포트로 트래픽을 전달하고 있는 경우입니다. 이 가이드는 'Connection Refused' 오류를 진단하고 해결하기 위한 체계적인 4단계 접근 방식을 제공하여 서비스 연결을 신속하게 복원할 수 있도록 합니다.

1단계: Nginx 서버 상태 확인 (기본 수신자)

연결 거부의 가장 기본적인 원인은 Nginx 서비스 자체가 실행 중이 아니거나 잘못 구성된 경우입니다.

1. Nginx 서비스 상태 확인

시스템의 서비스 관리자(보통 systemd)를 사용하여 Nginx가 활성 상태이고 실행 중인지 확인하십시오. 여기서 실패하면 기본 수신 포트(보통 80 또는 443)에서 거부가 직접 발생합니다.

sudo systemctl status nginx

예상 출력 (성공): Active: active (running)을 찾으십시오.

실행 가능한 수정: 상태가 inactive 또는 failed로 표시되면 서비스를 시작하고 로그에서 실패 세부 정보를 확인하십시오.

sudo systemctl start nginx
sudo journalctl -xe | grep nginx

2. 활성 수신 포트 확인

ss(소켓 통계) 또는 netstat 도구를 사용하여 Nginx가 예상 IP 주소와 포트(예: 0.0.0.0:80 또는 127.0.0.1:8080)에 실제로 바인딩되고 있는지 확인하십시오.

# ss 사용 (최신 Linux 배포판에서 권장)
sudo ss -tuln | grep 80

# netstat 사용
sudo netstat -tuln | grep 80

Nginx와 관련된 프로세스(PID) 아래에 예상 포트(예: :80 또는 :443)가 나열되지 않으면 Nginx가 바인딩에 실패한 것이며, 이는 구성 오류 또는 다른 서비스가 이미 해당 포트를 점유하고 있기 때문일 가능성이 높습니다.

팁: 다른 서비스가 포트를 점유하고 있는 경우 해당 서비스를 중지하거나 Nginx 구성을 수정하여 다른 사용 가능한 포트에서 수신하도록 해야 합니다.

2단계: 방화벽 및 네트워크 구성

Nginx가 로컬에서 실행 중이고 수신 중인 경우 연결 거부는 서비스 외부에서 발생할 수 있으며, 일반적으로 방화벽 규칙이 인바운드 트래픽을 차단하기 때문입니다.

1. 로컬 서버 방화벽 확인

Nginx가 수신 중인 포트(예: 80, 443)가 호스트 방화벽(UFW, firewalld 또는 iptables)을 통해 명시적으로 허용되는지 확인하십시오.

UFW 예제 (Ubuntu/Debian)

sudo ufw status verbose
# 닫혀 있는 경우 포트 허용:
sudo ufw allow 'Nginx Full'
# 또는 구체적으로:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Firewalld 예제 (CentOS/RHEL)

sudo firewall-cmd --list-all
# 닫혀 있는 경우 서비스 추가:
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

2. 클라우드 제공업체 보안 그룹 확인

서버가 클라우드 환경(AWS EC2, Azure VM, GCP Compute Engine)에서 호스팅되는 경우 연결 거부가 가상 네트워크의 보안 계층에서 발생할 수 있습니다.

  • AWS 보안 그룹 (SG): 연결된 SG를 확인하고 인바운드 규칙이 소스 IP 주소(일반적으로 공용 액세스의 경우 0.0.0.0/0)에서 포트 80 및 443으로의 트래픽을 허용하는지 확인하십시오.
  • Azure 네트워크 보안 그룹 (NSG): 인바운드 포트 규칙을 확인하십시오.

3단계: Nginx 구성 유효성 검사

잘못된 구성 지시문으로 인해 Nginx가 사용할 수 없는 포트나 IP에서 수신을 시도하여 시작 실패 및 후속 연결 거부가 발생할 수 있습니다.

1. listen 지시문 검토

기본 구성 파일(주로 /etc/nginx/nginx.conf) 및 관련 서버 블록(보통 /etc/nginx/conf.d/ 또는 /etc/nginx/sites-enabled/에 있음)을 검사하십시오. listen 지시문이 올바른지 확인하십시오.

올바르게 구성된 listen 블록 예:

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    # ... 기타 지시문
}

Nginx가 127.0.0.1(localhost)에서만 수신하도록 구성되었지만 공용 IP를 사용하여 액세스하려고 하면 연결이 거부됩니다.

2. 구성 구문 검사 실행

Nginx를 다시 시작하기 전에 항상 구성 구문의 유효성을 검사하십시오. 구문 분석 오류가 있으면 서비스가 시작되지 않아 거부가 발생합니다.

sudo nginx -t

테스트가 실패하면 식별된 오류를 수정하고 테스트를 다시 실행한 다음 Nginx를 다시 로드하거나 다시 시작하십시오.

sudo systemctl reload nginx

4단계: 리버스 프록시 (업스트림) 문제 해결

Nginx가 80/443 포트에서 성공적으로 실행 중이지만 특정 경로(/api/)에 액세스하면 'Connection Refused'가 발생하는 경우 문제는 Nginx와 백엔드 서비스(업스트림) 사이에 있습니다.

이 시나리오에서 Nginx는 초기 연결을 수락했지만 요청을 프록시하려고 할 때 백엔드에 대한 연결이 거부되었습니다. 오류 로그에서 이를 확인할 수 있습니다.

1. Nginx 오류 로그 확인

실패한 연결을 시도한 직후 Nginx 오류 로그(보통 /var/log/nginx/error.log)를 검사하십시오. proxy_pass 지시문과 관련된 메시지, 특히 연결 오류를 언급하는 메시지를 찾으십시오.

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

다음과 같은 항목이 표시될 수 있습니다:

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

2. 백엔드 서비스 상태 확인

프록시 시나리오에서 가장 일반적인 수정 사항입니다: 백엔드 애플리케이션(예: Node.js, Python Gunicorn, Apache)이 중단되었거나 Nginx가 예상하는 위치에서 수신 중이 아닙니다.

실행 가능한 단계:

a. 백엔드 서비스 상태 확인: 백엔드 애플리케이션이 실행 중인지 확인하십시오.

b. 백엔드 수신 포트 확인: 백엔드를 호스팅하는 서버에서 ss -tuln을 사용하여 애플리케이션이 Nginx의 proxy_pass 지시문에 지정된 IP/포트에서 수신 중인지 확인하십시오.

3. 백엔드 연결 직접 테스트

Nginx 서버에서 백엔드로의 연결을 curl 또는 telnet을 사용하여 직접 테스트하여 Nginx와 관련 없는 문제를 분리하십시오.

proxy_pass가 http://127.0.0.1:8080으로 설정되어 있다고 가정합니다:

# Nginx 서버에서 백엔드 포트로 연결 테스트
curl -v http://127.0.0.1:8080

# 또는 telnet 사용
telnet 127.0.0.1 8080
  • curl 또는 telnet이 실패하는 경우: 백엔드 서비스가 확실히 문제입니다(수신 중이 아니거나 내부 방화벽이 127.0.0.1 액세스를 차단하고 있음).
  • curl 또는 telnet이 성공하는 경우: 문제는 proxy_pass 지시문의 미묘한 오류(예: 세미콜론 누락, 호스트 이름 확인 오류 또는 프로토콜 불일치(HTTP 대 HTTPS))일 수 있습니다.

일반적인 proxy_pass 실수

proxy_pass의 IP 주소가 백엔드가 실제로 바인딩된 위치와 일치하는지 확인하십시오. 백엔드가 특정 IP(예: 192.168.1.10:8080)에 바인딩되지만 Nginx가 localhost:8080을 사용하는 경우 바인딩이 제한적이면 연결이 실패합니다.

주요 문제 해결 단계 최종 확인

  1. 시스템 확인: Nginx가 실행 중인가요 (systemctl status nginx)?
  2. 포트 확인: Nginx가 올바른 IP/포트에서 수신 중인가요 (ss -tuln)?
  3. 방화벽 확인: 들어오는 포트가 호스트 방화벽(UFW, iptables)에서 열려 있나요?
  4. 구성 확인: nginx -t가 통과하고 listen 지시문이 올바른가요?
  5. 프록시 확인 (해당되는 경우): 업스트림 서비스가 실행 중이고 proxy_pass에 정의된 정확한 IP/포트에서 수신 중인가요? curl을 사용하여 직접 연결을 테스트하십시오.

수신자, 포트, 방화벽, 구성, 업스트림 순서로 확인을 진행하십시오. 이 경로를 따르면 연결이 거부되는 정확한 위치에 집중할 수 있습니다.