🌐 Nginx 완전 가이드

server {
    listen 80;
    server_name example.com;

    location / {
        root /var/www/myapp;
        try_files $uri $uri/ /index.html;  # SPA 라우팅
    }
}

user  nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;   # 확장자 → Content-Type 매핑표
    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;
    keepalive_timeout 65;
    gzip          on;

    # 도메인별 설정은 별도 파일로 분리해 관리한다
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

proxy_http_version 1.1;
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;
proxy_set_header X-Request-Id      $request_id;

server {
    listen 443 ssl;
    http2 on;
    server_name api.example.com;

    include snippets/ssl-params.conf;
    include snippets/security-headers.conf;

    location / {
        include snippets/proxy-headers.conf;
        proxy_pass http://api_backend;
    }
}

user  nginx;
worker_processes auto;            # CPU 코어 수만큼 워커 생성
worker_rlimit_nofile 65535;       # 워커당 열 수 있는 파일(소켓 포함) 한도
pid /run/nginx.pid;

error_log /var/log/nginx/error.log warn;

# 동적 모듈은 main 컨텍스트에서 로드
# load_module modules/ngx_http_geoip2_module.so;

events {
    worker_connections 8192;      # 워커 하나당 최대 동시 연결
    multi_accept on;              # 한 번에 대기 중인 연결을 모두 accept
    # use epoll;                  # Linux는 자동 선택되므로 보통 생략
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    charset       utf-8;

    server_tokens off;                 # 에러 페이지·Server 헤더에서 버전 숨김

    # ── 전송 최적화 ─────────────────────────────
    sendfile    on;                    # 커널에서 파일을 바로 소켓으로 복사
    tcp_nopush  on;                    # sendfile과 함께: 헤더+데이터를 한 패킷에
    tcp_nodelay on;                    # keepalive 연결에서 작은 패킷 지연 제거

    # ── 타임아웃 & 요청 크기 ─────────────────────
    keepalive_timeout     65s;
    client_header_timeout 15s;
    client_body_timeout   30s;
    send_timeout          30s;
    client_max_body_size  20m;         # 기본 1m → 초과 시 413 Request Entity Too Large

    # ── JSON 액세스 로그 ────────────────────────
    log_format json escape=json '{'
        '"time":"$time_iso8601",'
        '"request_id":"$request_id",'
        '"remote_addr":"$remote_addr",'
        '"host":"$host",'
        '"method":"$request_method",'
        '"uri":"$request_uri",'
        '"status":$status,'
        '"bytes":$body_bytes_sent,'
        '"request_time":$request_time,'
        '"upstream_addr":"$upstream_addr",'
        '"upstream_status":"$upstream_status",'
        '"upstream_response_time":"$upstream_response_time",'
        '"user_agent":"$http_user_agent"'
    '}';
    access_log /var/log/nginx/access.log json buffer=32k flush=5s;

    # ── 압축 ────────────────────────────────────
    gzip on;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_proxied any;                  # 프록시 응답도 압축
    gzip_vary on;                      # Vary: Accept-Encoding (CDN 캐시 분리)
    gzip_types text/plain text/css application/javascript application/json
               application/xml image/svg+xml;

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

# 등록되지 않은 Host(IP 직접 접속, 스캐너)는 응답 없이 연결을 끊는다
server {
    listen 80  default_server;
    listen 443 ssl default_server;
    server_name _;

    ssl_reject_handshake on;   # 1.19.4+: 인증서 없이 TLS 핸드셰이크 자체를 거부
    return 444;                # nginx 전용 코드: 응답 없이 연결 종료
}

# http → https, www → apex 로 한 번에 정규화
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://example.com$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name www.example.com;
    include snippets/ssl-params.conf;
    return 301 https://example.com$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name example.com;
    include snippets/ssl-params.conf;
    root /var/www/example;
}

server_name example.com;                 # ① 정확한 이름
server_name *.example.com;               # ② 앞쪽 와일드카드 (a.example.com, a.b.example.com)
server_name mail.*;                      # ③ 뒤쪽 와일드카드
server_name ~^(?<tenant>[a-z0-9-]+)\.saas\.com$;   # ④ 정규식 + 이름 있는 캡처

# 정규식 캡처는 이후 지시어에서 변수로 사용 가능
# root /var/www/tenants/$tenant;

server {
    listen 8080;

    location = /           { return 200 "1. exact /\n"; }
    location ^~ /static/   { return 200 "2. ^~ /static/\n"; }
    location ~* \.(png|jpg|css|js)$ { return 200 "3. regex asset\n"; }
    location /api/         { return 200 "4. prefix /api/\n"; }
    location /             { return 200 "5. prefix / (fallback)\n"; }
}

# curl localhost:8080/                → 1. exact /
# curl localhost:8080/static/app.js   → 2. ^~ /static/    (정규식보다 우선)
# curl localhost:8080/img/logo.png    → 3. regex asset
# curl localhost:8080/api/logo.png    → 3. regex asset    (/api/ 접두보다 정규식이 우선!)
# curl localhost:8080/api/users       → 4. prefix /api/
# curl localhost:8080/about           → 5. prefix / (fallback)

# SPA: 파일 → 디렉터리 → index.html 순으로 탐색
location / {
    try_files $uri $uri/ /index.html;
}

# 정적 파일이 없으면 백엔드로 넘기기 (Rails/Django/Next.js 등)
location / {
    try_files $uri @app;
}
location @app {
    include snippets/proxy-headers.conf;
    proxy_pass http://app_backend;
}

# ❌ location에는 슬래시가 없고 alias에는 있음
location /static {
    alias /var/www/static/;
}
# GET /static../app/.env  →  /var/www/static/../app/.env  (상위 디렉터리 노출!)

# ✅ location과 alias의 끝 슬래시를 반드시 맞춘다
location /static/ {
    alias /var/www/static/;
}

# 정규식 location에서 alias를 쓰려면 캡처로 경로를 직접 조립해야 한다
location ~ ^/download/(.+\.pdf)$ {
    alias /data/files/$1;
}

# 정규식 location 안의 proxy_pass에는 URI를 붙일 수 없다 (nginx -t 에러)
# 경로를 바꾸려면 rewrite ... break 로 URI를 먼저 수정한다
location ~ ^/api/v1/(.*)$ {
    rewrite ^/api/v1/(.*)$ /$1 break;
    proxy_pass http://api_backend;
}

server {
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;

    location /assets/ {
        add_header Cache-Control "public, max-age=31536000, immutable";
        # ↑ 이 location의 응답에는 X-Frame-Options, X-Content-Type-Options가 없다!
    }
}

# snippets/security-headers.conf
add_header X-Frame-Options "DENY" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

# conf.d/example.com.conf
server {
    include snippets/security-headers.conf;

    location /assets/ {
        include snippets/security-headers.conf;   # 다시 포함
        add_header Cache-Control "public, max-age=31536000, immutable";
    }
}

# WebSocket 업그레이드 헤더
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

# 점검 모드: 사내 IP는 통과, 나머지는 503
geo $maintenance_bypass {
    default      0;
    10.0.0.0/8   1;
    192.168.0.0/16 1;
}

map $maintenance_bypass $maintenance_block {
    1       0;
    default 1;
}

# 봇 User-Agent는 액세스 로그에서 제외
map $http_user_agent $loggable {
    ~*(bot|crawler|spider|healthcheck)  0;
    default                             1;
}

# 요청 경로에 따라 캐시 정책 결정
map $uri $cache_control {
    ~*\.(js|css|woff2)$   "public, max-age=31536000, immutable";
    ~*\.html$             "no-cache";
    default               "no-store";
}

server {
    access_log /var/log/nginx/access.log json if=$loggable;

    location / {
        # 점검 중에만 아래 한 줄의 주석을 풀고 reload — 사내 IP는 통과
        # if ($maintenance_block) { return 503; }

        add_header Cache-Control $cache_control always;
        try_files $uri $uri/ /index.html;
    }
}

upstream backend {
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
    server 127.0.0.1:3002;
    # ip_hash;   # 같은 클라이언트를 같은 서버로 고정하고 싶을 때
}

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

    location / {
        proxy_pass http://backend;
        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;
    }
}

upstream api_backend {
    least_conn;                                 # 활성 연결이 가장 적은 서버로
    server 10.0.1.11:8080 max_fails=3 fail_timeout=30s;
    server 10.0.1.12:8080 max_fails=3 fail_timeout=30s;
    server 10.0.1.13:8080 backup;               # 나머지가 모두 죽었을 때만 사용

    keepalive 64;                               # 워커당 유지할 유휴 연결 수
    keepalive_timeout 60s;
}

location /api/ {
    proxy_pass http://api_backend;

    proxy_http_version 1.1;
    proxy_set_header Connection "";             # keepalive 재사용에 필수
    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;

    proxy_connect_timeout 3s;                   # 연결 수립 제한 — 짧게
    proxy_send_timeout    30s;
    proxy_read_timeout    30s;                  # 응답 대기 (기본 60s) → 초과 시 504

    # 연결 실패·타임아웃·502/503일 때 다음 서버로 재시도 (GET 등 멱등 요청만)
    proxy_next_upstream error timeout http_502 http_503;
    proxy_next_upstream_tries 2;
}

# WebSocket / SSE
location /ws/ {
    proxy_pass http://api_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;   # 10-maps.conf의 map
    proxy_set_header Host       $host;
    proxy_read_timeout 1h;                      # 유휴 연결이 끊기지 않게
}

location /events/ {                            # Server-Sent Events
    proxy_pass http://api_backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;                        # 이벤트를 즉시 흘려보냄
    proxy_cache off;
    proxy_read_timeout 1h;
}

# ngx_http_realip_module: 신뢰하는 프록시가 보낸 헤더에서만 IP를 꺼낸다
set_real_ip_from 10.0.0.0/8;          # 사내 LB 대역
set_real_ip_from 173.245.48.0/20;     # (예) CDN 대역 — 공식 목록으로 관리
real_ip_header    X-Forwarded-For;
real_ip_recursive on;
# 이후 $remote_addr가 실제 클라이언트 IP가 되어 로그·limit_req·allow/deny에 반영된다

location /static/ {
    alias /var/www/myapp/static/;
    expires 30d;
    add_header Cache-Control "public, immutable";
}

gzip on;
gzip_types text/css application/javascript application/json;
gzip_min_length 1024;

location = /index.test {
    default_type text/html;      # 이 location의 응답은 항상 text/html로 고정
    try_files /index.html =404;  # 실제 html 파일을 내부 서빙 (URL은 /index.test 그대로 유지, 클라이언트에게 리다이렉트 노출 안 됨)
}

location ~ \.test$ {
    rewrite ^(.*)\.test$ $1.html last;
    # last는 URI를 .html로 바꿔 location 매칭을 처음부터 다시 태운다 —
    # 이후 일반 location(/)에서 .html로 정상 서빙되므로 mime.types가 text/html을 올바르게 잡아준다.
}

location = /index.test {
    proxy_pass http://backend;
    proxy_hide_header Content-Type;      # 백엔드가 보낸 잘못된/누락된 Content-Type 제거
    add_header Content-Type "text/html; charset=utf-8" always;
}

ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

ssl_protocols TLSv1.2 TLSv1.3;              # TLS 1.0/1.1 비활성
ssl_prefer_server_ciphers off;              # TLS 1.3 시대에는 클라이언트 선택 존중
ssl_session_cache   shared:SSL:10m;         # 약 4만 세션 — 재접속 시 핸드셰이크 생략
ssl_session_timeout 1d;
ssl_session_tickets off;

# 80번 포트 — 필요하면 여기서도 동일한 location을 두고 그대로 서비스 가능
server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/myapp;

    location = /index.test {
        default_type text/html;
        try_files /index.html =404;
    }
    location / {
        try_files $uri $uri/ =404;
    }
}

# 443번 포트 — TLS가 붙어도 위와 동일한 location을 그대로 사용
server {
    listen 443 ssl;
    http2 on;
    server_name example.com www.example.com;
    root /var/www/myapp;

    include snippets/ssl-params.conf;
    include snippets/hsts.conf;

    location = /index.test {
        default_type text/html;
        try_files /index.html =404;
    }
    location / {
        try_files $uri $uri/ =404;
    }
}

# 키: 클라이언트 IP(바이너리 형태가 메모리 효율적), 10MB ≈ 16만 IP
limit_req_zone  $binary_remote_addr zone=api_rl:10m   rate=10r/s;
limit_req_zone  $binary_remote_addr zone=login_rl:10m rate=5r/m;
limit_conn_zone $binary_remote_addr zone=conn_per_ip:10m;

limit_req_status  429;     # 기본 503 대신 의미가 맞는 429
limit_conn_status 429;

server {
    include snippets/security-headers.conf;

    # 숨김 파일(.env, .git ...) 차단 — 단, ACME 인증용 .well-known은 허용
    location ~ /\.(?!well-known/) {
        deny all;
        access_log off;
        log_not_found off;
    }

    location /api/ {
        limit_req  zone=api_rl burst=20 nodelay;   # 순간 20건까지 허용, 초과분은 429
        limit_conn conn_per_ip 20;
        include snippets/proxy-headers.conf;
        proxy_pass http://api_backend;
    }

    location = /api/auth/login {
        limit_req zone=login_rl burst=5;           # 무차별 대입 방어
        include snippets/proxy-headers.conf;
        proxy_pass http://api_backend;
    }

    location /admin/ {
        allow 10.0.0.0/8;                          # 위에서부터 첫 매칭 규칙 적용
        allow 203.0.113.10;
        deny  all;
        include snippets/proxy-headers.conf;
        proxy_pass http://admin_backend;
    }
}

add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
# CSP는 서비스마다 다르므로 Report-Only로 먼저 관찰한 뒤 적용
# add_header Content-Security-Policy-Report-Only "default-src 'self'" always;

proxy_cache_path /var/cache/nginx/api
                 levels=1:2
                 keys_zone=api_cache:50m      # 키 메타데이터 (1MB ≈ 8천 키)
                 max_size=2g
                 inactive=30m                 # 30분간 요청 없으면 삭제
                 use_temp_path=off;

location /api/catalog/ {
    proxy_cache api_cache;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    proxy_cache_valid 200 301 5m;
    proxy_cache_valid 404      1m;

    # 백엔드 장애·갱신 중에는 오래된 캐시라도 응답
    proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
    proxy_cache_background_update on;
    proxy_cache_lock on;                 # 같은 키에 대한 동시 miss를 1건만 백엔드로

    # 개인화된 요청은 캐시 우회 + 저장 금지
    proxy_cache_bypass $http_authorization $cookie_session;
    proxy_no_cache     $http_authorization $cookie_session;

    add_header X-Cache-Status $upstream_cache_status always;   # HIT / MISS / STALE ...
    include snippets/proxy-headers.conf;
    proxy_pass http://api_backend;
}

open_file_cache          max=10000 inactive=30s;
open_file_cache_valid    60s;
open_file_cache_min_uses 2;
open_file_cache_errors   on;

proxy_buffer_size        16k;      # 응답 헤더용 (큰 쿠키/JWT 대비)
proxy_buffers            8 16k;
proxy_busy_buffers_size  32k;

reset_timedout_connection on;      # 타임아웃된 연결의 메모리를 즉시 회수

server {
    listen 127.0.0.1:8081;             # 외부 노출 금지
    location = /nginx_status {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}
# curl 127.0.0.1:8081/nginx_status
# Active connections: 291
# server accepts handled requests
#  16630948 16630948 31070465
# Reading: 6 Writing: 179 Waiting: 106
# → nginx-prometheus-exporter로 수집해 Grafana에서 시각화

location /api/ {
    add_header X-Debug-Location "api" always;
    add_header X-Debug-Upstream $upstream_addr always;
    # ...
}
# 확인 후 반드시 제거 (내부 주소 노출 방지)

user  nginx;
worker_processes auto;
worker_rlimit_nofile 65535;
pid /run/nginx.pid;
error_log /var/log/nginx/error.log warn;

events {
    worker_connections 8192;
    multi_accept on;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    charset       utf-8;
    server_tokens off;

    sendfile on;  tcp_nopush on;  tcp_nodelay on;
    keepalive_timeout 65s;
    client_max_body_size 20m;
    client_body_timeout 30s;
    send_timeout 30s;
    reset_timedout_connection on;

    log_format json escape=json '{"time":"$time_iso8601","request_id":"$request_id",'
        '"remote_addr":"$remote_addr","host":"$host","method":"$request_method",'
        '"uri":"$request_uri","status":$status,"bytes":$body_bytes_sent,'
        '"request_time":$request_time,"upstream_addr":"$upstream_addr",'
        '"upstream_response_time":"$upstream_response_time","ua":"$http_user_agent"}';
    access_log /var/log/nginx/access.log json buffer=32k flush=5s;

    gzip on;  gzip_comp_level 5;  gzip_min_length 1024;
    gzip_proxied any;  gzip_vary on;
    gzip_types text/plain text/css application/javascript application/json
               application/xml image/svg+xml;

    open_file_cache max=10000 inactive=30s;
    open_file_cache_valid 60s;

    limit_req_zone  $binary_remote_addr zone=api_rl:10m rate=10r/s;
    limit_conn_zone $binary_remote_addr zone=conn_per_ip:10m;
    limit_req_status 429;
    limit_conn_status 429;

    proxy_cache_path /var/cache/nginx/api levels=1:2 keys_zone=api_cache:50m
                     max_size=2g inactive=30m use_temp_path=off;

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

upstream api_backend {
    least_conn;
    server 10.0.1.11:8080 max_fails=3 fail_timeout=30s;
    server 10.0.1.12:8080 max_fails=3 fail_timeout=30s;
    keepalive 64;
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

# 알 수 없는 Host 차단
server {
    listen 80 default_server;
    listen 443 ssl default_server;
    server_name _;
    ssl_reject_handshake on;
    return 444;
}

# http → https
server {
    listen 80;
    server_name example.com www.example.com;
    location /.well-known/acme-challenge/ { root /var/www/certbot; }
    location / { return 301 https://example.com$request_uri; }
}

server {
    listen 443 ssl;
    http2 on;
    server_name example.com;

    include snippets/ssl-params.conf;
    include snippets/hsts.conf;
    include snippets/security-headers.conf;

    root /var/www/example/dist;
    index index.html;

    location ~ /\.(?!well-known/) { deny all; }

    # 해시가 붙은 빌드 산출물 — 1년 캐시
    location ^~ /assets/ {
        include snippets/hsts.conf;              # add_header 상속 함정 대비 — 다시 포함
        include snippets/security-headers.conf;
        add_header Cache-Control "public, max-age=31536000, immutable";
        try_files $uri =404;
        access_log off;
    }

    location ^~ /api/ {
        limit_req  zone=api_rl burst=20 nodelay;
        limit_conn conn_per_ip 20;
        include snippets/proxy-headers.conf;
        proxy_set_header Connection "";
        proxy_connect_timeout 3s;
        proxy_read_timeout 30s;
        proxy_pass http://api_backend;
    }

    location ^~ /ws/ {
        proxy_pass http://api_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 1h;
    }

    # SPA 라우팅
    location / {
        try_files $uri $uri/ /index.html;
    }
}