Nginx 핵심 설정 가이드

Nginx (Engine X)는 가볍고 고성능을 자랑하는 HTTP 웹 서버이자 리버스 프록시 서버입니다. 또한, IMAP/POP3/SMTP 이메일 프록시 기능도 제공합니다. BSD-like 라이선스 아래 배포되며, 적은 메모리 사용량과 뛰어난 동시 처리 능력으로 잘 알려져 있습니다. 실제로 Nginx는 동종 웹 서버 중에서 최고의 동시 처리 성능을 보여줍니다.

주요 명령어

Nginx를 효과적으로 관리하고 문제를 해결하는 데 유용한 몇 가지 핵심 명령어가 있습니다.

  • -c </경로/설정파일>: Nginx에 기본 설정 파일 대신 사용할 특정 설정 파일의 경로를 지정합니다.
  • -t: Nginx를 실행하지 않고 설정 파일의 구문 오류 여부를 검사합니다. 또한, 설정 파일 내에서 참조하는 파일들을 열어보려 시도하여 잠재적인 문제를 파악할 수 있도록 돕습니다. 이 명령은 Nginx 설정 파일의 유효성을 신속하게 확인할 때 유용합니다.
  • -v: 현재 설치된 Nginx의 버전을 간략하게 표시합니다.
  • -V: Nginx의 버전 정보, 빌드 시 사용된 컴파일러 버전, 그리고 모든 설정 매개변수를 자세히 출력합니다.
  • nginx -s <신호>: Nginx 마스터 프로세스에 특정 신호를 보내 제어합니다.
    • stop: Nginx 프로세스를 즉시 강제 종료합니다.
    • quit: 현재 처리 중인 모든 요청을 완료한 후, Nginx 프로세스를 우아하게 종료합니다.
    • reload: 설정 파일의 변경 사항을 서비스 중단 없이 적용하기 위해 Nginx 설정을 다시 로드합니다.
    • reopen: Nginx의 로그 파일을 다시 열도록 지시하여 로그 로테이션 등의 작업에 활용됩니다.

Nginx 설정 파일의 기본 구조

Nginx의 설정 파일은 여러 계층적 블록으로 구성되어 있으며, 각 블록은 특정 기능이나 범주에 대한 설정을 담당합니다. 일반적인 구조는 다음과 같습니다.


main { # 전역 설정: Nginx 전체에 영향을 미치는 설정들
    # ...
}

events { # 이벤트 처리 설정: Nginx의 워커 프로세스 동작 방식 및 연결 관리
    # ...
}

http { # HTTP 서버 설정: HTTP 통신과 관련된 모든 설정 (가장 핵심적인 블록)
    # ...
    upstream my_application_servers { # 백엔드 서버 그룹 정의 (로드 밸런싱에 사용)
        # ...
    }
    server { # 가상 호스트 설정: 특정 도메인이나 포트에 대한 웹 서버 동작 정의
        # ...
        location / { # URL 경로 매칭 설정: 요청된 URI에 따라 다른 처리 규칙 적용
            # ...
        }
        location /api {
            # ...
        }
    }
    server {
        # 다른 가상 호스트 설정
        # ...
    }
    # ...
}

main 모듈: 전역 설정

main 블록은 Nginx 인스턴스 전체에 적용되는 가장 기본적인 설정을 포함합니다.


user nginx nginx; # Nginx 워커 프로세스가 실행될 사용자 및 그룹을 지정합니다. 보안상의 이유로 'root'가 아닌 전용 계정을 사용하는 것이 일반적입니다. 기본값은 운영체제에 따라 다를 수 있습니다.
worker_processes auto; # Nginx가 시작할 워커(자식) 프로세스의 수를 설정합니다. 'auto'로 설정하면 CPU 코어 수에 맞춰 자동으로 최적화됩니다. 일반적으로 CPU 코어 수와 동일하게 설정하는 것이 권장됩니다.
error_log /var/log/nginx/error_events.log notice; # Nginx 전반의 오류 로그 파일 경로와 기록 레벨을 정의합니다. 로그 레벨은 debug, info, notice, warn, error, crit 중에서 선택할 수 있으며, 'notice'는 중요한 이벤트와 경고를 기록합니다.
pid /run/nginx.pid; # Nginx 마스터 프로세스의 PID(프로세스 식별자)가 저장될 파일의 위치를 지정합니다.
worker_rlimit_nofile 4096; # 각 Nginx 워커 프로세스가 동시에 열 수 있는 파일 디스크립터의 최대 수를 설정합니다. 높은 동시 접속 처리를 위해 기본값(보통 1024)보다 높게 설정할 수 있습니다.
include /etc/nginx/sites-enabled/*.conf; # 지정된 경로의 모든 .conf 파일을 현재 설정에 포함합니다. 복잡한 설정을 여러 파일로 분리하여 관리할 때 유용합니다.

events 모듈: 연결 및 처리 방식 설정

events 블록은 Nginx의 네트워크 연결 처리 모델과 워커 프로세스당 최대 연결 수를 정의합니다.


events {
    use epoll; # Nginx가 클라이언트 연결을 처리할 I/O 다중화(multiplexing) 방식을 선택합니다. Linux 시스템에서는 'epoll'이 가장 효율적입니다. BSD 계열 시스템에서는 'kqueue'가, 그 외에는 'select'나 'poll'이 사용될 수 있습니다.
    worker_connections 2048; # 각 Nginx 워커 프로세스가 동시에 유지할 수 있는 최대 클라이언트 연결 수를 설정합니다. 이 값은 서버의 리소스(메모리, 파일 디스크립터)와 직결됩니다.
}

Nginx 서버가 처리할 수 있는 총 동시 클라이언트 연결 수는 worker_processes * worker_connections로 계산할 수 있습니다. Nginx가 리버스 프록시로 사용될 경우, 하나의 클라이언트 요청이 Nginx와 백엔드 서버 간의 연결을 포함하여 여러 연결을 생성할 수 있음에 유의해야 합니다.

http 모듈: HTTP 서버 핵심 설정

http 블록은 HTTP 통신과 관련된 전역적인 설정들을 포함하며, server와 upstream 같은 중요한 하위 블록들을 감싸는 역할을 합니다.


http {
    include mime.types; # 파일 확장자에 따라 MIME 타입을 정의하는 파일을 포함합니다. 이를 통해 Nginx가 다양한 파일 유형을 올바르게 식별하여 클라이언트에 전달할 수 있습니다.
    default_type application/octet-stream; # MIME 타입이 명시적으로 정의되지 않은 파일에 대한 기본 타입을 설정합니다. 이 경우, 브라우저는 해당 파일을 다운로드하려고 시도합니다.
    log_format request_details '$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/web_access.log request_details; # 모든 HTTP 요청에 대한 접근 로그 파일 경로와 위에서 정의한 로그 형식을 지정합니다.
    sendfile on; # 운영체제의 sendfile 기능을 활성화하여 파일 전송 성능을 최적화합니다. 이는 디스크에서 네트워크로 데이터를 직접 전송하여 CPU 오버헤드를 줄입니다.
    tcp_nopush on; # sendfile과 함께 사용하면, Nginx가 한 번에 여러 헤더를 보낸 후 파일 데이터를 전송함으로써 네트워크 효율을 높일 수 있습니다.
    tcp_nodelay on; # Nagle 알고리즘을 비활성화하여 작은 데이터 패킷이라도 지연 없이 즉시 전송하도록 합니다. 실시간 애플리케이션에 유용합니다.
    keepalive_timeout 75; # 클라이언트와의 keep-alive 연결을 유지할 최대 시간을 초 단위로 설정합니다. 이 시간 동안 유휴 상태인 연결은 닫힙니다.
    
    gzip on; # Gzip 압축을 활성화하여 응답 데이터의 크기를 줄이고 전송 속도를 향상시킵니다.
    gzip_disable "MSIE [1-6]\."; # 특정 버전의 Internet Explorer에서 Gzip 압축을 비활성화하여 호환성 문제를 방지합니다.
    gzip_http_version 1.0; # HTTP/1.0 이상의 프로토콜을 사용하는 요청에 대해 Gzip 압축을 적용합니다.
    gzip_types text/plain text/css application/json application/javascript application/x-javascript text/xml; # Gzip 압축을 적용할 MIME 타입을 지정합니다. 여러 타입을 공백으로 구분하여 나열할 수 있습니다.
    gzip_comp_level 5; # Gzip 압축 레벨을 설정합니다 (1-9). 숫자가 높을수록 압축률은 증가하지만 CPU 사용량도 함께 증가합니다. 보통 4~6 정도가 권장됩니다.

    upstream my_application_servers {
        # ... 백엔드 서버 정의
    }

    server {
        # ... 가상 호스트 정의
    }
}

server 모듈: 가상 호스트 설정

server 블록은 Nginx가 처리할 가상 호스트를 정의합니다. 특정 도메인 이름, 포트 또는 IP 주소로 들어오는 요청을 어떻게 처리할지 상세하게 설정합니다.


server {
    listen 80; # 이 가상 호스트가 수신할 TCP 포트 번호를 지정합니다.
    server_name example.com www.example.com; # 이 가상 호스트를 식별할 도메인 이름을 지정합니다. 여러 도메인을 공백으로 구분할 수 있습니다.
    root /var/www/myproject/html; # 이 가상 호스트의 문서 루트(웹 콘텐츠의 최상위 디렉토리)를 정의합니다.
    index index.html index.php; # 디렉토리 요청 시 Nginx가 찾아야 할 기본 파일의 순서를 지정합니다.
    charset utf-8; # 이 가상 호스트에서 제공되는 콘텐츠의 기본 문자 인코딩을 설정합니다.
    access_log /var/log/nginx/access_myapp.log request_details; # 이 가상 호스트에 대한 접근 로그 파일 경로와 사용할 로그 형식을 지정합니다.
    error_log /var/log/nginx/error_myapp.log error; # 이 가상 호스트에 대한 오류 로그 파일 경로와 레벨을 지정합니다.
    error_page 404 /custom/404.html; # 특정 HTTP 상태 코드(예: 404 Not Found, 500 Internal Server Error) 발생 시 보여줄 사용자 정의 오류 페이지를 지정합니다.
    # ...
}

location 모듈: 요청 URI 매칭 및 처리

location 블록은 server 블록 내에 위치하며, 들어오는 요청의 URI(Uniform Resource Identifier)를 기반으로 Nginx가 어떤 방식으로 응답할지를 결정합니다. 이 블록은 정규 표현식 매칭을 포함한 강력한 패턴 매칭 기능을 제공하여, 정적 파일 서빙, 동적 콘텐츠 처리, 리버스 프록시 등 다양한 시나리오에 활용됩니다.

location 지시어의 매칭 규칙과 우선순위는 다음과 같습니다:

  • = (정확 일치): 요청 URI가 패턴과 정확히 일치하는 경우에만 적용되며, 다른 모든 매칭보다 우선순위가 가장 높습니다. 일치하면 즉시 처리가 중단됩니다.
  • ^~ (접두사 일치): 요청 URI가 특정 문자열로 시작하는 경우에 적용됩니다. 정규 표현식 매칭보다 우선순위가 높으며, 일치하면 검색을 중단합니다.
  • ~ 또는 ~* (정규 표현식 일치): ~은 대소문자를 구분하는 정규 표현식 매칭이고, ~*은 대소문자를 구분하지 않습니다. 여러 정규 표현식이 일치하는 경우, 설정 파일에 먼저 정의된 블록이 우선순위를 가집니다.
  • /uri (일반 문자열 접두사 일치): 요청 URI가 특정 문자열로 시작하는 경우에 적용됩니다. 여러 블록이 일치할 경우, 가장 긴(가장 구체적인) 매칭 경로가 선택됩니다.
  • / (기본 매칭): 모든 요청에 대해 일치하는 가장 일반적인 location 블록입니다. 다른 location 블록에서 매칭되지 않은 모든 요청을 처리합니다. 가장 낮은 우선순위를 가집니다.
  • @named_location (내부 리다이렉션): 이 유형은 클라이언트 요청에 직접 매칭되지 않고, Nginx 내부적으로 error_page 또는 try_files 같은 지시어에 의해 호출되어 사용됩니다.

간단한 정적 파일 서빙 예시


location / {
    root   /srv/website/public; # 웹 콘텐츠가 있는 디렉토리 지정
    index  index.html index.htm default.html; # 기본 인덱스 파일 정의
}

PHP 애플리케이션을 위한 정규 표현식 매칭 예시


location ~ \.php$ {
    root           /srv/website/public;
    fastcgi_pass   unix:/var/run/php/php8.1-fpm.sock; # PHP-FPM 소켓으로 요청 전달
    fastcgi_index  index.php;
    fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name; # PHP 스크립트 파일 경로 설정
    include        fastcgi_params; # FastCGI 통신에 필요한 매개변수 포함
}

리버스 프록시 설정 예시


# /api 경로로 시작하는 모든 요청을 백엔드 API 서버로 전달
location /api {
    proxy_pass  http://192.168.1.10:8080; # 요청을 백엔드 서버로 프록시
    proxy_redirect off; # 백엔드 서버의 'Location' 헤더를 Nginx가 수정하지 않도록 합니다.
    # 클라이언트의 실제 정보(IP 주소, 호스트)를 백엔드 서버로 전달하기 위한 헤더 설정
    proxy_set_header Host $host; # 원본 Host 헤더 유지
    proxy_set_header X-Real-IP $remote_addr; # 클라이언트의 실제 IP 주소 전달
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 프록시를 거친 IP 주소 목록 전달
}

# 특정 접두사를 가진 요청을 다른 백엔드로 전달하며 URL 경로를 재작성
location ~ ^/old-service/(.*)$ {
    proxy_set_header Host legacy-backend.example.com; # 백엔드에 전달할 호스트 헤더 변경
    # '/old-service/' 부분을 제거한 나머지 경로($1)를 백엔드에 전달
    proxy_pass http://127.0.0.1:9000/new-path/$1;
}

# React Router, Vue Router와 같은 SPA(Single Page Application)의 히스토리 모드 지원
location / {
  alias     /var/www/spa-app/; # SPA의 빌드된 정적 파일이 위치한 실제 디렉토리
  try_files $uri $uri/ /index.html; # 요청된 파일이나 디렉토리가 없으면 index.html로 폴백
}

upstream 모듈: 로드 밸런싱 설정

upstream 모듈은 여러 개의 백엔드 서버 그룹을 정의하여, 클라이언트 요청을 이 서버들 간에 분산 처리하는 로드 밸런싱 기능을 제공합니다. 이를 통해 가용성과 성능을 향상시킬 수 있습니다.

Nginx에서 지원하는 주요 로드 밸런싱 알고리즘은 다음과 같습니다:

  • Round Robin (기본값): 요청을 백엔드 서버에 순차적으로 분배합니다. 서버가 응답하지 않으면 자동으로 요청 목록에서 제외됩니다.
  • weight (가중치 라운드 로빈): 각 서버에 가중치를 부여하여, 가중치가 높은 서버가 더 많은 요청을 받도록 합니다. 백엔드 서버들의 성능 차이가 있을 때 유용합니다.
  • ip_hash: 클라이언트의 IP 주소를 해싱하여, 동일한 IP 주소를 가진 클라이언트로부터의 요청은 항상 동일한 백엔드 서버로 전달됩니다. 이는 세션 고정성(sticky session)을 유지하는 데 도움이 됩니다.
  • least_conn (최소 연결): 현재 활성화된 연결 수가 가장 적은 백엔드 서버로 요청을 보냅니다. 이는 각 서버의 부하를 균등하게 분배하는 데 효과적입니다.
  • fair (타사 모듈 필요): 백엔드 서버의 응답 시간을 기반으로 가장 빠른 서버로 요청을 보냅니다.
  • url_hash (타사 모듈 필요): 요청 URL의 해시 값에 따라 요청을 특정 서버로 보냅니다. 특정 URL에 대한 캐시 히트율을 높이는 데 사용될 수 있습니다.

upstream 블록 내에서 server 지시어를 통해 각 백엔드 서버의 주소와 함께 다음과 같은 상태 매개변수를 지정할 수 있습니다.

  • down: 현재 서버를 로드 밸런싱 그룹에서 일시적으로 제외합니다. 유지 보수 시 사용됩니다.
  • backup: 다른 모든 비-백업 서버가 장애 상태이거나 과부하 상태일 때만 요청을 처리하는 예비 서버로 지정합니다.
  • max_fails: 지정된 fail_timeout 기간 내에 서버에 대한 요청이 실패할 수 있는 최대 횟수입니다. 이 횟수를 초과하면 서버는 fail_timeout 기간 동안 비활성화됩니다. 기본값은 1입니다.
  • fail_timeout: max_fails 횟수만큼 실패한 후, 서버를 비활성화 상태로 유지할 시간(초)입니다. 이 시간 동안 Nginx는 해당 서버로 요청을 보내지 않습니다. 기본값은 10초입니다.

참고: ip_hash 로드 밸런싱 알고리즘을 사용할 경우, weight나 backup 상태 매개변수를 함께 사용할 수 없습니다.

upstream 설정 예시


upstream my_web_cluster {
    # 이 서버는 다른 서버보다 3배 더 많은 요청을 받습니다.
    server 192.168.1.101:80 weight=3;
    # 이 서버는 현재 로드 밸런싱에서 제외됩니다.
    server 192.168.1.102:80 down;
    # 이 서버는 30초 안에 5번 실패하면 30초 동안 비활성화됩니다.
    server 192.168.1.103:8080 max_fails=5 fail_timeout=30s;
    # 이 서버는 기본 설정으로 로드 밸런싱에 참여합니다.
    server 192.168.1.104:8080;
}

server {
  listen 80;
  server_name yourdomain.com;

  location / {
    # 'my_web_cluster'라는 upstream 그룹으로 들어오는 요청을 프록시합니다.
    proxy_pass  http://my_web_cluster/;
    # 클라이언트 정보 전달을 위한 헤더 설정
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

태그: nginx 웹서버 리버스프록시 로드밸런싱 Nginx설정

7월 31일 11:55에 게시됨

인기 태그

©2026 괴물 클럽