Nginx 서비스 제어를 위한 필수 명령어 마스터하기

Nginx 서비스 제어를 위한 필수 명령어를 마스터하면 안전하게 재시작하고, 트래픽 손실 없이 설정을 리로드하며, 서버가 응답하지 않는 이유를 진단할 수 있습니다. 대부분의 일상적인 Nginx 작업은 신중하게 사용되는 소수의 명령어로 이루어집니다.

이 가이드는 systemd로 관리되는 Nginx가 Ubuntu, Debian, CentOS, Rocky Linux 및 많은 클라우드 이미지에서 일반적인 Linux 시스템에서의 실용적인 명령어 사용에 중점을 둡니다.

예제는 서비스 이름이 nginx라고 가정합니다. 일부 사용자 정의 빌드 또는 제어판은 다른 유닛 이름을 사용하지만, 패키지된 Nginx 설치에서는 일반적으로 이 규칙을 따릅니다. 확실하지 않은 경우 일치하는 유닛을 나열하십시오:

systemctl list-units '*nginx*'
systemctl list-unit-files '*nginx*'

이 작은 확인은 일반적인 실수인 다른 웹 서버나 컨테이너가 실제로 트래픽을 처리하는 동안 잘못된 서비스를 문제 해결하는 것을 방지합니다.

Nginx가 실행 중인지 확인

서비스 상태로 시작하십시오:

sudo systemctl status nginx

이 명령은 Nginx가 활성 상태인지, 실패했는지, 비활성화되었는지 또는 아직 시작 중인지 보여줍니다. 또한 systemd의 최근 로그 라인을 표시하며, 여기에는 시작 또는 리로드 실패 이유가 포함되는 경우가 많습니다.

처음 몇 줄의 상태를 주의 깊게 읽으십시오. active (running)은 systemd가 마스터 프로세스가 살아 있다고 믿는다는 의미입니다. failed는 마지막 시작 또는 리로드 시도가 실패했음을 의미합니다. enabled 또는 disabled는 부팅 동작을 알려주며, 현재 서비스가 실행 중인지 여부는 알려주지 않습니다.

스크립트에서 유용한 더 짧은 출력의 경우:

systemctl is-active nginx

가능한 출력에는 active, inactive, failed 또는 activating이 포함됩니다. Nginx가 부팅 시 활성화되어 있는지만 확인하려면 다음을 사용하십시오:

systemctl is-enabled nginx

Nginx가 웹 포트에서 수신 대기 중인지 확인할 수도 있습니다:

sudo ss -ltnp | grep nginx

80 또는 443과 같은 포트에서 리스너가 표시되어야 합니다. 서비스가 활성 상태이지만 예상 포트가 수신 대기 중이 아닌 경우 listen 지시문과 포함된 설정 파일을 확인하십시오.

ss에 아무것도 표시되지 않으면 다른 프로세스가 이미 포트를 사용하고 있는지 확인하십시오:

sudo ss -ltnp 'sport = :80'
sudo ss -ltnp 'sport = :443'

포트 충돌은 Apache, Caddy, 로컬 개발 서버 또는 동일한 포트를 게시하는 컨테이너 런타임을 설치한 후에 흔히 발생합니다. 이 경우 Nginx를 반복적으로 재시작해도 도움이 되지 않습니다. 충돌하는 서비스를 중지하거나 리스너를 변경해야 합니다.

Nginx 시작, 중지, 재시작 및 리로드

Nginx가 실행 중이 아닐 때 start를 사용하십시오:

sudo systemctl start nginx

의도적으로 서비스를 오프라인으로 전환하려면 stop을 사용하십시오:

sudo systemctl stop nginx

프로덕션 서버에서 stop을 사용할 때는 주의하십시오. 다른 서버나 로드 밸런서가 트래픽을 처리하지 않는 한 즉시 서비스를 사용할 수 없게 만듭니다.

완전한 중지 및 시작이 필요할 때 restart를 사용하십시오:

sudo systemctl restart nginx

재시작은 간단하지만 항상 최선의 선택은 아닙니다. 특히 바쁜 서버나 설정에 시작 문제가 있는 경우 활성 연결을 중단시킬 수 있습니다.

Nginx 프로세스 자체가 비정상적인 경우, 모듈 또는 패키지 업데이트에 새 프로세스가 필요한 경우, 또는 의도적으로 작업자 상태를 지우려는 경우 재시작을 사용하십시오. 일반적인 서버 블록 편집, 인증서 경로 업데이트, 업스트림 변경, 리디렉션 및 헤더 변경의 경우 리로드가 일반적으로 더 나은 첫 번째 선택입니다.

대부분의 설정 변경에는 리로드를 선호하십시오:

sudo systemctl reload nginx

리로드는 Nginx 마스터 프로세스에 새 설정을 읽고 새 작업자를 시작하도록 요청합니다. 이전 작업자는 기존 요청을 완료한 후 종료됩니다. 이는 중단을 줄이면서 변경 사항을 적용하는 일반적인 방법입니다.

실용적인 예: api.example.com에 대한 새 서버 블록을 추가합니다. 먼저 sudo nginx -t를 실행하십시오. 테스트가 통과하면 sudo systemctl reload nginx를 실행하십시오. 기존 연결의 사용자는 아무것도 느끼지 못할 것입니다.

Nginx에 직접 리로드를 요청할 수도 있습니다:

sudo nginx -s reload

systemd 시스템에서는 일상적인 작업에 systemctl reload nginx를 선호하십시오. systemd가 서비스 상태 및 로그에 대한 신뢰할 수 있는 출처로 남아 있기 때문입니다. 직접 nginx -s 형식은 systemd가 없는 최소 시스템이나 컨테이너에서 여전히 유용합니다.

리로드와 재시작의 차이점 이해

이 구분은 많은 피할 수 있는 다운타임을 방지합니다.

리로드는 Nginx 마스터 프로세스에 새 설정을 읽고 새 작업자를 시작하도록 지시합니다. 설정이 유효하면 새 작업자가 새 연결을 수락하는 동안 이전 작업자는 기존 작업을 완료하고 종료합니다. 이것이 리로드가 일반적인 프로덕션 경로인 이유입니다.

재시작은 서비스를 중지했다가 시작합니다. 타이밍, 트래픽 및 감독자 동작에 따라 클라이언트는 연결 실패를 볼 수 있습니다. 재시작은 Nginx가 이전에 유효한 이전 설정으로 실행 중이었고 새 설정으로 시작할 수 없는 경우 작은 설정 실수를 중단으로 바꿀 수도 있습니다.

안전한 리듬은 다음과 같습니다:

sudo nginx -t
sudo systemctl reload nginx
sudo systemctl status nginx --no-pager

리로드가 실패하면 계속 시도하지 마십시오. 정확한 오류를 읽고, 파일을 수정하고, 다시 테스트한 다음 리로드하십시오.

변경 사항을 적용하기 전에 설정 테스트

가장 중요한 명령어는 다음과 같습니다:

sudo nginx -t

이 명령은 구문을 확인하고 Nginx가 설정을 로드할 수 있는지 보고합니다. 누락된 세미콜론, 잘못된 파일 경로, 중복 지시문, 알 수 없는 모듈 및 많은 인증서 경로 문제를 잡아냅니다.

다음과 같은 출력이 표시될 수 있습니다:

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

실패하면 줄 번호를 주의 깊게 읽으십시오. Nginx는 구문 분석이 실패한 파일과 줄을 알려주는 경우가 많습니다. 실제 실수는 특히 중괄호나 세미콜론이 누락된 경우 해당 줄 바로 위에 있을 수 있습니다.

포함된 파일을 포함하여 완전히 로드된 설정을 출력하려면 다음을 사용하십시오:

sudo nginx -T

이 명령은 지시문이 포함된 파일을 확실하지 않을 때 유용합니다. /etc/nginx/conf.d/, sites-enabled 또는 패키지 제공 스니펫의 예상치 못한 내용을 드러낼 수 있습니다.

nginx -T는 민감한 경로, 업스트림 이름 및 때로는 포함된 설정 값을 출력할 수 있습니다. 전체 출력을 티켓, 채팅 또는 공개 포럼에 붙여넣을 때는 주의하십시오. 필요한 경우 비밀 및 내부 호스트 이름을 삭제하십시오.

여러 Nginx 인스턴스 또는 사용자 정의 접두어를 유지 관리하는 경우 설정 파일을 명시적으로 지정하십시오:

sudo nginx -t -c /etc/nginx/nginx.conf

대부분의 패키지 시스템에서는 -c가 필요하지 않지만, 스테이징 경로에서 후보 설정을 비교할 때 유용합니다.

더 자세한 명령어 체크리스트는 Nginx 설정 테스트 및 상태 모니터링을 참조하십시오.

서비스 제어 중 로그 보기

명령어가 실패하면 로그가 일반적으로 이유를 설명합니다. 저널로 시작하십시오:

sudo journalctl -u nginx --since "10 minutes ago"

부팅 또는 재시작 실패의 경우 시간 창을 제거하고 최근 항목을 표시하십시오:

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

로그를 실시간으로 보려면:

sudo journalctl -u nginx -f

Nginx는 자체 로그도 작성하며, 일반적으로 여기에 있습니다:

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

systemd 저널은 서비스 시작, 중지, 리로드 및 권한 오류에 가장 적합합니다. Nginx 오류 로그는 업스트림 실패, 누락된 파일, 클라이언트 본문 크기 제한 및 TLS 문제와 같은 런타임 문제에 가장 적합합니다.

서버가 여러 사이트를 호스팅하는 경우 각 서버 블록에 자체 로그 파일이 있는지 확인하십시오. 별도의 로그를 사용하면 서비스 제어 변경을 특정 중단된 도메인에 연결하는 것이 훨씬 쉬워집니다.

리로드 후 저널과 오류 로그를 1분간 확인하십시오:

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

리로드 명령은 빠르게 반환될 수 있지만, 손상된 업스트림, 누락된 루트 디렉토리 또는 권한 문제는 첫 번째 실제 요청이 해당 서버 블록에 도달할 때만 나타날 수 있습니다.

부팅 시 Nginx 활성화 또는 비활성화

재부팅 후 Nginx를 자동으로 시작하려면:

sudo systemctl enable nginx

한 단계로 활성화하고 시작하려면:

sudo systemctl enable --now nginx

자동 시작을 방지하려면:

sudo systemctl disable nginx

비활성화는 현재 실행 중인 서비스를 중지하지 않습니다. 부팅 동작만 변경합니다. 비활성화하고 중지하려면 disable과 stop을 모두 실행하십시오.

프로덕션 시스템에서는 유지 관리 후 부팅 동작을 확인하십시오. 서버는 수동 시작 후 정상으로 보일 수 있지만 Nginx가 활성화되지 않았기 때문에 다음 재부팅 후 복구에 실패할 수 있습니다.

의존성 순서를 확인하려면 유닛을 검사하십시오:

systemctl cat nginx
systemctl show nginx -p WantedBy -p After -p Requires

패키지된 유닛 파일을 직접 편집하지 마십시오. 대신 오버라이드를 사용하십시오:

sudo systemctl edit nginx

이렇게 하면 systemd의 오버라이드 디렉토리에 드롭인이 생성되고 패키지 업그레이드가 더 깔끔해집니다. 유닛 오버라이드를 변경한 후 다음을 실행하십시오:

sudo systemctl daemon-reload
sudo systemctl restart nginx

시작 관계를 이해할 때만 유닛 의존성을 변경하십시오. 많은 Nginx 문제는 systemd 설정이 아닌 Nginx 설정에 속합니다.

의도할 때만 신호 보내기

Nginx에는 마스터 프로세스와 작업자 프로세스가 있습니다. 마스터는 설정을 읽고, 작업자를 관리하며, 신호에 응답합니다. systemd는 이를 대부분 숨기며, 이는 정상적인 운영에 좋습니다.

프로세스 트리를 검사해야 하는 경우:

ps -o pid,ppid,user,cmd -C nginx

일반적으로 root로 실행되는 하나의 마스터 프로세스와 구성된 Nginx 사용자(종종 www-data, nginx 또는 배포판에 따라 nobody)로 실행되는 작업자 프로세스를 볼 수 있습니다.

직접 신호가 존재합니다:

sudo nginx -s reload
sudo nginx -s quit
sudo nginx -s stop

quit는 정상 종료를 요청합니다. stop은 빠르게 종료됩니다. 일상적인 시스템 관리에서는 특별한 이유가 없는 한 systemctl을 사용하십시오. 서비스 상태, 로그 및 재시작 동작을 한 곳에 유지합니다.

피해야 할 일반적인 명령어 실수

설정 테스트 실패 후 리로드하지 마십시오. 리로드는 실패해야 하지만, 이에 의존하는 것은 엉성하고 문제 해결을 더 복잡하게 만듭니다.

정상적인 Nginx 제어에 kill -9를 사용하지 마십시오. systemd와 Nginx 마스터 프로세스가 작업자를 관리하도록 하십시오. 프로세스를 강제 종료하면 혼란스러운 상태와 연결 끊김이 발생할 수 있습니다.

sites-available에서 파일을 편집하고 활성 상태라고 가정하지 마십시오. Debian 스타일 레이아웃에서 활성화된 파일은 일반적으로 sites-enabled의 심볼릭 링크입니다. 다음으로 확인하십시오:

ls -l /etc/nginx/sites-enabled/

인증서 파일 권한을 잊지 마십시오. 리로드 중에 Nginx가 인증서나 키를 읽을 수 없으면 HTTPS 서버 블록이 로드되지 않을 수 있습니다.

sudo systemctl status nginx가 모든 사이트가 작동한다는 것을 증명한다고 가정하지 마십시오. Nginx가 실행 중인 동안 하나의 서버 블록이 죽은 업스트림이나 잘못된 문서 루트를 가리킬 수 있습니다.

변경 사항이 HTTPS와 관련된 경우 HTTP만 테스트하지 마십시오. 인증서 체인, 키 권한, SNI 일치 및 리디렉션 동작은 모두 HTTPS 확인이 필요합니다:

curl -I https://example.com/
openssl s_client -connect example.com:443 -servername example.com </dev/null

curl -I는 많은 확인에 충분합니다. openssl s_client는 더 자세하며 특정 이름으로 제공된 인증서를 검사해야 할 때 유용합니다.

안전한 프로덕션 변경 체크리스트

작은 Nginx 설정 변경의 경우 반복 가능한 체크리스트를 사용하십시오:

1. 의도한 파일을 편집합니다.
2. sudo nginx -t를 실행합니다.
3. 테스트가 실패하면 실행 중인 서비스를 건드리기 전에 설정을 수정합니다.
4. sudo systemctl reload nginx를 실행합니다.
5. sudo systemctl status nginx --no-pager를 확인합니다.
6. curl로 영향을 받는 URL을 테스트합니다.
7. 오류 로그에서 새 메시지를 확인합니다.

예를 들어, 리디렉션을 추가한 후:

sudo nginx -t
sudo systemctl reload nginx
curl -I http://example.com/old-path
sudo tail -n 50 /var/log/nginx/error.log

리버스 프록시 변경의 경우 실제 업스트림 경로를 테스트하십시오:

curl -I https://api.example.com/health
sudo journalctl -u nginx --since "5 minutes ago" --no-pager

이것은 의도적으로 지루합니다. 설정 편집으로 인한 대부분의 Nginx 중단은 누군가 테스트를 건너뛰거나, 잘못된 호스트를 리로드하거나, 영향을 받는 경로를 확인하지 않았기 때문에 발생합니다.

실패한 시작 및 리로드 문제 해결

Nginx가 시작되지 않으면 먼저 설정 테스트를 실행하십시오:

sudo nginx -t

구문이 유효하지만 시작이 여전히 실패하면 저널을 확인하십시오:

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

일반적인 원인은 다음과 같습니다:

• 다른 프로세스가 이미 포트 80 또는 443을 사용하고 있습니다.
• 인증서 또는 키 파일 경로가 잘못되었습니다.
• Nginx가 권한 또는 SELinux/AppArmor 정책으로 인해 파일을 읽을 수 없습니다.
• 참조된 디렉토리가 존재하지 않습니다.
• 패키지 변경 후 nginx.conf에 구성된 동적 모듈이 누락되었습니다.

포트 충돌의 경우:

sudo ss -ltnp 'sport = :80'
sudo ss -ltnp 'sport = :443'

누락된 파일의 경우 Nginx 오류 메시지를 신뢰하십시오. 일반적으로 경로를 지정합니다. 예상한 경로가 아니라 정확히 작성된 대로 경로를 확인하십시오:

sudo ls -l /path/from/error/message

리로드가 실패했지만 Nginx가 여전히 실행 중인 경우 이전 설정이 여전히 활성 상태일 수 있습니다. 좋은 소식입니다: 사용자는 아직 영향을 받지 않을 수 있습니다. 설정을 수정하고, 다시 테스트하고, 다시 리로드하십시오. 활성 설정이 깨끗하게 시작될 수 있다고 확신하지 않는 한 재시작하지 마십시오.

서비스 제어 문제를 에스컬레이션해야 하는 경우

패키지 업그레이드 후 Nginx가 시작되지 않거나, 프로덕션 서버에서 리로드가 실패하거나, systemd가 이해하지 못하는 권한 및 샌드박싱 오류를 표시할 때 DevOps 엔지니어 또는 Linux 관리자에게 문의하십시오. 또한 공유 인프라에서 유닛 파일을 변경하기 전에 도움을 받으십시오.

Nginx가 로드 밸런서 뒤에 있는 경우 상태 확인 및 드레이닝 동작과 함께 재시작을 조정하십시오. 로컬 명령이 예상보다 더 넓은 영향을 미칠 수 있습니다.

가장 안전한 리듬은 간단합니다: 상태 확인, 설정 테스트, 가능하면 리로드, 필요한 경우에만 재시작, 변경 직후 로그 읽기. 이러한 습관은 Nginx 서비스 제어를 스트레스가 아닌 예측 가능하게 만듭니다.