nginx 리버스 프록시

5. 자주 하는 실수 (Tip)

❌ 실수 1: location / 하나로 정적 파일까지 프록시로 보낸다

정적 파일까지 매번 Tomcat 을 거치면 응답이 느려지고 백엔드 스레드를 낭비합니다. ^~ /static/ 을 먼저 두고 alias 로 nginx 가 직접 서빙합니다.

❌ 실수 2: proxy_pass 끝 슬래시를 빼먹는다

슬래시 유무로 백엔드가 받는 경로가 통째로 달라집니다. 앱 컨텍스트 경로와 맞춰 둘 중 하나로 통일하고 팀 안에서 규칙을 공유합니다.

❌ 실수 3: Host 헤더를 안 넘긴다

Host 를 안 넘기면 백엔드는 localhost 나 기본 가상호스트로 요청을 받습니다. 버추얼 호스트를 쓰는 앱에서는 엉뚱한 사이트로 라우팅됩니다.

❌ 실수 4: X-Forwarded-Proto 를 안 넘긴다

Tomcat 이 HTTPS 요청을 HTTP 로 착각해 302 리다이렉트를 다시 HTTP 로 걸면 무한 리다이렉트가 생깁니다. RemoteIpValve 와 이 헤더는 항상 짝으로 둡니다.

❌ 실수 5: proxy_read_timeout 기본값 60초를 그대로 둔다

배치성 요청이나 큰 리포트 다운로드는 60초를 넘기기 쉬워 504 가 납니다. 앱의 가장 긴 요청 시간을 재고 그보다 길게 잡습니다.

❌ 실수 6: 웹소켓 경로에 Upgrade 헤더를 안 넣는다

Upgrade·Connection: upgrade 가 없으면 연결이 일반 HTTP 로 처리돼 끊깁니다. 웹소켓 전용 location 을 따로 두고 헤더를 명시합니다.

❌ 실수 7: client_max_body_size 기본값을 안 늘린다

기본 1m 를 넘는 업로드는 nginx 단계에서 413 으로 막혀 앱 로그에는 아무 기록도 안 남습니다. 앱이 허용하는 최대 크기에 맞춰 값을 올립니다.

❌ 실수 8: 정규식 location 순서를 잘못 둔다

~ 정규식은 파일에 쓴 순서대로 첫 일치를 쓰기 때문에, 넓은 패턴을 먼저 두면 좁은 패턴이 영원히 매칭되지 않습니다. 구체적인 패턴을 위에 둡니다.

❌ 실수 9: keepalive 를 켜고 Connection 헤더를 안 비운다

upstream 에 keepalive 를 줘도 proxy_set_header Connection "" 이 없으면 매 요청마다 연결이 닫혀 효과가 없습니다. proxy_http_version 1.1 과 세 줄을 항상 같이 씁니다.

❌ 실수 10: nginx -t 없이 바로 reload 한다

오타 하나로 reload 가 실패하면 워커가 죽거나 이전 설정으로 남습니다. 수정 뒤에는 항상 nginx -t 로 문법을 먼저 확인합니다.