Nginx 문제를 빠르게 파악하는 확인 순서

Nginx 문제를 마주했을 때 가장 먼저 할 일은 재현 가능한 증상을 정확히 파악하는 것이다. 제일 많이 하는 실수는 증상을 크게 잡으려다 확인할 범위를 너무 넓히는 것이다.

핵심은 트래픽이 어디서 어떻게 흐르는지 경로를 따라가면서 하나씩 확인하는 것이다. 화면에 보이는 에러만 보고 판단하면 놓치는 값이 많다. 응답 코드, 설정, 로그, 인증서까지 눈으로 확인할 수 있는 값들을 먼저 모아야 한다.

도메인부터 확인하기

DNS가 제대로 설정되지 않으면 나머지 확인이 모두 헛수고가 된다. 먼저 도메인이 올바른 서버를 가리키는지 확인해야 한다.

dig example.com
curl -I https://example.com

dig로 DNS 응답을 확인하고, curl로 실제 응답 헤더를 본다. 이 두 가지만으로 도메인과 웹 서버 연결 상태를 파악할 수 있다.

Nginx 설정이 문법 에러는 없는지

설정 파일을 고쳤다면 배포 전에 반드시 문법을 확인해야 한다. 작은 오타가 전체 서버를 내릴 수 있다.

sudo nginx -t

에러가 있으면 어느 줄인지 정확히 알려준다. 이 명령어 실행 후 OK가 나올 때까지는 다음 단계로 넘어가지 않는다.

로컬에서 테스트했던 설정과 운영 환경의 차이

개발할 때 로컬에서는 작동했는데 서버에서 실패하는 경우가 자주 있다. 포트, 인증서 경로, 환경 변수 등이 다를 수 있기 때문이다.

원인을 좁히려면 변경 전후의 상태를 기록해두는 게 가장 빠르다. 하나씩 수정해보고 각 단계마다 응답을 확인한다. 여러 설정을 한 번에 바꾸면 어떤 것이 원인인지 구분할 수 없다.

캐시 때문에 헷갈릴 수 있다

브라우저나 DNS 캐시 때문에 변경 사항이 바로 반영되지 않을 수 있다. 특히 운영 환경에서는 캐시를 의심해야 한다.

변경 후에도 예전 응답이 나온다면, 개인 시크릿 창에서 다시 시도하거나 브라우저 캐시를 지운다. 또는 curl에 특정 헤더를 포함해서 요청하는 것도 방법이다.

체크리스트

Nginx 문제를 다룰 때마다 이 순서로 확인하면 같은 실수를 반복하지 않을 수 있다.

1. dig와 curl로 도메인 연결 상태를 확인한다
2. nginx -t로 설정 문법을 검사한다
3. 변경한 설정과 이전 상태를 비교한다
4. 응답 헤더와 상태 코드를 기록한다
5. 브라우저 캐시를 의심해본다

지금 발생한 문제가 설정 때문인지, 도메인 때문인지, 아니면 캐시 때문인지 구분할 수 있으면 해결이 훨씬 빨라진다. 관련 기록을 짧게라도 남겨두면 다음 확인이 훨씬 효율적이다.