설정 파일

Nginx 설정 파일

개요

Nginx의 모든 동작은 /etc/nginx/nginx.conf 설정 파일에 의해 결정된다. 지시어(Directive)와 블록(Block)으로 구성된 계층적 구조를 가진다.

Nginx의 핵심은 결국 설정 파일이에요. Nginx 자체는 그냥 엔진이고, 어떻게 동작할지는 전부 설정 파일에서 정하거든요. 비유하자면, Nginx는 빈 스마트폰이고, 설정 파일은 앱을 설치하고 환경을 세팅하는 거예요.

설정 파일을 잘 다루면 정적 파일 서빙, 리버스 프록시, 로드 밸런싱, SSL 등 뭐든 할 수 있어요!

설정 파일 전체 구조

graph TD
    A["nginx.conf<br/>메인 설정 파일"] --> B["전역 블록 (main)<br/>워커 프로세스, 로그 등"]
    A --> C["events 블록<br/>연결 처리 방식"]
    A --> D["http 블록<br/>웹 서버 설정"]

    D --> E["server 블록<br/>가상 호스트 (사이트별)"]
    D --> F["upstream 블록<br/>백엔드 서버 그룹"]

    E --> G["location 블록<br/>URL 경로별 처리"]

    style A fill:#FFD700
    style D fill:#87CEEB
    style E fill:#90EE90
    style G fill:#FFB3B3
Mermaid
복사

graph LR
    subgraph "계층 구조"
        M[main] --> EV[events]
        M --> H[http]
        H --> S1[server 1]
        H --> S2[server 2]
        S1 --> L1[location /]
        S1 --> L2[location /api/]
        S2 --> L3[location /]
    end
Mermaid
복사

nginx.conf 전체 예시 (주석 해설)

# ============================================
# 전역 블록 (main context)
# ============================================
user www-data;                     # Nginx 워커 프로세스 실행 사용자
worker_processes auto;             # 워커 프로세스 수 (auto = CPU 코어 수)
pid /run/nginx.pid;                # PID 파일 위치
error_log /var/log/nginx/error.log warn;  # 에러 로그 경로 및 레벨

# ============================================
# events 블록
# ============================================
events {
    worker_connections 1024;       # 워커당 최대 동시 연결 수
    multi_accept on;               # 한 번에 여러 연결 수락
}

# ============================================
# http 블록
# ============================================
http {
    # MIME 타입 설정
    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"';

    access_log /var/log/nginx/access.log main;

    # 성능 최적화
    sendfile on;                   # 커널에서 직접 파일 전송
    tcp_nopush on;                 # 패킷 최적화
    keepalive_timeout 65;          # 연결 유지 시간 (초)
    gzip on;                       # gzip 압축 활성화

    # 사이트별 설정 파일 포함
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}
Plain Text
복사

각 블록 상세 설명

1. 전역 블록 (main)

지시어	값	설명
user	www-data	워커 프로세스 실행 사용자
worker_processes	auto	워커 프로세스 수 (auto = CPU 코어 수만큼)
pid	/run/nginx.pid	마스터 프로세스 PID 파일 위치
error_log	경로 레벨	에러 로그 파일과 로그 레벨

전역 블록은 Nginx 전체에 영향을 주는 설정이에요. 어떤 블록에도 속하지 않는 최상위 레벨의 설정들이 여기에 와요.

2. events 블록

지시어	값	설명
worker_connections	1024	워커 하나가 동시에 처리할 수 있는 연결 수
multi_accept	on	한 번에 여러 연결을 동시에 수락
use	epoll	이벤트 처리 방식 (리눅스: epoll)

최대 동시 연결 수 = worker_processes × worker_connections 예: 4 × 1024 = 4,096개 동시 연결 처리 가능!

3. http 블록

http 블록은 웹 서버 관련 모든 설정을 감싸는 큰 블록이에요. 여기 안에 server 블록, upstream 블록 등이 들어가요.

4. server 블록 (가상 호스트)

server {
    listen 80;                      # 수신 포트
    server_name example.com www.example.com;  # 도메인

    root /var/www/html;             # 웹 루트 디렉토리
    index index.html;               # 기본 문서

    location / {
        try_files $uri $uri/ =404;
    }
}
Plain Text
복사

지시어	설명	예시
listen	수신할 포트	80, 443 ssl
server_name	매칭할 도메인 이름	example.com *.example.com
root	웹 파일이 있는 디렉토리	/var/www/html
index	기본 문서 파일명	index.html index.htm

server 블록 하나가 하나의 웹사이트를 담당해요. 도메인별로 다른 server 블록을 만들면, 한 대의 서버에서 여러 웹사이트를 운영할 수 있어요!

5. location 블록 (URL 경로별 처리)

graph TD
    A["클라이언트 요청<br/>URL 경로"] --> B{location 매칭}
    B -->|"/"| C["location / <br/>기본 매칭"]
    B -->|"/api/"| D["location /api/<br/>프록시 전달"]
    B -->|"/images/"| E["location /images/<br/>정적 파일 + 캐싱"]
    B -->|".php$"| F["location ~ \\\\.php$<br/>정규식 매칭"]

    style C fill:#90EE90
    style D fill:#87CEEB
    style E fill:#FFD700
    style F fill:#DDA0DD
Mermaid
복사

location 매칭 우선순위

순위	기호	의미	예시
1	=	정확히 일치	location = /favicon.ico
2	^~	접두사 일치 (정규식 무시)	location ^~ /images/
3	~	정규식 일치 (대소문자 구분)	location ~ \\.php$
4	~*	정규식 일치 (대소문자 무시)	location ~* \\.(jpg\\|png)$
5	(없음)	접두사 일치 (일반)	location /api/
6	/	기본 매칭 (모든 요청)	location /

우선순위가 높은 것부터 매칭돼요. 예를 들어 /favicon.ico 요청이 오면, location = /favicon.ico(정확 매칭)가 location /(기본 매칭)보다 먼저 선택돼요.

자주 쓰는 설정 패턴

정적 파일 서빙

location / {
    root /var/www/html;
    index index.html;
    try_files $uri $uri/ /index.html;  # SPA(React) 대응
}
Plain Text
복사

리버스 프록시

location /api/ {
    proxy_pass <http://localhost:8080>;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
Plain Text
복사

정적 파일 캐싱

location ~* \\.(css|js|png|jpg|gif|ico|woff2)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}
Plain Text
복사

HTTP → HTTPS 리다이렉트

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}
Plain Text
복사

설정 파일 관리 방식

flowchart TD
    A["nginx.conf<br/>(메인 — 건드리지 않음)"] -->|include| B["sites-enabled/*<br/>(활성화된 사이트)"]
    A -->|include| C["conf.d/*.conf<br/>(추가 설정)"]

    D["sites-available/<br/>(모든 사이트 설정 보관)"] -->|"심볼릭 링크"| B

    style A fill:#FFD700
    style B fill:#90EE90
Mermaid
복사

권장 방식: nginx.conf는 가급적 수정하지 말고, 사이트별 설정은 sites-available/에 파일을 만든 뒤 sites-enabled/에 링크!

# 새 사이트 설정 만들기
sudo nano /etc/nginx/sites-available/mysite.conf

# 활성화 (심볼릭 링크)
sudo ln -s /etc/nginx/sites-available/mysite.conf /etc/nginx/sites-enabled/

# 기본 사이트 비활성화 (필요시)
sudo rm /etc/nginx/sites-enabled/default

# 테스트 후 적용
sudo nginx -t && sudo systemctl reload nginx
Bash
복사

주요 변수 (Variables)

Nginx가 요청 처리 과정에서 자동으로 채워서 제공하는 내장(미리 정의된) 변수라서 별도로 선언하지 않고 바로 사용할 수 있어요.

변수	설명	예시 값
$host	요청된 호스트명	example.com
$uri	현재 요청 URI	/api/users
$request_uri	쿼리스트링 포함 URI	/api/users?page=1
$remote_addr	클라이언트 IP	192.168.1.100
$scheme	프로토콜	http 또는 https
$server_name	server_name 값	example.com
$request_method	HTTP 메서드	GET, POST
$status	응답 상태 코드	200, 404

핵심 정리

Nginx 설정 = 지시어(Directive)와 블록(Block)의 계층 구조

핵심 블록: main → events → http → server → location

server 블록 = 가상 호스트 (도메인별 사이트 설정)

location 블록 = URL 경로별 처리 규칙

설정 관리:

sites-available/에 보관 → sites-enabled/에 링크 → nginx -t → reload