Nginx 설정 검사부터 반영 확인까지: nginx -t 성공 뒤에도 볼 것

Nginx 설정을 고쳤는데 페이지는 그대로다. 또는 nginx -t가 실패했는데 기존 사이트는 계속 열린다. 두 상황은 모순이 아니다. 파일을 검사하는 단계와 실행 중인 서버가 새 설정을 읽는 단계가 다르기 때문이다. 이 글은 운영 서비스를 멈추지 않고 별도의 로컬 Nginx로 그 차이를 확인한 기록이다.

먼저 검사할 파일과 실행 중인 서버를 구분한다

2026년 9월 12일 최초 실험에서는 정상 설정으로 서버를 시작하고, 복사한 후보 파일에 존재하지 않는 지시어를 추가했다. 아래 명령의 -c는 검사할 후보, -p는 상대 경로의 기준을 지정한다. YOUR_LAB_DIRECTORY는 자신이 만든 실험 경로로 바꿔야 한다. 운영 서버의 기본 설정을 바꾸는 명령이 아니다.

nginx -t -p /YOUR_LAB_DIRECTORY/ \
  -c /YOUR_LAB_DIRECTORY/invalid.conf

검사 프로세스의 종료 코드는 1이었고 unknown directive가 출력됐다. 기존 페이지는 200이었다. 후보 파일을 검사했을 뿐 실행 중인 서버에 적용하지 않았으므로 가능한 결과다. 이 관찰은 잘못된 설정을 실제로 reload해도 안전하다는 실험이 아니다.

오류 메시지에서 다음 행동을 정한다

위 표의 unknown directive는 직접 관찰한 오류다. 다른 파일·권한 오류 항목은 공식 명령 설명을 바탕으로 한 진단 안내이며 이번에 각각의 장애를 재현한 것은 아니다. 오류를 없애려고 권한을 일괄 완화하기보다 검사한 파일과 실행 계정부터 좁히는 편이 좋다.

후보가 통과해도 응답은 아직 이전 값이었다

9월 22일 KST 보강 실험에서는 /version이 config-v1을 반환하는 임시 서버를 만들었다. 잘못된 후보를 검사한 다음 config-v2를 반환하도록 고친 후보도 검사했다. 수정한 후보의 검사 종료 코드는 0이었지만, 적용 전 요청은 여전히 config-v1이었다.

검증된 후보를 그 임시 서버의 활성 설정 경로로 교체하고, 스크립트가 직접 시작한 master PID에만 HUP을 보낸 뒤 새 요청이 config-v2로 바뀌었다. 시스템 Nginx 서비스에는 신호를 보내지 않았다. 응답이 바뀌었다는 확인은 한 로컬 요청의 관찰이며 동시 접속이나 무중단성을 측정한 결과는 아니다.

실제 변경은 검사·반영·응답 확인을 한 묶음으로

1. 검사 대상 기록

   사용 중인 설정 경로와 후보 경로, 되돌릴 파일을 구분한다.

2. 후보 검사

   실제 반영할 파일과 같은 include·경로 조건으로 검사한다.

3. 대상에 반영

   검사를 통과한 파일을 해당 서비스의 절차로 반영한다.

4. 응답 대조

   상태 코드뿐 아니라 바꾼 본문·헤더가 나오는지 확인한다.

Ubuntu에서 systemd로 관리하는 Nginx라면 systemctl cat nginx의 ExecStart·ExecReload를 읽어 실행 경로를 확인할 수 있다. 수동 실행, 컨테이너, 다른 prefix를 쓰는 서버에는 같은 명령을 그대로 적용하지 않는다. nginx -T는 포함된 설정까지 출력하므로 결과를 공개할 때 비밀값이나 내부 주소가 있는지 살펴야 한다.

systemctl cat nginx
nginx -V

# 아래는 실제로 존재하는 확인용 URL로 바꾼다.
curl -sS --connect-timeout 3 --max-time 10 \
  -D response-headers.txt -o response-body.html https://example.com/

Nginx 공식 문서는 reload 시 새 설정 적용에 실패하면 이전 설정으로 계속 동작하는 절차를 설명한다. 그러나 신호 명령의 성공만으로 기대한 응답이 바뀌었다고 판단하지는 않는다. 해당 서비스의 오류 기록과 변경한 경로의 실제 응답을 함께 확인해야 한다.

404인데 curl 종료 코드는 0이었습니다

2026년 10월 22일 KST, 별도 루프백 HTTP 서버의 정상 경로와 없는 경로를 curl로 요청했습니다. 404 응답도 기본 옵션에서는 종료 코드 0이었습니다. 같은 요청에 --fail을 추가했을 때는 404에서 종료 코드 22가 나왔습니다. Nginx 검사 성공 뒤 응답 확인을 붙여도 curl 프로세스의 성공만 읽으면 없는 페이지를 정상으로 판정할 수 있다는 별도 실험입니다.

-sS는 진행 표시와 오류 메시지 출력을 조절하며 HTTP 404를 자동으로 실패 처리하는 옵션이 아닙니다. 이번 관찰에서는 --fail이 404 본문도 저장하지 않았습니다. 진단용 본문을 보존해야 한다면 HTTP 상태와 본문을 따로 저장하고 판정하는 방법을 선택하세요. --fail을 추가해도 200으로 잘못 반환된 홈 화면이나 다른 릴리스 본문은 찾지 못하므로 기대한 상태·내용도 대조해야 합니다.

# 본인 사이트의 실제 확인 URL과 예상 문자열로 바꾼다.
if ! status=$(curl -q --noproxy '*' -sS --connect-timeout 3 --max-time 10 \
  -o response-body.html -w '%{http_code}' https://example.com/version); then
  echo '전송 실패' >&2
  exit 1
fi
[ "$status" = 200 ] || { echo "예상하지 않은 HTTP 상태: $status" >&2; exit 1; }
grep -Fq 'EXPECTED-RELEASE' response-body.html || { echo '예상 본문 없음' >&2; exit 1; }

문법이 맞아도 웹사이트의 동작은 틀릴 수 있다

존재하지 않는 글을 홈 화면으로 넘기거나 특정 location에서 보안 헤더를 빠뜨린 설정도 문법 검사만으로는 원하는 동작인지 알 수 없다. 따라서 대표 글 하나뿐 아니라 없는 URL, 정적 자산, 오류 응답을 검사 대상으로 정한다. 반영에 문제가 있으면 보관한 이전 설정을 검사한 뒤 같은 절차로 복원하고 다시 요청한다.

• 없는 글과 CSS가 200으로 열린다: Nginx try_files 진단 순서

  없는 글과 자산이 홈 화면으로 바뀌는지 상태·본문으로 확인한다.

• nginx -t는 통과했는데 응답 헤더가 사라졌다: 상속과 always

  검사를 통과한 설정에서 헤더가 빠지는 조건을 비교한다.

python3 run-lab.py --output observations.json

python3 lab-nginx-candidate-routes.py --output new-observations.json

python3 lab-curl-http-exit.py --output lab-curl-http-exit-result.json