🟢
Nginx 치트시트

리버스 프록시, 로드 밸런싱(Upstream), SSL/TLS(HTTPS), SPA 라우팅, Location 매칭 우선순위, Rate Limiting 및 실무 트러블슈팅 레퍼런스
#nginx#webserver#reverse-proxy#ssl#load-balancing#devops#infrastructure최종 업데이트: 2026-09-27
Nginx 치트시트 핵심 명령어 및 실전 가이드

리버스 프록시, 로드 밸런싱(Upstream), SSL/TLS(HTTPS), SPA 라우팅, Location 매칭 우선순위, Rate Limiting 및 실무 트러블슈팅 레퍼런스
## 1. CLI 핵심 제어 & 시스템 서비스 (CLI & Service Control)
```bash
# [1] 설정 파일 문법 검사 (설정 수정 후 무조건 먼저 실행!)
nginx -t
# 특정 설정 파일 경로를 지정하여 문법 검사
nginx -t -c /etc/nginx/nginx.conf

# [2] 서비스 중단 없는 무중단 설정 리로드 (Graceful Reload)
nginx -s reload
# 즉시 정지 (Fast Shutdown) vs 안전 정지 (Graceful Shutdown)
nginx -s stop        # 즉시 강제 종료
nginx -s quit        # 현재 처리 중인 연결을 모두 완료한 후 안전 종료

# [3] Linux systemd 서비스 관리 명령어
sudo systemctl status nginx    # 현재 실행 상태 및 PID 확인
sudo systemctl start nginx     # Nginx 서비스 시작
sudo systemctl stop nginx      # Nginx 서비스 중지
sudo systemctl restart nginx   # 프로세스 완전 재시작
sudo systemctl reload nginx    # 설정 리로드 (권장)
sudo systemctl enable nginx    # 부팅 시 자동 시작 등록

# [4] 버전 및 컴파일 모듈 정보 확인
nginx -v             # 기본 버전 출력 (예: nginx version: 1.24.0)
nginx -V             # 컴파일된 모듈 및 configure 인수 상세 확인
```

## 2. nginx.conf 기본 골격 구조 (Architecture & Contexts)
```nginx
# /etc/nginx/nginx.conf - 메인 설정 파일 계층 구조

user nginx;                  # 워커 프로세스를 실행할 시스템 계정
worker_processes auto;       # CPU 코어 수에 맞춰 자동 워커 생성
pid /var/run/nginx.pid;

# 1. 이벤트 블록: 네트워크 연결 처리 방식
events {
    worker_connections 1024; # 워커 프로세스당 동시 허용 커넥션 수
    use epoll;               # Linux 고성능 이벤트 폴링 방식
    multi_accept on;         # 한 번에 여러 연결을 수락
}

# 2. HTTP 블록: 웹 트래픽 전역 설정
http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # 성능 최적화 디렉티브
    sendfile on;             # 커널 레벨에서 파일 직접 전송 (Zero-Copy)
    tcp_nopush on;           # 패킷이 가득 찼을 때만 전송 (헤더 최적화)
    tcp_nodelay on;          # 소켓 버퍼 지연 방지 (Keep-Alive 최적화)
    keepalive_timeout 65;    # 클라이언트 유휴 커넥션 유지 시간(초)

    # Gzip 압축 전송 설정
    gzip on;
    gzip_min_length 1024;
    gzip_comp_level 5;
    gzip_types text/plain text/css application/json application/javascript text/xml;

    # 개별 사이트 가상 호스트 설정 파일 포함
    include /etc/nginx/conf.d/*.conf;
}
```

## 3. 리버스 프록시 설정 (Reverse Proxy)
```nginx
# 백엔드 WAS(Spring Boot, Node.js, Django 등)로 요청 전달
server {
    listen 80;
    server_name api.luckytechworld.com;

    location / {
        # 백엔드 서버 주소 (내부 포트 8080)
        proxy_pass http://127.0.0.1:8080;

        # ⚠️ 필수 프록시 헤더 전달 (백엔드에서 실제 클라이언트 IP 식별)
        proxy_set_header Host $host;                         # 원본 요청 호스트
        proxy_set_header X-Real-IP $remote_addr;             # 실제 접속 클라이언트 IP
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 거쳐온 프록시 IP 체인
        proxy_set_header X-Forwarded-Proto $scheme;          # http 또는 https 프로토콜

        # HTTP/1.1 프로토콜 사용 (Keep-Alive 지원)
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        # 프록시 버퍼 및 타임아웃
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}
```

## 4. 로드 밸런싱 & 업스트림 (Load Balancing: upstream)
```nginx
# 다중 백엔드 인스턴스로 트래픽 분산
upstream backend_cluster {
    # 1. 라운드 로빈 (기본값): 균등 분배
    # 2. least_conn: 현재 연결 수가 가장 적은 서버로 분배
    # least_conn;
    # 3. ip_hash: 클라이언트 IP 기반 고정 세션 (Sticky Session)
    # ip_hash;

    server 10.0.1.10:8080 weight=3 max_fails=3 fail_timeout=10s; # 가중치 3 (우선 전달)
    server 10.0.1.11:8080 weight=1 max_fails=3 fail_timeout=10s;
    server 10.0.1.12:8080 backup; # 다른 서버 장애 시에만 동작하는 예비 서버
    server 10.0.1.13:8080 down;   # 점검 중으로 제외된 서버

    keepalive 32; # 업스트림 서버와의 유휴 커넥션 유지 풀
}

server {
    listen 80;
    server_name service.luckytechworld.com;

    location / {
        proxy_pass http://backend_cluster;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

## 5. 정적 파일 호스팅 & SPA 라우팅 (Static Files & SPA)
```nginx
# Vue, React, Angular 등 SPA 및 정적 에셋 서빙
server {
    listen 80;
    server_name luckytechworld.com;

    root /var/www/dist; # 정적 파일 루트 디렉토리
    index index.html;

    # [1] SPA 브라우저 새로고침 404 해결 (필수!)
    # 파일 -> 디렉토리 -> 없으면 index.html로 내부 리다이렉트
    location / {
        try_files $uri $uri/ /index.html;
    }

    # [2] 정적 에셋(이미지, JS, CSS) 브라우저 캐싱 (1년 보관)
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 1y;
        add_header Cache-Control "public, no-transform, immutable";
        access_log off; # 에셋 요청은 액세스 로그 제외로 I/O 절약
    }

    # [3] 숨김 파일(.git, .env 등) 접근 차단
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }
}
```

## 6. SSL/TLS (HTTPS) 인증서 & 리다이렉트
```nginx
# [1] 80번 포트(HTTP) -> 443번 포트(HTTPS) 영구 리다이렉트 (301)
server {
    listen 80;
    listen [::]:80;
    server_name luckytechworld.com www.luckytechworld.com;

    return 301 https://$host$request_uri;
}

# [2] 443번 포트 (HTTPS & HTTP/2 보안 서버)
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name luckytechworld.com www.luckytechworld.com;

    # Let's Encrypt 또는 상용 SSL 인증서 경로
    ssl_certificate /etc/letsencrypt/live/luckytechworld.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/luckytechworld.com/privkey.pem;

    # 안전한 암호화 프로토콜 및 세션 설정
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384";
    ssl_session_cache shared:SSL:10m; # 10MB 캐시 (약 4만 세션 공유)
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    # HSTS 설정 (브라우저에 1년간 무조건 HTTPS 접속 강제)
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

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

## 7. Location 매칭 문법 & 우선순위 (Location Matching)
```nginx
# [Location 매칭 우선순위 규칙 (위에서부터 우선 평가됨)]
# 1순위: =  (정확한 일치 - Exact Match)
location = /login {
    # /login 에만 완벽히 일치 (쿼리스트링 제외)
}

# 2순위: ^~ (정규식 검사 중단 전방 일치)
location ^~ /images/ {
    # /images/ 로 시작하는 경로는 아래 정규식(~)을 건너뛰고 즉시 적용
}

# 3순위: ~  (대소문자 구분 정규 표현식)
location ~ \.(php|py)$ { }

# 4순위: ~* (대소문자 무시 정규 표현식)
location ~* \.(jpg|png|gif)$ { }

# 5순위: /prefix (가장 긴 전방 일치 - Prefix Match)
location /api/v1/ { }

# 최하위: / (기본 폴백 - Default Fallback)
location / {
    # 일치하는 다른 룰이 없을 때 최종 실행
}
```

## 8. 보안 헤더 & IP 접근 제어 (Security & Access Control)
```nginx
# 전역 보안 응답 헤더 추가 (클릭재킹, XSS 방지)
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;

# 관리자 페이지 특정 IP만 허용 (IP Whitelist)
location /admin/ {
    allow 192.168.1.100;      # 특정 사내 IP 허용
    allow 10.0.0.0/24;        # 서브넷 허용
    deny all;                 # 그 외 모든 IP 차단 (403 Forbidden)

    proxy_pass http://127.0.0.1:8080;
}

# 특정 악성 IP 수동 차단 (Blacklist)
location / {
    deny 203.0.113.50;        # 악성 봇 IP 차단
    deny 198.51.100.0/24;
    # ...
}
```

## 9. 속도 제한 & DDoS 방어 (Rate Limiting)
```nginx
# http 블록에 속도 제한 영역 정의
http {
    # 클라이언트 IP($binary_remote_addr) 기준으로 10MB 메모리 할당, 초당 10개 요청 제한
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
    # IP당 동시 활성 커넥션 수 제한 영역
    limit_conn_zone $binary_remote_addr zone=conn_limit:10m;

    server {
        listen 80;

        # 로그인 및 회원가입 엔드포인트 무차별 대입 방어
        location /api/v1/auth/ {
            # burst=5: 순간적으로 최대 5개 요청까지는 버퍼에 대기 허용
            # nodelay: 대기 없이 즉시 처리하되 한도 초과 시 503 반환
            limit_req zone=api_limit burst=5 nodelay;
            limit_conn conn_limit 5; # 단일 IP당 동시 커넥션 최대 5개

            limit_req_status 429; # 기본 503 대신 429 Too Many Requests 반환

            proxy_pass http://127.0.0.1:8080;
        }
    }
}
```

## 10. 웹소켓 프록시 설정 (WebSocket: ws / wss)
```nginx
# WebSocket은 HTTP/1.1 업그레이드 헤더 교환이 필수적임
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name socket.luckytechworld.com;

    location /ws/ {
        proxy_pass http://127.0.0.1:8080;

        # 웹소켓 전용 필수 디렉티브
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # 긴 연결 유지를 위한 읽기 타임아웃 연장 (기본 60초 -> 1시간)
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}
```

## 11. 업로드 용량 & 버퍼/타임아웃 튜닝 (Tuning & Uploads)
```nginx
server {
    listen 80;

    # [1] 대용량 파일 업로드 시 413 Request Entity Too Large 해결
    client_max_body_size 50M;      # 최대 업로드 파일 크기 (기본값: 1M)
    client_body_buffer_size 128k;   # 메모리 내 요청 본문 버퍼 크기

    # [2] 백엔드 응답 대용량 다운로드 및 버퍼 설정
    proxy_buffering on;            # 프록시 버퍼링 활성화
    proxy_buffer_size 16k;         # 첫 응답 헤더 버퍼 크기
    proxy_buffers 8 64k;           # 본문 버퍼 수 및 크기 (8 x 64k = 512k)
    proxy_busy_buffers_size 128k;

    # [3] 대용량 배치/보고서 API 지연 대기 (504 Gateway Timeout 방지)
    proxy_connect_timeout 120s;    # 백엔드 서버 연결 타임아웃
    proxy_read_timeout 300s;       # 백엔드 응답 읽기 대기 타임아웃 (5분)
    proxy_send_timeout 300s;       # 백엔드로 데이터 전송 타임아웃
}
```

## 12. 실무 트러블슈팅 & 로그 분석 (Troubleshooting & Logs)
```nginx
# [1] 커스텀 JSON 포맷 액세스 로그 (ELK / CloudWatch 수집용)
log_format json_analytics escape=json
  '{"time_local":"$time_local",'
  '"client_ip":"$remote_addr",'
  '"request_method":"$request_method",'
  '"request_uri":"$request_uri",'
  '"status":"$status",'
  '"body_bytes_sent":"$body_bytes_sent",'
  '"request_time":"$request_time",'
  '"upstream_response_time":"$upstream_response_time",'
  '"upstream_addr":"$upstream_addr",'
  '"http_user_agent":"$http_user_agent"}';

access_log /var/log/nginx/access.log json_analytics;
error_log /var/log/nginx/error.log warn; # debug, info, notice, warn, error, crit
```
```bash
# [2] 대표적인 HTTP 에러 원인 및 해결 체크리스트
# 502 Bad Gateway:
#  - 원인: 백엔드 WAS가 꺼져 있거나 포트/소켓이 열려있지 않음.
#  - 확인: curl http://127.0.0.1:8080 또는 sudo netstat -tlpn | grep 8080

# 504 Gateway Timeout:
#  - 원인: 백엔드 처리 시간이 proxy_read_timeout(기본 60초)을 초과함.
#  - 해결: 백엔드 쿼리 튜닝 또는 proxy_read_timeout 상향 조정.

# 413 Request Entity Too Large:
#  - 원인: 파일 업로드 크기가 client_max_body_size 한도를 초과함.
#  - 해결: client_max_body_size 50M; 설정 추가 후 reload.

# 실시간 에러 로그 모니터링:
sudo tail -f /var/log/nginx/error.log
```
💬
Nginx 치트시트

의견 및 질문

댓글 수정

댓글 삭제
