NGINX 가이드·약 5분 내외

NGINX location과 proxy_pass 이해하기

NGINX 설정에서 location 지시어가 무엇인지, proxy_pass로 요청을 백엔드에 어떻게 전달하는지 정리합니다. API가 여러 개일 때 설정을 나눠야 하는지도 함께 설명합니다.

location 지시어란?

location은 NGINX 설정 파일에서 특정 URL 경로로 들어온 요청을 어떻게 처리할지 지정하는 블록입니다. 사용자가 접속한 주소(URI)를 감지해 경로별로 다른 처리를 적용할 수 있습니다.

🔀

경로별 라우팅

/api/로 시작하는 요청을 Node.js, Spring 등 백엔드 서버로 넘깁니다(proxy_pass).

📁

정적 파일 연결

/images/나 /css/ 같은 경로 요청을 서버 내 특정 폴더와 연결합니다.

🔒

보안 및 권한 제어

특정 경로에만 인증(auth_basic)이나 접근 제한을 다르게 적용합니다.

location 기본 예시

server {
    listen 80;

    # 일반 웹페이지 요청은 정적 폴더로 연결
    location / {
        root /var/www/html;
    }

    # /api/로 시작하는 요청은 백엔드 API 서버로 전달
    location /api/ {
        proxy_pass http://localhost:3000/;
    }
}

proxy_pass란?

proxy_pass는 NGINX가 받은 클라이언트 요청을 다른 서버(백엔드)로 대신 전달하라는 지시어입니다. NGINX는 안내 데스크처럼 요청을 받아 내부 담당 서버로 넘기고, 결과를 다시 클라이언트에게 돌려줍니다.

proxy_pass 없을 때

•백엔드 서버 주소·포트가 외부에 노출
•CORS 에러 발생 가능
•로드 밸런싱 불가

proxy_pass 사용 시

API가 여러 개면 location도 여러 개 써야 하나요?

API 엔드포인트마다 location을 따로 선언해야 하나요?

아닙니다. location /api/ 하나만 선언하면 /api/users, /api/products 등 모든 하위 경로가 해당 블록을 따릅니다. 이를 접두사 매칭(Prefix Matching)이라고 합니다.

하나의 백엔드 서버로 모든 API 전달 (일반적인 경우)

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

여러 개 선언이 필요한 경우

백엔드 서버(목적지)가 서로 다를 때만 나눠 선언합니다. 예를 들어 마이크로서비스 구조에서 회원 API와 결제 API가 각각 다른 포트에서 동작할 때입니다.

백엔드가 분리된 경우 (마이크로서비스)

# 회원 관련 API는 3000번 서버로
location /api/users/ {
    proxy_pass http://localhost:3000;
}

# 결제 관련 API는 4000번 서버로
location /api/payments/ {
    proxy_pass http://localhost:4000;
}

주의: proxy_pass 끝 슬래시(/) 유무

proxy_pass 주소 맨 뒤에 슬래시(/)를 붙이느냐 안 붙이느냐에 따라 백엔드로 전달되는 경로가 달라집니다. 사용자가 /api/v1/users로 요청했을 때를 기준으로 비교하면 다음과 같습니다.

슬래시 없음 (경로 유지)

•proxy_pass http://localhost:3000;
•→ 백엔드에 /api/v1/users 그대로 전달
•백엔드 코드에도 /api 경로 포함 필요