nginx: proxy_pass 슬래시(/)로 서브패스 프록시 경로가 꼬일 때

location /api/ 같은 서브패스 프록시에서 가장 흔한 버그는 proxy_pass의 / 유무로 업스트림에 전달되는 경로가 달라지는 것입니다.

관련 가이드: 서브패스(/app)로 앱을 프록시할 때의 체크리스트

규칙: URI가 붙었는지(슬래시 포함)로 결정됨

1) prefix를 유지하고 싶을 때 (/api가 그대로 전달)

location /api/ {
  proxy_pass http://127.0.0.1:3000;
}

• 클라이언트: /api/hello
• 업스트림: /api/hello

2) prefix를 제거하고 싶을 때 (/api를 떼고 전달)

location /api/ {
  proxy_pass http://127.0.0.1:3000/;
}

• 클라이언트: /api/hello
• 업스트림: /hello

실무 체크리스트

• “앱이 어디에 마운트되어 있는지”(/인지 /api인지)부터 확정
• 프록시 뒤 앱이라면 X-Forwarded-* 전달 + 앱의 trust proxy 설정 확인
• curl -v로 실제 요청/리다이렉트를 확인

관련 용어: X-Forwarded-For, X-Forwarded-Proto, trust proxy