Nginx 설정 실수로 서비스가 내려갈 때

Nginx 설정을 건드린 후로 계속 뭔가 이상하다. 요청이 제대로 전달되지 않거나, SSL 에러가 나거나, 응답 헤더가 없거나. 어디서부터 확인해야 할까?

Nginx는 수정 후에 바로 실행되지 않으니까, 설정 문법 에러를 놓치기 쉽다. 또한 프록시 규칙이 복잡하면, 요청이 정확히 어디로 가는지 알 수 없을 수 있다.

Nginx 설정 문법 확인

변경 후 반드시 먼저 할 일:

sudo nginx -t
# 설정 문법이 올바른가?

sudo nginx -T
# 전체 설정을 상세히 본다

문법 에러가 없다면 이미 절반은 성공한 거다.

프록시 규칙 확인

요청이 실제로 어디로 가는지 로그로 본다.

server {
  listen 80;
  server_name example.com;

  location /api/ {
    proxy_pass http://backend:3000;
    # 중요: 이 규칙이 요청을 어디로 보내는가?
  }
}

Curl로 직접 확인해본다:

curl -X GET http://example.com/api/users \
  -H "Host: example.com"
# 백엔드에 도착하는가? 404는 뭔가?

HTTP 상태 코드

• 200: 성공
• 301/302: 리다이렉트 (Location 헤더 확인)
• 400-499: 클라이언트 에러
• 500-599: 서버 에러

Curl의 -v 옵션으로 전체 응답을 본다:

curl -v http://example.com/api/users
# 상태 코드, 헤더, 본문을 모두 본다

DNS와 프록시

백엔드 서버를 프록시할 때, Nginx가 그 주소를 제대로 resolve할 수 있는가?

dig backend  # 또는 hostname
# DNS 응답이 있는가?

# 또는 Nginx에서 직접
curl http://backend:3000/health
# Nginx 컨테이너 내에서 백엔드에 접근 가능한가?

Kubernetes나 Docker 환경에서 DNS 이름이 resolve되지 않는 경우가 종종 있다.

헤더 전달

Nginx가 필요한 헤더를 백엔드에 전달하는가? 보통:

proxy_pass http://backend:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

Authorization 헤더는? Origin 헤더는? 커스텀 헤더가 필요하면 추가한다.

캐싱 문제

브라우저나 Nginx가 응답을 캐싱하고 있다면, 설정 변경 후에도 이전 내용이 나올 수 있다.

curl -H "Cache-Control: no-cache" http://example.com/api/users
# 캐싱을 무시하고 요청

Nginx 설정에서 expires off;나 proxy_no_cache 1;을 추가할 수 있다.

실제 확인 순서

1. nginx -t 로 문법 확인
2. curl -v 로 실제 응답 확인 (상태 코드, 헤더, 본문)
3. DNS resolve 확인
4. 필요한 헤더가 전달되는지 백엔드 로그에서 확인
5. 캐싱이 문제면 Cache-Control 헤더 추가

Nginx는 설정이 복잡할수록 문제가 생기기 쉽다. 변경 전에 현재 설정을 백업해두고, 한 번에 하나씩만 수정하자. 그래야 뭐가 문제인지 빨리 찾을 수 있다.