Nginx 설정 구문 및 시작 실패 디버깅

Nginx가 시작되지 않을 때, 원인은 일반적으로 구문 오류, 잘못된 include, 포트 충돌 또는 파일 권한 문제입니다. 가장 빠른 해결 방법은 먼저 설정을 테스트한 다음, 서비스를 반복적으로 재시작하는 대신 서비스 로그를 확인하는 것입니다.

이 가이드는 systemctl restart nginx가 실패하거나 설정 변경 후 서버가 수신을 중지했을 때 실행해야 하는 정확한 확인 사항을 보여줍니다.

필수 첫 단계: `nginx -t`로 설정 구문 테스트

Nginx 시작 문제(특히 설정 파일 관련)를 진단하는 가장 중요한 명령어는 nginx -t(설정 테스트)입니다. 이 명령어는 Nginx 데몬을 실제로 시작하지 않고 로드된 모든 설정 파일(nginx.conf 및 포함된 파일)을 구문 분석합니다. 구조적 오류, 적절한 지시문 배치 및 올바른 구문을 확인합니다.

테스트 실행 방법

일반적으로 필요한 권한(종종 root 또는 sudo 사용)이 있는 사용자로 이 명령어를 실행합니다.

sudo nginx -t

출력 해석

성공 출력

구문이 완벽하고 포함된 모든 파일을 읽을 수 있는 경우 출력은 다음과 같습니다.

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

이 출력이 표시되면 문제는 구문 오류가 아니라 포트 충돌, 권한 문제 또는 서비스 관리자(예: systemd)가 Nginx를 실행하려고 시도하는 방식의 오류일 가능성이 높습니다.

실패 출력 (구문 오류)

구문 오류가 있는 경우 nginx -t는 문제가 발생한 파일과 줄 번호를 즉시 보고합니다. 이는 대상 디버깅에 매우 유용합니다.

세미콜론 누락 오류 예시:

/etc/nginx/sites-enabled/default 파일 15행의 지시문 끝에 세미콜론을 잊어버린 경우:

sudo nginx -t

출력:

nginx: [emerg] unexpected "location" in /etc/nginx/sites-enabled/default:15
nginx: configuration file /etc/nginx/nginx.conf test failed

실행 가능한 팁: 오류 메시지에 제공된 정확한 파일 경로와 줄 번호를 사용하여 문제가 되는 지시문을 검사하고 수정하십시오.

구문 외 시작 실패 문제 해결

nginx -t가 성공을 보고했지만 Nginx가 계속 시작되지 않는 경우(예: systemctl status nginx가 실패를 표시하거나 서비스가 즉시 반환됨), 문제는 정적 설정 파일 구문 외부에 있습니다. 일반적인 원인으로는 포트 충돌, 권한 문제 또는 환경 문제가 있습니다.

1. 포트 충돌 확인

Nginx는 바인딩하는 포트(일반적으로 HTTP의 경우 80, HTTPS의 경우 443)에 대한 독점 액세스 권한이 필요합니다. 다른 프로세스가 이미 이러한 포트를 사용하고 있는 경우 Nginx는 바인딩과 관련된 [emerg] 오류와 함께 시작되지 않습니다.

ss 또는 netstat 명령어를 사용하여 대상 포트에서 수신 대기 중인 프로세스를 확인합니다.

# 포트 80에서 수신 대기 중인 프로세스 확인
sudo ss -tulpen | grep ':80'

다른 프로세스(예: Apache, 다른 Nginx 인스턴스)가 이미 바인딩되어 있는 경우 해당 프로세스를 중지하거나 Nginx 설정에서 listen 지시문을 변경해야 합니다.

2. 시작 실패에 대한 시스템 로그 분석

설정 테스트가 통과되면 서비스 관리자 로그는 데몬이 시작되지 않거나 즉시 종료된 이유에 대한 결정적인 기록을 제공합니다. systemd를 사용하는 대부분의 최신 Linux 배포판에서 journalctl 명령어가 가장 유용합니다.

Nginx 서비스 로그 보기

Nginx 서비스에 대한 로그를 보려면:

# Nginx 서비스 저널의 마지막 50줄 보기
sudo journalctl -u nginx.service -n 50 --no-pager

서비스가 Nginx 바이너리를 실행하려고 시도하기 전에 발생하는 오류(서비스 파일 자체의 문제를 나타낼 수 있음) 또는 Nginx 마스터 프로세스가 시작 시 즉시 내보내는 오류를 주의 깊게 살펴보십시오.

주목해야 할 일반적인 로그 오류:

권한 거부: Nginx가 필요한 디렉토리(PID 파일 위치 또는 SSL 인증서 경로)에 액세스할 수 없는 경우.
작업자 프로세스 실패: 작업자 프로세스가 포크되거나 올바르게 초기화될 수 없음을 나타내는 오류.

3. 파일 권한 및 경로 확인

Nginx는 디렉토리, 특히 SSL 인증서가 포함된 디렉토리 또는 사용자 지시문(예: user nginx;)을 사용할 때 특정 권한이 필요합니다.

SSL/TLS 설정: HTTPS를 활성화한 후 Nginx가 실패하면 ssl_certificate 및 ssl_certificate_key에 지정된 경로가 올바르고 Nginx 사용자가 해당 파일에 대한 읽기 권한이 있는지 확인합니다.
PID 파일 위치: main 컨텍스트의 pid 지시문(일반적으로 /var/run/nginx/)으로 지정된 디렉토리가 존재하고 Nginx 사용자가 쓸 수 있는지 확인합니다.

인증서 모범 사례: 일반적으로 root 또는 Nginx 사용자만 읽을 수 있도록 개인 키를 항상 안전하게 유지하십시오.

특정 오류 시나리오 진단

nginx -t는 구문을 포착하지만 다른 문제는 종종 다르게 나타납니다.

'연결 거부' 시나리오 (서비스가 실행 중이 아님)

서버에 연결을 시도하고 "연결 거부" 메시지를 받으면 해당 포트에서 수신 대기 중인 프로세스가 없음을 의미합니다.

상태 확인: 서비스가 실행 중인지 확인합니다.
```
sudo systemctl status nginx
```
비활성 상태인 경우: sudo nginx -t를 다시 실행한 다음 journalctl -u nginx.service를 확인하여 정확한 시작 실패 원인을 파악합니다.

`[emerg] bind()` 실패 오류 처리

이 오류는 Nginx가 listen 지시문에 정의된 IP 주소와 포트 조합을 확보할 수 없음을 명시적으로 의미합니다. 위에서 설명한 대로 이는 포트 충돌 또는 잘못된 IP 주소 설정을 직접적으로 가리킵니다.

로그 분석이 추측보다 나은 이유

Nginx 시작 문제를 해결할 때 추측에 의존하지 마십시오. 설정 테스트와 시스템 저널은 명시적인 데이터 포인트를 제공합니다. 다음 단계를 따르면:

구문 테스트 (nginx -t)
포트 확인 (ss/netstat)
서비스 로그 검토 (journalctl)

...일반 설정 확인에서 특정 런타임 환경으로 이동하여 문제 영역을 효율적으로 격리할 수 있습니다.

핵심 요약

리로드 또는 재시작을 시도하기 전에 항상 sudo nginx -t로 설정의 유효성을 검증하십시오.
깨끗한 테스트에도 불구하고 시작이 실패하면 ss를 사용하여 포트 충돌을 확인하십시오.
런타임 시작 오류에 대한 심층적인 통찰력을 얻으려면 journalctl -u nginx.service를 참조하십시오.