nginx.conf 구조 완전 분석

nginx.conf는 Nginx의 모든 동작을 제어하는 핵심 파일입니다. 이 파일의 구조를 이해하지 못하면 설정을 수정할 때마다 시행착오를 겪게 됩니다. 블록 계층 구조와 지시어 상속 원리를 완전히 익혀봅시다.

---

nginx.conf 전체 구조

Nginx 설정 파일은 컨텍스트(Context) 와 지시어(Directive) 로 구성됩니다.

# ============================================================
# Main 컨텍스트 (전역 설정)
# ============================================================
user  nginx;                        # 워커 프로세스 실행 사용자
worker_processes  auto;             # 워커 수 (auto = CPU 코어 수)
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

# ============================================================
# Events 컨텍스트 (네트워크 이벤트 처리)
# ============================================================
events {
    worker_connections  1024;       # 워커 1개당 최대 동시 연결 수
    use epoll;                      # 이벤트 처리 방식 (Linux: epoll)
    multi_accept on;                # 한 번에 여러 연결 수락
}

# ============================================================
# HTTP 컨텍스트 (HTTP 전체 설정)
# ============================================================
http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # 로그 포맷 정의
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;
    sendfile        on;
    keepalive_timeout  65;

    # 추가 설정 파일 포함
    include /etc/nginx/conf.d/*.conf;

    # --------------------------------------------------------
    # Server 컨텍스트 (가상 호스트)
    # --------------------------------------------------------
    server {
        listen       80;
        server_name  example.com;
        root         /var/www/html;

        # ----------------------------------------------------
        # Location 컨텍스트 (URL 경로별 처리)
        # ----------------------------------------------------
        location / {
            index  index.html index.htm;
        }

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

---

Main 컨텍스트 (전역 설정)

HTTP 블록 밖의 최상위 설정으로, Nginx 프로세스 자체를 제어합니다.

# 워커 프로세스를 실행할 OS 사용자
# 보안상 root가 아닌 전용 사용자 사용 권장
user  nginx;

# 워커 프로세스 수
# auto: CPU 코어 수만큼 자동 설정 (권장)
# 숫자 직접 지정도 가능: worker_processes 4;
worker_processes  auto;

# 워커 프로세스에 CPU 코어 바인딩 (선택)
# worker_cpu_affinity auto;

# 에러 로그 위치와 레벨
# 레벨: debug | info | notice | warn | error | crit | alert | emerg
error_log  /var/log/nginx/error.log  warn;

# PID 파일 위치 (nginx -s reload 등에서 사용)
pid  /var/run/nginx.pid;

# 워커 프로세스당 열 수 있는 최대 파일 디스크립터 수
# ulimit -n 값과 일치시키거나 크게 설정
worker_rlimit_nofile  65535;

---

Events 컨텍스트

네트워크 이벤트 처리 방식과 연결 수를 설정합니다.

events {
    # 워커 1개가 동시에 처리할 수 있는 최대 연결 수
    # 총 최대 연결 = worker_processes × worker_connections
    # 예: 4 × 1024 = 4096개 동시 연결
    worker_connections  1024;

    # 이벤트 처리 모델
    # Linux: epoll (권장), FreeBSD: kqueue, Windows: select
    use  epoll;

    # 워커가 새 연결을 한 번에 여러 개 수락할지 여부
    # on으로 설정하면 accept() 시스템콜을 효율적으로 사용
    multi_accept  on;
}

---

HTTP 컨텍스트

HTTP 프로토콜 관련 전역 설정을 담습니다. 여기서 설정한 값들은 하위 Server·Location 블록에 상속 됩니다.

http {
    # MIME 타입 정의 파일 포함 (확장자 → Content-Type 매핑)
    include       /etc/nginx/mime.types;

    # mime.types에 없는 파일의 기본 Content-Type
    default_type  application/octet-stream;

    # 파일을 커널에서 직접 소켓으로 전송 (시스템콜 최소화)
    # 정적 파일 서빙 성능 향상에 필수
    sendfile  on;

    # sendfile과 함께 사용 — TCP 패킷을 가능한 크게 묶어 전송
    tcp_nopush  on;

    # 소량의 데이터도 지연 없이 즉시 전송 (tcp_nopush와 함께 사용)
    tcp_nodelay  on;

    # Keep-Alive 연결 유지 시간 (초)
    # 클라이언트가 같은 연결로 여러 요청을 보낼 수 있는 시간
    keepalive_timeout  65;

    # Keep-Alive 연결당 최대 요청 수
    keepalive_requests  1000;

    # 응답 헤더에 Nginx 버전 숨기기 (보안)
    server_tokens  off;

    # Gzip 압축 설정
    gzip  on;
    gzip_types  text/plain text/css application/json application/javascript text/xml;
    gzip_min_length  1024;  # 1KB 미만은 압축 안 함

    # 추가 설정 파일 포함 (conf.d/*.conf)
    include  /etc/nginx/conf.d/*.conf;
}

---

Server 컨텍스트 (가상 호스트)

하나의 Nginx가 여러 도메인·포트를 처리할 수 있도록 가상 호스트 를 정의합니다. HTTP 컨텍스트 안에 여러 개의 Server 블록을 정의할 수 있습니다.

server {
    # 리슨 포트 및 옵션
    listen  80;                  # IPv4, 포트 80
    listen  [::]:80;             # IPv6, 포트 80
    # listen  443 ssl;           # HTTPS

    # 이 서버 블록이 처리할 도메인 이름
    # 공백으로 여러 도메인 지정 가능
    server_name  example.com www.example.com;

    # 이 서버의 웹 루트 디렉터리
    root  /var/www/example.com;

    # 기본 인덱스 파일
    index  index.html index.htm;

    # 서버 레벨 접근 로그 (HTTP 레벨 설정과 별도 지정 가능)
    access_log  /var/log/nginx/example.access.log  main;
    error_log   /var/log/nginx/example.error.log   warn;
}

요청이 Server 블록에 매핑되는 순서

Nginx는 요청의 Host 헤더를 기준으로 어떤 Server 블록이 처리할지 결정합니다.

1. listen 포트 일치 확인
2. server_name 완전 일치 확인 (예: example.com)
3. server_name 와일드카드 앞부분 일치 (예: *.example.com)
4. server_name 와일드카드 뒷부분 일치 (예: example.*)
5. server_name 정규식 일치 (예: ~^www\d+\.example\.com$)
6. 일치하는 server_name이 없으면 default_server로 지정된 블록 사용

# 기본 서버 블록 — 매칭되는 server_name이 없을 때 사용
server {
    listen 80 default_server;
    server_name _;           # "_"는 어떤 도메인도 매칭하지 않는 특수값
    return 444;              # 연결 즉시 닫기 (알 수 없는 도메인 차단)
}

---

Location 컨텍스트

URL 경로별로 다른 처리를 적용합니다. Server 블록 안에 여러 Location을 정의할 수 있습니다.

Location 매칭 유형

server {
    # 1. 완전 일치 (=)
    # 정확히 "/favicon.ico"인 경우만 매칭
    location = /favicon.ico {
        log_not_found off;
        access_log off;
    }

    # 2. 우선 접두사 일치 (^~)
    # "/images/"로 시작하면 이 블록 사용, 정규식 검사 생략
    location ^~ /images/ {
        root /var/www/static;
        expires 30d;
    }

    # 3. 정규식 일치 — 대소문자 구분 (~)
    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
    }

    # 4. 정규식 일치 — 대소문자 무시 (~*)
    location ~* \.(jpg|jpeg|png|gif|webp)$ {
        expires 7d;
        add_header Cache-Control "public";
    }

    # 5. 일반 접두사 일치 (수정자 없음)
    # "/api/"로 시작하는 모든 경로
    location /api/ {
        proxy_pass http://backend;
    }

    # 6. 가장 기본 — 위 어디에도 매칭 안 되면 여기
    location / {
        try_files $uri $uri/ =404;
    }
}

Location 매칭 우선순위

1. 완전 일치 (=)           ← 가장 높은 우선순위
2. 우선 접두사 (^~)
3. 정규식 (~, ~*)           ← 설정 파일에 나타나는 순서대로
4. 일반 접두사 (수정자 없음) ← 가장 긴 것이 선택됨

---

지시어 상속 규칙

Nginx의 지시어는 상위 컨텍스트에서 하위 컨텍스트로 상속 됩니다.

Main
 └── Events
 └── HTTP                ← http 레벨 설정이 여기서 상속 시작
      └── Server         ← http 설정 상속, server에서 재정의 가능
           └── Location  ← server 설정 상속, location에서 재정의 가능

http {
    gzip on;          # HTTP 레벨에서 gzip 활성화
    keepalive_timeout 65;

    server {
        # gzip on 상속됨
        keepalive_timeout 30;  # server 레벨에서 재정의

        location /api/ {
            # gzip on 상속됨
            # keepalive_timeout 30 상속됨
            proxy_pass http://backend;
        }
    }
}

주의: 일부 지시어(예: add_header)는 상속 규칙이 다릅니다. 하위 블록에서 add_header를 한 번이라도 쓰면, 상위에서 설정한 add_header가 ** 모두 무시**됩니다. 헤더 설정은 가능한 한 한 곳에서 일괄 관리하는 것이 좋습니다.

---

설정 파일 분리 전략 (conf.d 패턴)

운영 환경에서는 nginx.conf 하나에 모든 설정을 넣지 않고, 도메인·역할별로 파일을 분리합니다.

/etc/nginx/
  nginx.conf              ← 전역 설정만 (include conf.d/*.conf 포함)
  conf.d/
    example.com.conf      ← example.com 가상 호스트
    api.example.com.conf  ← API 서브도메인
    upstream.conf         ← upstream 블록 정의
    ssl-params.conf       ← SSL 공통 파라미터

nginx.conf에서 include 지시어로 로딩:

http {
    # ...
    include /etc/nginx/conf.d/*.conf;
}

# 새 사이트 설정 추가 후 검증 및 리로드
sudo nginx -t && sudo systemctl reload nginx

---

정리

컨텍스트	역할	주요 지시어
Main	프로세스 전역 설정	user, worker_processes, error_log
Events	이벤트 처리 방식	worker_connections, use epoll
HTTP	HTTP 전역 설정	sendfile, gzip, keepalive_timeout
Server	가상 호스트 정의	listen, server_name, root
Location	URL 경로별 처리	proxy_pass, try_files, expires