Nginx 리버스 프록시를 이용한 페이지 분리 및 통합

Nginx 리버스 프록시 서버가 URL 경로를 해석하여 각 팀이 독립적으로 운영하는 서버로 라우팅하는 방식의 마이크로 프론트엔드 통합 패턴(Linked SPA)을 학습한다.

학습 목표

Nginx 리버스 프록시의 역할과 마이크로 프론트엔드에서의 활용 방식을 설명할 수 있다
URL 경로 기반 라우팅(location 디렉티브)으로 팀별 서버를 연결하는 구성을 이해한다
이 방식의 장점(동일 오리진, 팀 독립성)과 단점(리소스 중복, 하드 네비게이션)을 구분한다
Linked SPA와 Unified SPA의 차이를 설명할 수 있다

1. Nginx 리버스 프록시란

1.1 리버스 프록시의 역할

Nginx는 웹에서 가장 널리 사용되는 웹 서버이자 리버스 프록시 서버이다. **리버스 프록시(Reverse Proxy)**란 사용자의 요청을 가장 먼저 받아, 내부의 서버로부터 리소스를 대신 요청하고 받아서 제공하는 중개자를 말한다.

1.2 리버스 프록시가 제공하는 이점

이점	설명
로드 밸런싱	여러 서버에 요청을 분산하여 성능과 가용성 향상
캐싱	정적 리소스를 Nginx 레벨에서 캐싱하여 백엔드 부하 감소
보안	내부 서버의 IP/포트를 외부에 노출하지 않음
SSL 종단	Nginx에서 SSL을 처리하고, 내부 통신은 HTTP로 수행
압축	gzip 등으로 응답을 압축하여 전송 효율 향상

2. 아키텍처 구성

2.1 전체 구성도

마이크로 프론트엔드에서 Nginx 프록시를 사용하면, 사용자는 하나의 도메인으로 접근하지만 실제로는 URL 경로에 따라 서로 다른 팀의 서버가 응답한다.

2.2 Nginx 설정 파일 구조

Nginx 설정은 upstream과 server 블록으로 구성된다.

nginx

# upstream: 내부 서버 정의
upstream team_home {
    server host.docker.internal:3001;
}
upstream team_jobs {
    server host.docker.internal:3002;
}
upstream team_network {
    server host.docker.internal:3003;
}

# server: 프록시 라우팅 규칙
server {
    listen 3000;

    # /network/* 로 시작하는 요청 → 팀 네트워크 서버
    location /network {
        proxy_pass http://team_network;
    }

    # /jobs/* 로 시작하는 요청 → 팀 잡스 서버
    location /jobs {
        proxy_pass http://team_jobs;
    }

    # 나머지 모든 요청 → 팀 홈 서버
    location / {
        proxy_pass http://team_home;
    }
}

핵심 포인트:

upstream 블록에서 내부 서버의 주소를 정의한다
location 블록에서 URL 경로에 따라 어떤 upstream으로 프록시할지 결정한다
더 구체적인 경로(/network, /jobs)가 먼저 매칭되고, 나머지는 /에 매칭된다
Docker 환경에서는 host.docker.internal로 호스트 머신의 서버에 접근한다

3. Linked SPA 패턴

3.1 Linked SPA란

각 팀의 서버가 독립된 SPA를 운영하고, 팀 간 전환은 <a> 태그를 통한 **하드 네비게이션(Hard Navigation)**으로 처리하는 패턴이다.

네비게이션 유형	설명	사용 위치
소프트 네비게이션	클라이언트 라우터로 URL 변경, 전체 새로고침 없음	SPA 내부
하드 네비게이션	`<a href>` 또는 `location.href` 변경, 전체 페이지 새로고침	SPA 간 전환

html

<!-- 팀 홈의 네비게이션 -->
<nav>
  <ul>
    <!-- 하드 네비게이션: 다른 팀 SPA로 이동 -->
    <li><a href="/">홈</a></li>
    <li><a href="/jobs">채용</a></li>
    <li><a href="/network">네트워크</a></li>
  </ul>
</nav>

3.2 Linked SPA vs Unified SPA

비교 항목	Linked SPA	Unified SPA
전환 방식	하드 네비게이션 (페이지 새로고침)	소프트 네비게이션 (SPA 전환)
공유 상태	없음 (각 SPA 독립)	전역 상태 공유 가능
공통 UI	각 SPA에서 중복 구현	Shell이 공통 UI 제공
구현 기술	Nginx 프록시	Module Federation
팀 간 결합도	매우 낮음	중간

Linked SPA는 Nginx 프록시만으로 구현 가능한 가장 단순한 마이크로 프론트엔드 패턴이다. Module Federation이 필요 없으며, 각 팀이 완전히 독립적으로 개발/배포할 수 있다.

4. 장점

4.1 동일 오리진 이점

Nginx 프록시를 통해 모든 서버가 같은 도메인(service.com)으로 노출되므로:

CORS 문제가 발생하지 않음: 프래그먼트 로딩이나 API 호출 시 크로스 오리진 이슈 없음
쿠키/세션 공유 가능: 동일 도메인이므로 인증 쿠키가 자연스럽게 공유됨
사용자 신뢰: 하나의 도메인으로 서비스되므로 사용자가 동일 서비스로 인식

4.2 팀별 독립 인프라

각 팀은 자신만의 서버, 빌드 파이프라인, 배포 프로세스를 운영한다. 내부망 엔드포인트만 Nginx에 공유하면 되므로, 기술 스택도 팀별로 자유롭게 선택할 수 있다.

4.3 도입 용이성

Nginx 리버스 프록시는 이미 대부분의 서비스에서 사용하는 매우 일반적인 인프라이다. 기존 인프라에 location 블록만 추가하면 되므로 도입 비용이 매우 낮다.

4.4 장애 전파 차단

각 팀의 서버가 완전히 분리되어 있으므로, 한 팀의 서버 장애가 다른 팀에 전파되지 않는다. 팀 잡스 서버가 다운되어도 팀 홈과 팀 네트워크는 정상 동작한다.

5. 단점

5.1 리소스 중복 로딩

각 팀이 독립적으로 번들링하므로, 공통 라이브러리(React, lodash 등)가 팀별로 중복 포함된다. 사용자는 팀 간 이동 시마다 같은 라이브러리를 다시 다운로드해야 한다.

5.2 페이지 이동 시 전체 새로고침

팀 간 전환은 하드 네비게이션이므로 전체 페이지가 새로고침된다. 이때 깜빡임이 발생하며, SPA 수준의 매끄러운 전환 경험을 제공할 수 없다.

5.3 공통 UI 공유 어려움

헤더, 푸터, 사이드바 같은 공통 UI를 각 팀에서 별도로 구현해야 한다. 공통 컴포넌트를 NPM 패키지로 공유할 수 있지만, 각 팀이 빌드 타임에 통합하므로 버전 동기화가 필요하다.

5.4 SPA 라우팅 주의사항

각 팀의 SPA가 클라이언트 라우터를 사용할 때, base path를 올바르게 설정해야 한다. 팀 잡스의 SPA는 /jobs를 base path로 사용해야 하며, 이를 잘못 설정하면 라우팅이 깨진다.

javascript

// 팀 잡스의 Vite 설정
export default defineConfig({
  base: '/jobs/',
  server: {
    host: true,
    port: 3002
  }
});

6. 실전 구성 패턴

6.1 Docker + Nginx 조합

프로덕션에서는 Nginx를 Docker 컨테이너로 실행하는 것이 일반적이다.

dockerfile

FROM nginx:alpine
COPY proxy-server.conf /etc/nginx/conf.d/proxy-server.conf
EXPOSE 3000

6.2 팀별 서버 구성

각 팀은 독립적인 프로젝트로 운영하며, pnpm workspace와 TurboRepo로 개발 환경을 관리할 수 있다.

yaml

# pnpm-workspace.yaml
packages:
  - 'teams/*'    # 각 팀의 SPA 프로젝트
  - 'apps/*'     # Nginx 프록시 서버

6.3 팀 간 이동 시 UX 개선 방안

7. 적합한 사용 시나리오

적합한 경우	부적합한 경우
팀 간 전환이 빈번하지 않은 서비스	팀 간 전환이 매우 잦은 서비스
각 팀이 완전한 기술 독립성을 원하는 경우	공통 상태 관리가 필수인 경우
기존 인프라에 최소 비용으로 도입	SPA 수준의 매끄러운 전환이 필수
장애 전파 차단이 중요한 서비스	리소스 최적화가 최우선인 경우
서비스 규모가 크고 팀이 많은 조직	소규모 팀에서 운영하는 단일 서비스

핵심 정리

Nginx 리버스 프록시는 URL 경로(location)에 따라 서로 다른 내부 서버로 요청을 전달하는 가장 일반적이고 도입이 쉬운 마이크로 프론트엔드 인프라이다.
동일 오리진으로 노출되므로 CORS 문제가 없고, 쿠키/세션 공유가 자연스러우며, 사용자는 하나의 서비스로 인식한다.
각 팀이 독립 인프라를 운영하므로 장애 전파가 차단되고, 기술 스택을 자유롭게 선택할 수 있다.
단, 팀 간 이동 시 전체 새로고침이 발생하고, 공통 리소스가 중복 로딩되며, 공통 UI 공유가 어렵다.
팀 간 전환이 빈번하지 않은 서비스에서 Linked SPA 패턴으로 가장 효과적이며, 전환이 잦은 서비스에는 Module Federation(Unified SPA) 도입을 검토해야 한다.

다음 단계

SSI 서버사이드 인클루드: Nginx SSI 기능을 이용해 서버에서 HTML 프래그먼트를 조합한 후 클라이언트에 완성된 페이지를 전달하는 방식을 학습한다.

Nginx 리버스 프록시를 이용한 페이지 분리 및 통합 ​

학습 목표 ​

1. Nginx 리버스 프록시란 ​

1.1 리버스 프록시의 역할 ​

1.2 리버스 프록시가 제공하는 이점 ​

2. 아키텍처 구성 ​

2.1 전체 구성도 ​

2.2 Nginx 설정 파일 구조 ​

3. Linked SPA 패턴 ​

3.1 Linked SPA란 ​

3.2 Linked SPA vs Unified SPA ​

4. 장점 ​

4.1 동일 오리진 이점 ​

4.2 팀별 독립 인프라 ​

4.3 도입 용이성 ​

4.4 장애 전파 차단 ​

5. 단점 ​

5.1 리소스 중복 로딩 ​

5.2 페이지 이동 시 전체 새로고침 ​

5.3 공통 UI 공유 어려움 ​

5.4 SPA 라우팅 주의사항 ​

6. 실전 구성 패턴 ​

6.1 Docker + Nginx 조합 ​

6.2 팀별 서버 구성 ​

6.3 팀 간 이동 시 UX 개선 방안 ​

7. 적합한 사용 시나리오 ​

핵심 정리 ​

다음 단계 ​