Nginx 리버스 프록시가 요청을 제대로 전달하지 않을 때

Nginx 리버스 프록시 설정은 정말 작은 실수도 크게 영향을 미친다. 같은 요청도 프록시 규칙에 따라 다른 곳으로 전달되거나 아예 차단될 수 있다.

HTTP 상태 코드로 문제 범위 좁히기

문제가 생기면 먼저 HTTP 상태 코드를 확인하는 게 가장 빠르다:

• 404 → 경로가 잘못 설정됐거나 백엔드 서버가 없음
• 502/503 → 백엔드 서버가 응답하지 않음
• 301/302 → 리다이렉트가 일어남 (원하지 않은 리다이렉트일 수 있음)
• 200 이지만 이상한 응답 → 프록시 헤더 설정 문제

dig example.com
curl -I https://example.com
sudo nginx -t

이 명령들로 DNS 설정, HTTP 상태, Nginx 설정의 문법을 순서대로 확인할 수 있다.

Nginx 설정 검증하기

nginx -t 명령은 설정 파일의 문법만 체크한다. 파일이 제대로 읽혀도 논리적인 오류는 못 찾는다. 그래서 설정을 바꾼 후에는:

1. sudo nginx -t로 문법 확인
2. sudo systemctl reload nginx로 적용
3. 실제 요청을 보내서 테스트

이 순서를 따라야 한다.

프록시 규칙 확인하기

upstream 블록과 location 블록의 매칭이 제대로 되는지 확인해야 한다. 정규식을 사용한 경로 매칭은 특히 조심해야 한다.

인증서 설정이 영향을 미칠 수 있다

HTTPS를 쓸 때 인증서 경로가 잘못되면 HTTPS 핸드셰이크가 실패한다. 또한 자체 서명 인증서를 쓸 때는 브라우저에서 경고가 나타날 수 있다.

캐시 문제 체크하기

Nginx가 응답을 캐시하고 있다면, 백엔드 설정을 바꿔도 캐시된 응답을 받을 수 있다. 테스트할 때는 캐시를 비활성화하거나 cache-control 헤더를 확인해야 한다.

체계적인 테스트 순서

리버스 프록시 문제를 진단할 때:

1. 원하는 것과 같은 상황을 다시 만들어본다.
2. 로그(access log, error log)를 남긴다.
3. HTTP 상태 코드를 기록한다.
4. 한 가지 설정만 바꾼다.

작은 변경과 확인을 반복하면 자연스럽게 원인이 보인다.