Nginx 문제 해결: 웹 서버 문제를 위한 일반적인 명령줄 솔루션

Nginx가 중단되면 처음 몇 분은 일반적으로 문제를 좁히는 데 사용됩니다. 서비스가 중지되었나요? 설정 변경이 실패했나요? 다른 프로세스가 이미 포트 80을 사용 중인가요? Nginx는 정상이지만 업스트림 앱이 다운되었나요? 올바른 순서로 확인을 실행하면 명령줄에서 빠르게 답을 얻을 수 있습니다.

저는 가장 덜 파괴적인 명령부터 시작하는 것을 선호합니다: 상태 확인, 설정 테스트, 로그 읽기, 그런 다음에만 리로드 또는 재시작합니다. 재시작은 유용한 증거를 숨길 수 있으므로, 무엇을 수정하고 있는지 확인한 후에만 수정 사항으로 취급하세요.

필수 Nginx 관리 명령

문제 해결의 첫 번째 단계는 종종 Nginx 서비스 자체의 상태를 확인하는 것입니다. 운영 체제에 따라 일반적으로 systemd 또는 service(SysVinit)와 상호 작용합니다.

1. Nginx 서비스 상태 확인

Nginx가 실행 중인지, 중지되었는지, 실패했는지 아는 것이 중요합니다. status 명령이 이 개요를 제공합니다.

systemd 사용 (Ubuntu 16.04+, CentOS 7+와 같은 최신 Linux 배포판에서 일반적):

sudo systemctl status nginx

예상 출력 (활성/실행 중):

● nginx.service - 고성능 웹 서버 및 리버스 프록시 서버
   Loaded: 로드됨 (/lib/systemd/system/nginx.service; 활성화됨; 공급업체 사전 설정: 활성화됨)
   Active: 활성 (실행 중) since Tue 2023-10-24 10:00:00 UTC; 1시간 전
     Docs: man:nginx(8)
 Main PID: 1234 (nginx)
    Tasks: 2 (limit: 4915)
   CGroup: /system.slice/nginx.service
           ├─1234 nginx: 마스터 프로세스 /usr/sbin/nginx -g daemon on;
           └─1235 nginx: 작업자 프로세스

출력에 Active: inactive (dead) 또는 Active: failed가 표시되면 Nginx가 현재 트래픽을 제공하지 않는다는 것을 알 수 있습니다. 그 이유는 알 수 없습니다. 다음 단서는 일반적으로 설정 테스트 또는 시스템 저널입니다.

sudo journalctl -u nginx -n 80 --no-pager

이 명령은 systemd의 시작 실패를 포함한 최근 서비스 로그를 보여줍니다. 알 수 없는 지시문, 누락된 인증서 파일, 바인드 실패 또는 권한 오류에 대한 메시지를 찾아보세요.

2. Nginx 시작, 중지 및 리로드

상태를 확인한 후에는 이를 관리해야 합니다. 필요에 따라 다음 명령을 사용하세요:

작업	명령 (`systemctl` 사용)
중지 서비스	`sudo systemctl stop nginx`
시작 서비스	`sudo systemctl start nginx`
재시작 서비스	`sudo systemctl restart nginx` (중지 후 다시 시작)
리로드 설정	`sudo systemctl reload nginx` (연결을 끊지 않고 새 설정 적용)

모범 사례: restart보다 reload 사용 설정 변경(예: 가상 호스트 또는 SSL 인증서 업데이트) 시 항상 reload를 사용하세요. 이렇게 하면 기존 연결이 중단 없이 계속되는 동안 변경 사항이 원활하게 적용됩니다. reload가 실패하거나 작업자 프로세스를 완전히 재설정해야 하는 경우에만 restart를 사용하세요.

리로드 전에 다음을 실행하세요:

sudo nginx -t && sudo systemctl reload nginx

이 한 줄 패턴은 가장 일반적인 실수인 손상된 설정을 리로드하여 작동 중인 서버를 중단시키는 것을 방지합니다. nginx -t가 실패하면 리로드 명령이 실행되지 않습니다.

설정 파일 검증

Nginx에서 시작 실패 또는 예기치 않은 동작의 가장 일반적인 원인은 설정 파일(nginx.conf 또는 /etc/nginx/sites-available/ 내에 포함된 파일)의 구문 오류입니다. Nginx는 훌륭한 내장 테스트 유틸리티를 제공합니다.

3. 설정 구문 테스트

-t 플래그는 설정 파일의 구문 오류를 테스트하고 설정 파일 경로가 유효한지 확인합니다.

sudo nginx -t

성공적인 출력 예:

nginx: 설정 파일 /etc/nginx/nginx.conf 구문이 정상입니다
nginx: 설정 파일 /etc/nginx/nginx.conf 테스트가 성공했습니다

오류 출력 예:

오류가 있는 경우 Nginx는 정확한 파일과 줄 번호를 알려줍니다. 예를 들어, 세미콜론 누락:

nginx: [emerg] /etc/nginx/sites-enabled/default:15에 알 수 없는 지시문 "server_name example.com"이 있습니다
nginx: 설정 파일 /etc/nginx/nginx.conf 테스트가 실패했습니다

이 즉각적인 피드백을 통해 지정된 파일의 15번째 줄로 바로 이동하여 오타를 수정할 수 있습니다.

때로는 보고된 줄이 Nginx가 마침내 문제를 발견한 위치일 뿐입니다. 누락된 } 또는 ;는 몇 줄 앞에 있을 수 있습니다. 오류가 정상적인 지시문을 가리키는 경우 위 블록을 검사하세요.

4. 활성 설정 표시

Nginx가 현재 실행 중인 설정을 정확히 확인하려면(특히 여러 설정 병합 또는 복잡한 포함 후에 유용함) -T 플래그(대문자 T)를 사용하세요:

sudo nginx -T

이 명령은 전체 활성 설정을 출력하며, 비교 또는 상세 검토를 위해 파일로 파이프할 수 있습니다:

sudo nginx -T > current_nginx_config.txt

nginx -T 출력을 공유할 때는 주의하세요. 내부 호스트 이름, 인증서 경로, 프록시 헤더 및 때로는 헤더로 전달되는 비밀번호가 포함될 수 있습니다. 인시던트 작업에는 훌륭하지만, 티켓이나 채팅에는 먼저 수정하세요.

포트 및 리스너 확인

Nginx가 시작되지 않고 로그에 bind() to 0.0.0.0:80 failed가 언급되면 다른 프로세스가 이미 해당 포트에서 수신 대기 중일 수 있습니다.

sudo ss -ltnp | grep -E ':80|:443'

일반적인 출력은 로컬 주소, 포트 및 프로세스 이름을 보여줍니다. Apache, Caddy, 컨테이너 프록시 또는 이전 Nginx 프로세스가 포트를 보유하고 있으면 Nginx가 바인딩할 수 없습니다.

서버 자체에서 공개 동작을 확인할 수도 있습니다:

curl -I http://127.0.0.1
curl -Ik https://127.0.0.1

-I는 헤더만 가져옵니다. -k는 인증서 유효성 검사를 무시하며, 도메인 이름에 대해 발급된 인증서로 localhost를 테스트할 때 유용합니다. 다른 머신에서 실제 호스트 이름도 테스트하세요:

curl -I https://example.com

localhost는 작동하지만 공개 호스트 이름이 실패하면 방화벽 규칙, 클라우드 보안 그룹, DNS, 로드 밸런서 또는 CDN 설정을 확인하세요.

DNS는 별도로 확인할 가치가 있습니다. DNS로 인해 정상적인 Nginx 서버가 외부에서 중단된 것처럼 보일 수 있기 때문입니다:

dig +short example.com
dig +short www.example.com

반환된 주소가 예상한 서버 또는 로드 밸런서인지 확인하세요. 사이트를 최근에 이동한 경우, 오래된 DNS로 인해 일부 사용자는 이전 호스트로 보내지고 자체 테스트는 새 호스트에 도달할 수 있습니다.

모니터링 및 로그 분석

Nginx가 성공적으로 시작되었지만 잘못된 페이지를 제공하거나 5xx 오류를 반환하는 경우 로그가 주요 정보 출처가 됩니다.

5. 주요 로그 파일 위치 찾기

기본적으로 Nginx 로그는 일반적으로 /var/log/nginx/에 있습니다. 두 가지 필수 파일은 다음과 같습니다:

access.log: 서버에서 처리한 모든 요청(IP, 요청 시간, 상태 코드 및 요청된 리소스 포함)을 기록합니다.
error.log: 작동 또는 요청 처리 중에 발생한 경고, 알림 및 심각한 오류를 기록합니다.

6. `tail`을 사용한 실시간 로그 모니터링

오류가 발생할 때 모니터링하려면 오류 로그에서 follow(-f) 옵션과 함께 tail 명령을 사용하세요.

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

이것은 새로 배포된 애플리케이션 엔드포인트를 테스트할 때 매우 유용합니다. Nginx 또는 업스트림 애플리케이션에서 오류가 발생하는지 즉시 확인할 수 있기 때문입니다.

트래픽이 많은 서버의 경우 새 오류 줄만 따르고 타임스탬프를 계속 표시하세요:

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

그런 다음 다른 터미널에서 실패한 요청을 재현하세요:

curl -I https://example.com/failing/path

이 간단한 두 터미널 워크플로는 각 요청과 로그 항목을 직접 일치시킬 수 있기 때문에 브라우저에서 클릭하는 것보다 종종 더 빠릅니다.

7. 액세스 로그 상태 코드 분석

트래픽이 많은 문제의 경우 액세스 로그에서 상태 코드를 빠르게 스캔하면 문제를 발견할 수 있습니다:

4xx 코드 (클라이언트 오류): 종종 끊어진 링크, 누락된 파일(404) 또는 권한 문제를 나타냅니다.
5xx 코드 (서버 오류): Nginx 자체가 요청을 이행하지 못했음을 나타내며, 종종 업스트림 연결 시간 초과(502/504) 또는 내부 서버 처리 실패(500)로 인해 발생합니다.

grep을 사용하여 특정 코드를 필터링하세요. 예를 들어, 모든 502 Bad Gateway 오류 찾기:

sudo grep ' 502 ' /var/log/nginx/access.log | tail -n 20

빠른 상태 코드 카운트는 하나의 잘못된 URL을 처리하고 있는지 아니면 더 광범위한 인시던트를 처리하고 있는지 보여줄 수 있습니다:

sudo awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -nr | head

일반적인 패턴:

404 급증은 종종 잘못된 배포 경로, 누락된 정적 파일 또는 변경된 경로를 의미합니다.
403은 종종 파일 권한, 디렉터리 권한 또는 의도적인 액세스 규칙을 가리킵니다.
502는 일반적으로 Nginx가 업스트림 서비스에서 유효한 응답을 받을 수 없음을 의미합니다.
504는 일반적으로 업스트림 서비스가 연결을 수락했지만 제 시간에 응답하지 않았음을 의미합니다.

업스트림 실패의 경우 애플리케이션 서비스도 확인하세요:

sudo systemctl status myapp
sudo journalctl -u myapp -n 100 --no-pager

myapp을 실제 서비스 이름으로 바꾸세요. Nginx는 살아 있고 연결 가능한 것만 프록시할 수 있습니다.

고급 진단: 상세 정보 및 프로세스 ID

8. 디버그 로깅 강제 (주의 권장)

매우 까다로운 상황에서는 로깅 수준을 높이면 요청 처리에 대한 더 자세한 정보를 얻을 수 있습니다. 이는 설정에서 error_log 지시문을 debug로 수정하여 수행합니다.

경고: 디버그 로깅은 매우 빠르게 엄청난 양의 데이터를 생성하므로 성능에 심각한 영향을 미치므로 활성 문제 해결을 위해서만 일시적으로 사용해야 합니다.

지시문을 변경한 후에는 변경 사항을 적용하려면 Nginx를 reload 또는 restart해야 합니다.

9. Nginx 마스터 프로세스 ID(PID) 찾기

프로세스 ID(PID)는 실행 중인 마스터 프로세스에 특정 신호를 보내는 데 유용합니다(예: systemctl 외부에서 정상 종료 또는 정상 리로드). PID는 일반적으로 파일(보통 /var/run/nginx.pid)에 저장됩니다.

cat /var/run/nginx.pid
# 예제 출력: 1234

그런 다음 필요한 경우 kill 명령을 사용할 수 있습니다 (예: sudo kill -HUP 1234를 사용하여 PID를 사용하여 리로드 강제):

대부분의 운영자는 systemctl reload nginx를 선호해야 합니다. 서비스 관리자를 통해 이루어지고 감사가 더 쉽기 때문입니다. 신호는 systemd가 프로세스를 관리하지 않는 최소 시스템, 컨테이너 또는 이전 호스트에서 여전히 유용합니다.

증상별 일반적인 명령줄 수정

설정 편집 후 Nginx가 실패하는 경우:

sudo nginx -t
sudo journalctl -u nginx -n 80 --no-pager

보고된 파일과 줄을 수정한 다음 리로드하기 전에 다시 테스트하세요.

인증서 갱신 후 HTTPS가 실패하는 경우:

sudo nginx -t
sudo ls -l /etc/letsencrypt/live/example.com/
sudo openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates -subject

이렇게 하면 인증서 파일이 존재하는지 확인하고 주제와 유효 기간을 표시합니다.

정적 파일이 403을 반환하는 경우:

namei -l /var/www/example.com/index.html

namei -l은 경로의 모든 디렉터리에 대한 권한을 출력합니다. Nginx는 상위 디렉터리에 대한 실행 권한과 파일에 대한 읽기 권한이 필요합니다.

리버스 프록시가 502를 반환하는 경우:

sudo grep 'connect() failed' /var/log/nginx/error.log | tail
sudo ss -ltnp | grep 3000
curl -I http://127.0.0.1:3000

이렇게 하면 업스트림이 수신 대기 중인지, 로컬에서 응답하는지 확인합니다.

업스트림이 TCP 포트 대신 Unix 소켓인 경우 소켓 경로와 권한을 확인하세요:

sudo ls -l /run/myapp/myapp.sock
sudo grep -R "proxy_pass" /etc/nginx/sites-enabled /etc/nginx/conf.d

Nginx 작업자 사용자는 소켓에 액세스할 수 있는 권한이 필요합니다. 많은 시스템에서 해당 사용자는 www-data 또는 nginx이지만, 소유권이나 그룹을 변경하기 전에 nginx.conf에서 확인하세요.

간헐적 실패의 경우 액세스 로그에서 성공한 요청과 실패한 요청을 비교하세요. 작은 샘플로도 충분한 경우가 많습니다:

sudo grep ' 504 ' /var/log/nginx/access.log | tail -n 20
sudo grep ' 200 ' /var/log/nginx/access.log | tail -n 20

경로, 로그 형식에 포함된 경우 업스트림 응답 시간 필드 또는 과도한 요청을 트리거하는 특정 클라이언트 IP의 패턴을 찾아보세요.

문제 해결 워크플로

Nginx 문제에 직면했을 때 다음 순서를 따르세요:

상태 확인: sudo systemctl status nginx.
설정 테스트: 시작에 실패한 경우 sudo nginx -t를 실행하세요. 보고된 오류를 수정하세요.
재시작/리로드: 설정이 수정된 경우 sudo systemctl reload nginx를 사용하세요.
로그 모니터링: 실행 중이지만 중단된 경우 문제를 재현하는 동안 sudo tail -f /var/log/nginx/error.log를 사용하세요.
액세스 분석: access.log를 검토하여 실패의 성격(4xx 대 5xx)을 나타내는 상태 코드를 확인하세요.

이 순서는 추측을 방지합니다. 상태는 Nginx가 실행 중인지 알려주고, 설정 테스트는 로드할 수 있는지 알려주며, 로그는 실제 요청 중에 발생한 상황을 알려주고, 로컬 curl 검사는 Nginx 문제를 업스트림 또는 네트워크 문제와 분리합니다.

작업하면서 간단한 인시던트 노트를 작성하세요: 실행한 명령, 확인된 결과, 수행한 변경 사항. 이렇게 하면 반복 확인을 방지하고 인계가 훨씬 쉬워집니다.