Nginx include 디렉티브 - 설정 파일 분리와 구조화

이전 글에서는 Nginx의 계층 구조 속에서 설정이 어떻게 상속되는지를 살펴봤다.

 

상속을 잘 활용하면 공통 설정을 한 곳에 모을 수 있는데, 서버 규모가 커지면 nginx.conf 하나에 모든 설정을 몰아넣는 것만으로는 한계가 생긴다. 가상 호스트가 10개, 20개가 되거나 upstream 설정, SSL 설정, 보안 헤더 설정이 뒤섞이기 시작하면 파일 하나가 수백 줄을 넘어가게 된다.

 

이 문제를 해결하는 것이 바로 include 디렉티브다.

 

include 디렉티브란?

include는 다른 파일의 내용을 현재 위치에 그대로 삽입하는 디렉티브다.

프로그래밍 언어로 따지면 Java의 import와 비슷한 개념으로, Nginx가 설정 파일을 파싱할 때, include를 만나면 해당 파일을 읽어서 그 자리에 내용을 붙여넣은 것처럼 처리할 수 있도록 지원한다.

 

아래와 같은 예시를 살펴보자.

include /etc/nginx/conf.d/*.conf;

 

위 한 줄은 /etc/nginx/conf.d/ 디렉터리 안의 .conf 파일을 전부 읽어서 현재 위치에 포함시키라는 의미다.

그리고 아래와 같이 작성해볼 수 있다.

 

위의 설정 파일의 내용은 include 를 사용하여 외부의 설정파일을 http Block에서 사용하고 있다.

각 해당 설정파일을 nginx.conf에 직접 적는다고 하면 하나의 nginx.conf 파일에 모든 설정에 대한 내용들을 적게 될 것이고 

양이 비대해질 것이다. 

 

따라서 각 설정 파일에 대한 내용들을 분리하고 관리하기 위해서 별도의 설정 파일을 두고 include를 사용하여 관리하는 것이다.

이러한 Nginx의 관리적 측면에서 가장 기본적인 내용을 제외하고는 별도의 관리 포인트는 전부 별도로 관리하는 것이 유지보수적인 측면에서 유리하여 아래와 같은 분리를 고려할 수 있다.(실제로 실무에서도 최대한 분리한다고 한다.)

 

각 파일 설정 구성과 include

 

이는 아래와 같이 설정 파일을 구성할 수 있다.

 

servers 파일를 만들어주고, 존재하는 conf.d 폴더 내에 gzip.conf 파일을 만들어준다.

그리고 아래처럼 gzip.conf 파일의 내용을 설정해준다.

 

 

한편, server 폴더를 생성하고(mkdir server),

mysite.conf 파일을 만들어서 아래와 같이 설정 내용을 적어준다.

 

mysite.conf의 설정 파일 내용

 

그리고 이러한 설정 파일들은 각 모듈로 http 최상단 Block에서 include로 설정 내용을 끌어올 수 있게 된다.

이는 역할별 분리를 가능하도록 만들어주며, 공통 설정을 하나의 설정 파일만 변경하면 되는 장점을 지닌다. 

또한 서버 확장에 용이하며, 문제 사항이 발견되었을 시에 추적 및 버젼 변경을 쉽게 만든다. 

 

 

상속 가능 디렉티브 vs 상속 불가능 디렉티브

단, 중요한 주의사항이 있다. 모든 디렉티브가 상속되는 것은 아니다.

Nginx의 디렉티브는 상속 여부에 따라 아래와 같이 나눌 수 있다.

상속되지 않는 디렉티브

특정 디렉티브는 설계상 해당 블록에서만 유효하며, 하위 블록으로 상속되지 않는다.

상속이 안되는 디렉티브 종류

listen 
server_name
location 블록 자체

 

예를 들어 listen과 server_name은 아무리 http 블록에 선언해봤자 동작하지 않는다. 이 두 디렉티브는 오직 server { } 블록 안에서만 의미를 갖기 때문이다.

http {
    # ❌ 아래 두 디렉티브는 http 블록에서 선언해도 의미 없음
    # listen 80;       → server 블록에서만 유효
    # server_name _;   → server 블록에서만 유효

    server {
        listen 80;           # ✅ 여기서만 유효
        server_name example.com;  # ✅ 여기서만 유효
    }
}

 

상속되는 디렉티브

proxy_connect_timeout
gzip, gzip_types
client_max_body_size
error_page
access_log,error_log

이 디렉티브들은 http 블록에 한 번만 선언해두면 모든 server와 location에 적용되며, 필요한 경우 하위 블록에서 재정의(Override)할 수 있다.

http {
    # 공통 설정 — 모든 하위 블록에 상속됨
    proxy_connect_timeout 60s;
    gzip on;
    gzip_types text/plain text/css application/json;
    client_max_body_size 10m;
    error_page 404 /404.html;
    access_log /var/log/nginx/access.log;
    error_log  /var/log/nginx/error.log warn;

    server {
        listen 80;
        server_name api.example.com;

        # API 서버는 대용량 파일 업로드를 허용 → client_max_body_size만 재정의
        client_max_body_size 100m;

        location / {
            proxy_pass http://backend;
            # proxy_connect_timeout, gzip 등은 http 블록에서 상속
        }
    }

    server {
        listen 80;
        server_name www.example.com;

        # 별도 재정의 없음 → http 블록의 모든 설정 그대로 적용

        location /upload/ {
            client_max_body_size 50m;  # 이 location만 50m으로 재정의
        }
    }
}