ps aux | grep nginx
# root     1234  nginx: master process /usr/sbin/nginx
# www-data 1235  nginx: worker process
# www-data 1236  nginx: worker process
# www-data 1237  nginx: cache manager process

왜 이 구조가 빠른가

연결 10,000개 = 스레드 10,000개

· 스레드마다 메모리(수백 KB~수 MB)
· 컨텍스트 스위칭 비용 폭증
· 대부분의 스레드는 그냥 '기다리는 중'

연결 10,000개 = 워커 4개

· 각 워커가 epoll 로 "준비된 연결"만 처리
· 기다리는 연결은 자원을 거의 안 씀
· 메모리 사용량이 연결 수에 거의 비례하지 않음

# /etc/nginx/nginx.conf
user  www-data;
worker_processes  auto;            # CPU 코어 수만큼 자동 (권장)
worker_rlimit_nofile  65535;       # 워커당 열 수 있는 파일·소켓 수

events {
    worker_connections  4096;      # 워커 하나가 다룰 최대 연결
    multi_accept  on;              # 한 번에 여러 연결을 받아들임
    use epoll;                     # 리눅스 기본값 (명시하지 않아도 됨)
}

# 이론상 최대 동시 연결 = worker_processes × worker_connections
# 단, 프록시는 클라이언트 1 + 업스트림 1 = 연결 2개를 씁니다

# 사이트 활성화 · 비활성화 (Ubuntu 계열)
sudo ln -s /etc/nginx/sites-available/mysite /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default          # 기본 사이트 제거

# 검증 → 반영 (이 순서를 반드시 지키세요)
sudo nginx -t
sudo systemctl reload nginx

# 지금 적용 중인 전체 설정 보기 (include 를 전부 펼침)
sudo nginx -T | less

# 버전과 컴파일 옵션
nginx -V

막혔을 때 먼저 칠 명령

# 진단에 필요한 값을 로그에 미리 넣어 두세요 — 사고 뒤에 넣으면 늦습니다
log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
                  'rt=$request_time urt=$upstream_response_time '        # ★ 어디가 느린가
                  'us=$upstream_status ua=$upstream_addr '               # ★ 어느 백엔드
                  'srv=$server_name host=$host';                          # ★ 어느 블록

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

# 상태 페이지 — 로컬에서만
server {
    listen 127.0.0.1:8080;
    location /nginx_status {
        stub_status;
        access_log off;
    }
}

http {                                  # ── 컨텍스트(블록)
    gzip on;                            # ── 지시어 (세미콜론 필수)
    keepalive_timeout 65;

    server {                            # 안쪽 블록은 바깥 설정을 물려받습니다
        listen 80;
        server_name example.com;
        gzip off;                       # 여기서 다시 쓰면 이 server 안에서는 off

        location /api/ {
            proxy_pass http://app:3000;
        }
    }
}

자주 쓰는 내장 변수

# 사이트 A
server {
    listen 80;
    server_name a.example.com;
    root /var/www/a;
}

# 사이트 B
server {
    listen 80;
    server_name b.example.com www.b.example.com;    # 여러 개 가능
    root /var/www/b;
}

# 어디에도 안 걸리는 요청 처리 (직접 IP 접속·봇 등)
server {
    listen 80 default_server;
    server_name _;
    return 444;               # 아무 응답 없이 연결을 끊습니다 (Nginx 전용 코드)
}

server_name 매칭 우선순위

공통 설정을 파일로 빼기

# /etc/nginx/snippets/proxy-common.conf
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_http_version 1.1;
proxy_read_timeout 60s;

# 사용하는 쪽
location /api/ {
    include /etc/nginx/snippets/proxy-common.conf;
    proxy_pass http://app:3000;
}

server {
    listen 443 ssl default_server;
    http2 on;
    server_name example.com;
    root /var/www/example;

    # ① 정확히 일치 — 가장 빠릅니다. 호출이 잦은 경로에
    location = / {
        try_files /index.html =404;
    }
    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    # ② ^~ — 정적 자원을 정규식이 가로채지 못하게 막습니다
    location ^~ /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # ③ 정규식 — 여기서만 파일 순서가 중요합니다
    location ~* \.(?:jpg|jpeg|png|gif|webp|svg|woff2)$ {
        expires 30d;
        add_header Cache-Control "public";
    }

    # 숨김 파일 차단 (.git · .env) — 반드시 넣으세요
    location ~ /\.(?!well-known) {
        deny all;
        access_log off;
    }

    # ④ 일반 접두사 — 가장 긴 것이 이깁니다
    location /api/ {
        include /etc/nginx/snippets/proxy-common.conf;
        proxy_pass http://app:3000;          # 끝 슬래시 주의 (아래 warn)
    }

    location / {
        try_files $uri $uri/ /index.html;    # SPA 폴백
    }
}

server {
    location = /images/logo.png { … }      # ① 정확히 일치 (최우선 · 즉시 확정)
    location ^~ /static/       { … }       # ② 접두사 + 정규식 건너뛰기
    location ~ \.(jpg|png)$    { … }       # ④ 정규식 (대소문자 구분)
    location ~* \.(jpg|png)$   { … }       # ④ 정규식 (대소문자 무시)
    location /api/             { … }       # ③ 일반 접두사
    location /                 { … }       # ③ 가장 짧은 접두사 = 최후의 보루
}

규칙을 말로 풀면

1. = 로 정확히 일치하는 것이 있으면 거기서 끝입니다
2. 없으면 가장 길게 일치하는 접두사를 기억해 둡니다
3. 그 접두사가 ^~ 였다면 정규식을 아예 보지 않고 확정합니다
4. 아니면 정규식들을 설정 파일에 적힌 순서대로 검사해 처음 일치하는 것을 씁니다
5. 정규식에 하나도 안 걸리면 2에서 기억해 둔 접두사 매칭을 씁니다

root 와 alias — 가장 헷갈리는 한 쌍

location /static/ {
    root /var/www;
}

# 요청: /static/app.css
# 실제: /var/www + /static/app.css
#     = /var/www/static/app.css

location /static/ {
    alias /var/www/assets/;      # ★ 끝 슬래시 필수
}

# 요청: /static/app.css
# 실제: /var/www/assets/app.css
#     (location 부분이 alias 로 치환)

try_files — 순서대로 찾기

# 파일 → 폴더 → 404
location / {
    root /var/www/html;
    try_files $uri $uri/ =404;
}

# ★ SPA (React·Vue) — 없는 경로는 전부 index.html 로
location / {
    root /var/www/spa;
    try_files $uri $uri/ /index.html;
}

# 파일이 없으면 앱으로 넘기기 (하이브리드)
location / {
    root /var/www/html;
    try_files $uri $uri/ @app;
}
location @app {
    proxy_pass http://127.0.0.1:3000;
}

정적 파일 캐시 설정

# 해시가 붙은 빌드 산출물 — 아주 길게 캐시
location ~* \.(?:css|js|woff2?)$ {
    root /var/www/spa;
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;                       # 정적 파일 로그는 꺼서 IO 절약
}

# 이미지
location ~* \.(?:png|jpe?g|gif|svg|ico|webp|avif)$ {
    root /var/www/spa;
    expires 30d;
    add_header Cache-Control "public";
}

# index.html 은 절대 캐시하면 안 됩니다 (새 배포가 반영되지 않습니다)
location = /index.html {
    root /var/www/spa;
    add_header Cache-Control "no-store, must-revalidate";
}

슬래시의 차이 — 반드시 알아야 합니다

location /api/ {
    proxy_pass http://app:3000;
}

# 요청  : /api/users
# 전달  : http://app:3000/api/users
#         (location 경로가 그대로 유지)

location /api/ {
    proxy_pass http://app:3000/;
}

# 요청  : /api/users
# 전달  : http://app:3000/users
#         (/api/ 가 / 로 치환)

실무에서 쓰는 완전한 형태

location /api/ {
    proxy_pass http://127.0.0.1:3000;

    # ── 원래 요청 정보를 앱에 전달 (n08 에서 자세히)
    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-Forwarded-Host  $host;

    # ── HTTP/1.1 + keepalive (기본은 1.0 이라 매번 새 연결을 맺습니다)
    proxy_http_version 1.1;
    proxy_set_header Connection "";

    # ── 타임아웃 (기본 60초)
    proxy_connect_timeout 5s;        # 연결 수립 — 짧게
    proxy_send_timeout   60s;
    proxy_read_timeout   60s;        # 앱 응답 대기 — 504 의 기준

    # ── 버퍼링 (기본 on)
    proxy_buffering on;
    proxy_buffer_size 8k;
    proxy_buffers 8 8k;
}

경로별로 다른 앱에 보내기

server {
    listen 80;
    server_name example.com;

    # 프런트엔드 정적 파일
    location / {
        root /var/www/spa;
        try_files $uri $uri/ /index.html;
    }

    # 자바 API
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        include /etc/nginx/snippets/proxy-common.conf;
    }

    # 파이썬 관리자
    location /admin/ {
        proxy_pass http://127.0.0.1:8000;
        include /etc/nginx/snippets/proxy-common.conf;
    }

    # 업로드된 파일 (앱을 거치지 않고 직접)
    location /uploads/ {
        alias /var/data/uploads/;
        add_header Content-Disposition "attachment";     # 브라우저에서 실행되지 않게
    }
}

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_add_x_forwarded_for 는
#   기존 X-Forwarded-For 값이 있으면 ", $remote_addr" 를 덧붙이고
#   없으면 $remote_addr 만 넣습니다

앱 쪽 설정도 필요합니다

server.forward-headers-strategy=native
# 또는 = framework
# 프록시 뒤에 있을 때 반드시 설정하세요

SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
USE_X_FORWARDED_HOST = True
ALLOWED_HOSTS = ['example.com']

app.set('trust proxy', 1);   // 앞단 프록시 1개를 신뢰
// req.ip · req.protocol 이 올바르게 동작합니다

uvicorn main:app \
  --proxy-headers \
  --forwarded-allow-ips='127.0.0.1'

# 앞단에 CDN·LB 가 또 있을 때 : 신뢰할 대역을 지정해 실제 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 가 됩니다 (로그·rate limit 에 그대로 적용)

upstream backend {
    # 기본은 라운드 로빈 (순서대로 돌아가며)
    server 10.0.1.11:3000 weight=3;              # 3배 더 많이 받음
    server 10.0.1.12:3000;
    server 10.0.1.13:3000 max_fails=3 fail_timeout=30s;
    server 10.0.1.14:3000 backup;                # 다른 서버가 전부 죽으면 투입

    keepalive 32;                                # ★ 업스트림 연결 재사용
}

server {
    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";          # ★ keepalive 를 쓰려면 필수
        include /etc/nginx/snippets/proxy-common.conf;
    }
}

분산 방식

장애 감지

upstream backend {
    server 10.0.1.11:3000 max_fails=3 fail_timeout=30s;
    # 30초 안에 3번 실패하면 30초간 그 서버를 제외합니다 (수동적 헬스체크)
}

server {
    location / {
        proxy_pass http://backend;

        # 어떤 상황에서 다음 서버로 재시도할지
        proxy_next_upstream error timeout http_502 http_503 http_504;
        proxy_next_upstream_tries 2;
        proxy_next_upstream_timeout 10s;
    }
}

# 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://$host$request_uri;
    }
}

# 실제 서비스
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;                                    # 1.25.1+ 문법
    server_name example.com www.example.com;

    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;
    ssl_prefer_server_ciphers off;               # TLS1.3 에서는 클라이언트 우선이 권장
    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;

    ssl_session_cache   shared:SSL:10m;          # 재접속 시 협상 생략 → 지연 감소
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    # OCSP 스테이플링 — ※ Let's Encrypt 는 2025년에 OCSP 를 종료해
    #   LE 인증서에는 OCSP 주소가 없습니다 (켜 두면 경고만 남고 무시됨)
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 1.1.1.1 8.8.8.8 valid=300s;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    root /var/www/html;
}

HTTP/3 (QUIC) 1.25+

server {
    listen 443 ssl;
    listen 443 quic reuseport;          # ★ UDP 443 — 방화벽도 열어야 합니다
    http2 on;
    http3 on;

    ssl_protocols TLSv1.3;              # HTTP/3 는 TLS1.3 필수

    # 브라우저에게 "HTTP/3 로도 접속할 수 있다"고 알림
    add_header Alt-Svc 'h3=":443"; ma=86400';
}

# UDP 443 을 여는 것을 잊지 마세요
sudo ufw allow 443/udp

# 지원 여부 확인
nginx -V 2>&1 | grep -o with-http_v3_module

# ── return : 가장 단순하고 빠릅니다 (가능하면 이것을 쓰세요)
server {
    listen 80;
    server_name old.example.com;
    return 301 https://new.example.com$request_uri;      # 영구 이동
}

# www 를 붙이거나 떼기
server {
    server_name www.example.com;
    return 301 https://example.com$request_uri;
}

# ── rewrite : 정규식으로 경로를 바꿉니다
location / {
    rewrite ^/old/(.*)$ /new/$1 permanent;      # 301 리다이렉트 (브라우저 주소가 바뀜)
    rewrite ^/api/v1/(.*)$ /v1/$1 last;         # 내부 재처리 (주소는 그대로)
}

조건부 처리 — if 는 조심해서

# Nginx 의 if 는 location 안에서 예상 밖으로 동작할 수 있습니다
# (공식 위키에도 "If is Evil" 문서가 있습니다)

# ✗ 피할 것
location / {
    if ($http_user_agent ~* "bot") {
        return 403;
    }
    proxy_pass http://app;      # if 안에서 다른 지시어와 섞이면 문제가 생깁니다
}

# ✓ map 을 쓰세요 (http 컨텍스트에 정의)
map $http_user_agent $is_bot {
    default        0;
    "~*bot|crawl"  1;
}
server {
    location / {
        if ($is_bot) { return 403; }        # return 만 쓰는 if 는 안전합니다
        proxy_pass http://app;
    }
}

# http 컨텍스트에
gzip on;
gzip_vary on;                    # ★ Vary: Accept-Encoding — 캐시가 압축본과 원본을 구분
gzip_comp_level 5;               # 1~9 · 5~6 이 적정 (9는 CPU 낭비)
gzip_min_length 1024;            # 1KB 미만은 압축해도 이득이 없습니다
gzip_proxied any;                # 프록시를 거친 요청도 압축
gzip_types
    text/plain text/css text/xml text/javascript
    application/json application/javascript application/xml+rss
    application/atom+xml image/svg+xml
    application/vnd.ms-fontobject font/ttf font/otf;
# text/html 은 항상 압축되므로 목록에 넣지 않습니다

brotli — gzip 보다 15~20% 더 작게

# 모듈이 필요합니다 (nginx.org 공식 패키지 또는 직접 빌드)
brotli on;
brotli_comp_level 5;
brotli_min_length 1024;
brotli_types text/plain text/css application/json application/javascript image/svg+xml;

# gzip 과 함께 두면 브라우저가 지원하는 쪽을 자동으로 씁니다

# 모듈 설치 (nginx.org 저장소 기준)
sudo apt install -y nginx-module-brotli

# nginx.conf 최상단에
# load_module modules/ngx_http_brotli_filter_module.so;
# load_module modules/ngx_http_brotli_static_module.so;

미리 압축해 두기 (정적 파일)

# 빌드 시점에 app.js.gz · app.js.br 을 함께 만들어 두면
# 요청마다 압축하지 않고 그 파일을 그대로 보냅니다 (CPU 0)
gzip_static on;
brotli_static on;

# 빌드 후
find dist -type f \( -name '*.js' -o -name '*.css' -o -name '*.html' \) \
  -exec gzip -9 -k {} \; -exec brotli -9 -k {} \;

# 압축이 실제로 적용되는지 확인
curl -H "Accept-Encoding: gzip" -I https://example.com/app.js | grep -i content-encoding
# content-encoding: gzip

# http 컨텍스트에 캐시 저장소 정의
proxy_cache_path /var/cache/nginx
                 levels=1:2
                 keys_zone=app_cache:100m      # 키 저장용 공유 메모리 (100MB ≈ 80만 개)
                 max_size=10g                  # 디스크 최대 사용량
                 inactive=60m                  # 60분간 접근 없으면 삭제
                 use_temp_path=off;

server {
    location /api/products {
        proxy_cache app_cache;
        proxy_cache_key "$scheme$request_method$host$request_uri";

        proxy_cache_valid 200 302  10m;        # 정상 응답은 10분
        proxy_cache_valid 404       1m;
        proxy_cache_valid any       30s;

        # 백엔드가 죽어도 옛 캐시로 응답 (아주 중요한 장치)
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
        proxy_cache_background_update on;      # 만료된 캐시를 주면서 뒤에서 갱신
        proxy_cache_lock on;                   # 동시 요청 중 하나만 백엔드로 (스탬피드 방지)

        add_header X-Cache-Status $upstream_cache_status;   # HIT · MISS · EXPIRED · STALE

        proxy_pass http://backend;
    }
}

# 캐시가 먹는지 확인
curl -I https://example.com/api/products | grep -i x-cache-status
# X-Cache-Status: MISS   ← 첫 요청
# X-Cache-Status: HIT    ← 두 번째부터

캐시하면 안 되는 것

# 로그인 사용자별 응답은 절대 캐시하면 안 됩니다
# (다른 사람의 개인정보가 노출되는 심각한 사고가 됩니다)

proxy_cache_bypass $http_authorization $cookie_sessionid;   # 이 값이 있으면 캐시를 건너뜀
proxy_no_cache     $http_authorization $cookie_sessionid;   # 저장도 하지 않음

# 또는 캐시 키에 사용자 구분을 넣습니다 (적중률은 떨어집니다)
proxy_cache_key "$scheme$request_method$host$request_uri$cookie_sessionid";

캐시 무효화

# 오픈소스 Nginx 에는 선택적 삭제(purge) 기능이 없습니다
# ① 파일을 직접 지우기 (가장 단순)
sudo find /var/cache/nginx -type f -delete
sudo systemctl reload nginx

# ② 캐시 키에 버전을 넣어 통째로 갈아치우기
# proxy_cache_key "v2:$scheme$request_method$host$request_uri";

# ③ ngx_cache_purge 모듈을 넣어 빌드 (서드파티)
# ④ 짧은 TTL + stale-while-revalidate 로 운영

server {
    # 업로드 최대 크기 (기본값 1m — 매우 작습니다)
    client_max_body_size 50m;

    # 요청 본문을 읽는 타임아웃
    client_body_timeout 120s;
    client_header_timeout 30s;

    # 본문 버퍼 (넘으면 임시 파일에 씁니다)
    client_body_buffer_size 128k;
    client_body_temp_path /var/cache/nginx/client_temp;

    location /upload {
        proxy_pass http://app:3000;

        # 프록시 타임아웃도 함께 늘려야 합니다
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;

        # 큰 업로드는 버퍼링을 끄고 스트리밍으로 넘기는 편이 나을 수 있습니다
        proxy_request_buffering off;
    }
}

대용량 파일은 우회하는 것이 정답

수백 MB~GB 파일을 웹서버와 앱을 거쳐 올리는 것은 메모리·디스크·타임아웃 모두에 부담입니다. 실무에서는 클라이언트가 스토리지에 직접 업로드하는 방식을 씁니다.

① 브라우저 → 앱 : "파일 올릴 건데 업로드 주소 좀"
② 앱 → 브라우저 : 서명된 임시 업로드 URL (presigned URL)
③ 브라우저 → S3 등 스토리지 : 파일을 직접 전송  ← 서버를 거치지 않습니다
④ 브라우저 → 앱 : "다 올렸어요, 이 키로 저장됐습니다"

· 서버 부하 0 · 타임아웃 문제 없음 · 확장에 유리

# http 컨텍스트에
log_format main_ext '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    'rt=$request_time uct=$upstream_connect_time '
                    'uht=$upstream_header_time urt=$upstream_response_time '
                    'cache=$upstream_cache_status host=$host';

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

JSON 로그 — 수집 도구와 연동할 때

log_format json_log escape=json
  '{'
    '"time":"$time_iso8601",'
    '"remote_addr":"$remote_addr",'
    '"method":"$request_method",'
    '"uri":"$request_uri",'
    '"status":$status,'
    '"bytes":$body_bytes_sent,'
    '"referer":"$http_referer",'
    '"ua":"$http_user_agent",'
    '"request_time":$request_time,'
    '"upstream_time":"$upstream_response_time",'
    '"host":"$host",'
    '"request_id":"$request_id"'
  '}';

access_log /var/log/nginx/access.json json_log;

로그를 줄이는 방법

# 정적 파일·헬스체크는 기록하지 않기
location = /health { access_log off; return 200 "ok\n"; }
location ~* \.(css|js|png|jpg|svg|woff2)$ { access_log off; expires 1y; }

# 특정 조건만 기록 (map 으로 판단)
map $status $loggable {
    ~^[23]  0;      # 2xx · 3xx 는 기록 안 함
    default 1;
}
access_log /var/log/nginx/errors.log main_ext if=$loggable;

# 버퍼링으로 디스크 IO 줄이기 (트래픽이 아주 많을 때)
access_log /var/log/nginx/access.log main_ext buffer=32k flush=5s;

# http 컨텍스트에 존을 정의합니다
limit_req_zone  $binary_remote_addr zone=general:10m rate=30r/s;   # 일반 API
limit_req_zone  $binary_remote_addr zone=login:10m   rate=5r/m;    # 로그인 (분당 5회)
limit_conn_zone $binary_remote_addr zone=conn:10m;                 # 동시 연결 수

limit_req_status  429;                    # 기본은 503 — 429 가 의미상 정확합니다
limit_conn_status 429;

server {
    # 전체에 완만한 제한
    limit_req  zone=general burst=60 nodelay;
    limit_conn conn 20;

    # 로그인은 강하게
    location = /api/login {
        limit_req zone=login burst=3 nodelay;
        proxy_pass http://app;
    }

    # 헬스체크는 제외 — limit_req 에는 off 가 없습니다.
    # return 은 rewrite 단계에서 끝나므로 limit_req(preaccess 단계)까지 가지 않습니다
    location = /health {
        return 200 "ok\n";
    }
}

그 밖의 방어 수단

# 대역폭 제한 (다운로드 서버)
location /downloads/ {
    limit_rate_after 10m;        # 처음 10MB 는 최고 속도로
    limit_rate 500k;             # 이후 500KB/s 로 제한
}

# 특정 User-Agent 차단
map $http_user_agent $blocked_ua {
    default              0;
    "~*(scrapy|curl|wget|python-requests)"  1;
}
server {
    if ($blocked_ua) { return 403; }
}

# 지역·IP 차단
location /admin/ {
    allow 10.0.0.0/8;
    allow 203.0.113.5;
    deny  all;
}

# http 컨텍스트 — Upgrade 헤더를 조건부로 만듭니다
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    location /ws/ {
        proxy_pass http://app:3000;

        # ★ WebSocket 핸드셰이크에 필수
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host       $host;

        # ★ 유휴 연결이 끊기지 않게 (기본 60초면 1분마다 끊깁니다)
        proxy_read_timeout  3600s;
        proxy_send_timeout  3600s;

        # 버퍼링을 끄지 않으면 메시지가 모였다가 한꺼번에 갑니다
        proxy_buffering off;
    }
}

SSE (Server-Sent Events)

location /events {
    proxy_pass http://app:3000;
    proxy_http_version 1.1;
    proxy_set_header Connection '';       # keepalive 유지

    proxy_buffering off;                  # ★ 필수 — 없으면 이벤트가 안 나갑니다
    proxy_cache off;
    proxy_read_timeout 3600s;

    chunked_transfer_encoding off;
    # add_header X-Accel-Buffering no;  ← 효과 없음: 브라우저에게 보낼 뿐입니다.
    #   이 헤더는 앱(업스트림)이 응답에 실어 보내야 Nginx 가 읽고 버퍼링을 끕니다
}

gRPC 프록시

server {
    listen 443 ssl;
    http2 on;                             # gRPC 는 HTTP/2 필수

    location / {
        grpc_pass grpc://app:50051;       # 평문
        # grpc_pass grpcs://app:50051;    # TLS
        grpc_read_timeout 3600s;
    }
}

실시간 세 방식 — 무엇을 언제 쓰나

실시간 연결이 끊길 때 — 확인 순서

# 연결이 많아지면 워커 한계도 함께 올려야 합니다
events {
    worker_connections 10240;      # 워커당 동시 연결 (기본 512~1024)
    use epoll;
}
worker_processes  auto;            # 코어 수
worker_rlimit_nofile 65535;        # ★ 이것을 안 올리면 위 값이 의미 없습니다

# 총 동시 연결 ≈ worker_processes × worker_connections
# 단, 프록시는 연결 하나당 소켓 2개(클라·업스트림)를 씁니다 → 실제로는 절반

http {
    # 업스트림 keepalive — 백엔드로의 연결을 재사용합니다
    upstream app {
        server 127.0.0.1:3000;
        keepalive 64;              # ★ 이것만으로 지연이 눈에 띄게 줄어듭니다
        keepalive_timeout 60s;
    }
}

reload 는 어떻게 무중단이 되나

배포 전 검증 절차

#!/usr/bin/env bash
set -euo pipefail

# 1) 백업 — ★ 설정을 고치기 '전에' 따로 떠 둡니다
#    (고친 뒤에 백업하면 되돌릴 대상도 새 설정이 됩니다)
#    sudo cp -a /etc/nginx /etc/nginx.bak.$(date +%F-%H%M)

# 2) 문법 검사
sudo nginx -t

# 3) 반영
sudo systemctl reload nginx

# 4) 실제 응답 확인
sleep 1
curl -fsS -o /dev/null -w "%{http_code}\n" https://example.com/health

# 실패하면 되돌리기
# sudo rm -rf /etc/nginx && sudo mv /etc/nginx.bak.XXXX /etc/nginx && sudo systemctl reload nginx

# 현재 MPM 확인
apachectl -V | grep MPM
# Server MPM:     event

# Ubuntu 계열에서 전환
sudo a2dismod mpm_prefork
sudo a2enmod mpm_event
sudo systemctl restart apache2

# ※ mod_php 가 켜져 있으면 event 로 전환되지 않습니다
sudo a2dismod php8.3
sudo a2enmod proxy_fcgi setenvif
sudo a2enconf php8.3-fpm

# mpm_event.conf — 동시 처리 설정
<IfModule mpm_event_module>
    StartServers             4
    MinSpareThreads         25
    MaxSpareThreads         75
    ThreadsPerChild         25
    # ★ 동시에 처리할 최대 요청 수
    MaxRequestWorkers      400
    # 0 = 무제한 (메모리 누수가 있으면 10000 등으로)
    MaxConnectionsPerChild   0
</IfModule>

# 설치
sudo apt install -y apache2          # Ubuntu
sudo dnf install -y httpd            # RHEL

sudo systemctl enable --now apache2  # 또는 httpd

# 상태 확인
apachectl -v                         # 버전
apachectl -V                         # 컴파일 정보 · MPM
apachectl -M                         # 로드된 모듈
apachectl -S                         # 가상 호스트 목록 ← 아주 유용합니다
apachectl configtest                 # 문법 검사

sudo systemctl reload apache2        # 무중단 반영
sudo apachectl graceful              # 같은 동작

막혔을 때 먼저 칠 명령

# apache2.conf 의 뼈대
ServerRoot "/etc/apache2"
Listen 80

IncludeOptional mods-enabled/*.load
IncludeOptional mods-enabled/*.conf
IncludeOptional conf-enabled/*.conf
# ← 사이트 설정을 여기서 읽습니다
IncludeOptional sites-enabled/*.conf

User  ${APACHE_RUN_USER}
Group ${APACHE_RUN_GROUP}

# 응답에 버전을 노출하지 않음
ServerTokens Prod
ServerSignature Off
Timeout 60
KeepAlive On
MaxKeepAliveRequests 100
KeepAliveTimeout 5

<Directory />
    Options FollowSymLinks
    AllowOverride None
    # 기본은 전부 차단 (안전한 기본값)
    Require all denied
</Directory>

<Directory /var/www/>
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

자주 쓰는 모듈

# Ubuntu 계열
sudo a2enmod rewrite proxy proxy_http headers deflate expires ssl remoteip
sudo a2dismod autoindex status
sudo systemctl restart apache2

# RHEL 계열 — /etc/httpd/conf.modules.d/*.conf 에서 LoadModule 을 주석 처리·해제
# LoadModule rewrite_module modules/mod_rewrite.so

# /etc/apache2/sites-available/example.com.conf
<VirtualHost *:80>
    ServerName  example.com
    ServerAlias www.example.com
    DocumentRoot /var/www/example

    <Directory /var/www/example>
        Options -Indexes +FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>

    ErrorLog  ${APACHE_LOG_DIR}/example-error.log
    CustomLog ${APACHE_LOG_DIR}/example-access.log combined

    # HTTPS 로 리다이렉트
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
</VirtualHost>

<VirtualHost *:443>
    ServerName example.com
    DocumentRoot /var/www/example

    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem

    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>

sudo a2ensite example.com          # 활성화
sudo a2dissite 000-default         # 기본 사이트 비활성화
sudo apachectl configtest
sudo systemctl reload apache2

sudo apachectl -S                  # 어떤 VirtualHost 가 어떤 순서인지 확인

컨테이너 블록 — 무엇을 언제 쓰나

실전 VirtualHost — 리버스 프록시 · SPA

# sudo a2enmod proxy proxy_http headers rewrite ssl http2
<VirtualHost *:443>
    ServerName example.com
    Protocols h2 http/1.1

    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem

    # ── 1) 정적 SPA
    DocumentRoot /var/www/spa
    <Directory /var/www/spa>
        Options -Indexes +FollowSymLinks
        # ★ .htaccess 를 끄면 눈에 띄게 빨라집니다
        AllowOverride None
        Require all granted

        # 클라이언트 라우팅 폴백
        RewriteEngine On
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule ^ /index.html [L]
    </Directory>

    # ── 2) API 프록시 (/api 접두사를 떼고 넘김)
    # 백엔드에 원래 Host 를 전달
    ProxyPreserveHost On
    ProxyPass        /api/ http://127.0.0.1:8080/
    ProxyPassReverse /api/ http://127.0.0.1:8080/

    <Location /api/>
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-Forwarded-Port  "443"
    </Location>

    # ── 3) WebSocket (Apache 는 명시적으로 잡아 줘야 합니다)
    # sudo a2enmod proxy_wstunnel
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteRule ^/ws/(.*) ws://127.0.0.1:8080/ws/$1 [P,L]

    # ── 4) 프록시 타임아웃 — 기본은 Timeout 값(2.4 기본 60초)을 따릅니다. 백엔드에 맞게 명시하세요
    ProxyTimeout 60

    ErrorLog  ${APACHE_LOG_DIR}/example-error.log
    CustomLog ${APACHE_LOG_DIR}/example-access.log combined
</VirtualHost>

# 파일 시스템 기준 — 실제 폴더에 적용
<Directory /var/www/example>
    # 디렉터리 목록 금지
    Options -Indexes +FollowSymLinks
    # .htaccess 무시 (성능·보안)
    AllowOverride None
    Require all granted
</Directory>

# URL 기준 — 프록시 경로처럼 실제 파일이 없는 곳에도 적용됩니다
<Location /admin>
    Require ip 10.0.0.0/8
    Require ip 203.0.113.5
</Location>

# 민감한 파일 접근 차단 (반드시 넣으세요)
<FilesMatch "^\.|\.(env|git|sql|bak|log|ini|conf)$">
    Require all denied
</FilesMatch>

# 업로드 폴더에서 스크립트 실행 금지 (치명적 취약점 방지)
<Directory /var/www/example/uploads>
    php_admin_flag engine off
    Options -ExecCGI
    AddType text/plain .php .phtml .php3 .php5 .pl .py .cgi
</Directory>

Options 지시어

· 서버 재시작 없이 즉시 반영
· 서버 설정 접근 권한 없이 사용 가능
  (공유 호스팅의 핵심)
· 애플리케이션과 함께 배포 가능
  (워드프레스·라라벨이 기본 제공)
· 폴더 단위로 권한 위임

· ★ 요청마다 파일을 읽습니다
  (상위 폴더 전부를 거슬러 올라가며!)
· 설정이 여러 곳에 흩어져 추적이 어려움
· 문법 오류 시 500 오류 (검증 단계 없음)
· 사용자가 보안 설정을 무력화할 수 있음

# 완전히 끄기 (권장 · 성능 향상)
<Directory /var/www/>
    AllowOverride None
</Directory>

# 필요한 것만 허용
<Directory /var/www/app/>
    AllowOverride FileInfo Options=Indexes
</Directory>

전형적인 .htaccess (워드프레스·라라벨)

# 프런트 컨트롤러 패턴 — 실제 파일이 없으면 index.php 로
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^ index.php [L]
</IfModule>

# 민감 파일 차단
<FilesMatch "^\.|composer\.(json|lock)$">
    Require all denied
</FilesMatch>

# 디렉터리 목록 금지
Options -Indexes

RewriteEngine On

# ── 기본 형태
# RewriteCond  조건 (여러 개 가능 · AND 로 묶임)
# RewriteRule  패턴  대체  [플래그]

# HTTPS 강제
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]

# www 제거
RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
RewriteRule ^(.*)$ https://%1/$1 [R=301,L]

# 실제 파일이 없으면 index.php 로 (프런트 컨트롤러)
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [L]

# 옛 URL 을 새 URL 로
RewriteRule ^article/([0-9]+)$ /posts/$1 [R=301,L]

# 내부 재작성 (주소는 그대로, 처리만 다른 곳에서)
RewriteRule ^api/(.*)$ /backend/api.php?path=$1 [QSA,L]

디버깅 — 규칙이 왜 안 먹는지

# 2.4 부터는 LogLevel 로 rewrite 추적을 켭니다
LogLevel warn rewrite:trace3

# error.log 에 각 단계가 기록됩니다
# trace1(간단) ~ trace8(매우 상세) · 운영에서는 반드시 끄세요 (로그 폭증)

# 모듈 활성화
# sudo a2enmod proxy proxy_http proxy_balancer lbmethod_byrequests headers

<VirtualHost *:80>
    ServerName example.com

    # 원래 Host 헤더를 유지
    ProxyPreserveHost On
    # ★ 정방향 프록시 금지 (켜면 오픈 프록시가 됩니다)
    ProxyRequests Off

    ProxyPass        /api/ http://127.0.0.1:8080/api/
    ProxyPassReverse /api/ http://127.0.0.1:8080/api/

    # 실제 IP 전달
    RequestHeader set X-Forwarded-Proto "http"
    RequestHeader set X-Real-IP "expr=%{REMOTE_ADDR}"

    # 정적 파일은 프록시하지 않음
    ProxyPass /static/ !
    Alias /static/ /var/www/static/

    ProxyTimeout 60
</VirtualHost>

로드 밸런싱

<Proxy balancer://mycluster>
    BalancerMember http://10.0.1.11:8080 loadfactor=3
    BalancerMember http://10.0.1.12:8080
    # H = 대기(핫 스탠바이)
    BalancerMember http://10.0.1.13:8080 status=+H

    # bytraffic · bybusyness 도 있음
    ProxySet lbmethod=byrequests
</Proxy>

ProxyPass        / balancer://mycluster/
ProxyPassReverse / balancer://mycluster/

# 관리 화면 (내부에서만 접근 가능하게)
<Location /balancer-manager>
    SetHandler balancer-manager
    Require ip 10.0.0.0/8
</Location>

AJP — Tomcat 전용 프로토콜

# sudo a2enmod proxy_ajp
ProxyPass        /app/ ajp://127.0.0.1:8009/app/
ProxyPassReverse /app/ ajp://127.0.0.1:8009/app/

# SSLStaplingCache 는 VirtualHost 안에 둘 수 없습니다 — 서버 전역(바깥)에 한 번
# ※ Let's Encrypt 는 2025년에 OCSP 를 종료해 LE 인증서에는 스테이플링이 동작하지 않습니다
SSLStaplingCache "shmcb:logs/ssl_stapling(32768)"

<VirtualHost *:443>
    ServerName example.com
    DocumentRoot /var/www/example

    SSLEngine on
    SSLCertificateFile      /etc/letsencrypt/live/example.com/fullchain.pem
    SSLCertificateKeyFile   /etc/letsencrypt/live/example.com/privkey.pem
    # 2.4.8 미만에서는 체인을 따로 지정했습니다
    # SSLCertificateChainFile /etc/letsencrypt/live/example.com/chain.pem

    SSLProtocol             -all +TLSv1.2 +TLSv1.3
    SSLHonorCipherOrder     off
    SSLCipherSuite          ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384

    SSLUseStapling on

    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>

# HTTP → HTTPS
<VirtualHost *:80>
    ServerName example.com
    Redirect permanent / https://example.com/
</VirtualHost>

# certbot 이 Apache 설정까지 자동으로 해 줍니다
sudo apt install -y certbot python3-certbot-apache
sudo certbot --apache -d example.com -d www.example.com

# 인증서만 받고 설정은 직접
sudo certbot certonly --apache -d example.com

Nginx 와 지시어 대응 — 이름만 다릅니다

HTTPS 가 안 될 때 — 증상별

# 인증서 체인을 밖에서 확인 — 가장 확실한 방법
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>&1 \
  | grep -E "subject=|issuer=|Verify return code"

# 만료일
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null \
  | openssl x509 -noout -dates

# 자동 갱신이 실제로 도는지 (실행하지 않고 예행)
sudo certbot renew --dry-run

# 갱신 후 자동 reload — 이 훅이 없으면 인증서는 새것인데 서비스는 옛것을 씁니다
sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-apache.sh <<'EOF'
#!/bin/sh
systemctl reload apache2
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-apache.sh

# 비밀번호 파일 만들기 (문서 루트 밖에 두세요)
sudo htpasswd -c /etc/apache2/.htpasswd admin      # -c 는 최초 1회만
sudo htpasswd /etc/apache2/.htpasswd user2         # 추가

<Location /admin>
    AuthType Basic
    AuthName "Restricted Area"
    AuthUserFile /etc/apache2/.htpasswd
    Require valid-user
</Location>

# IP 제한
<Location /internal>
    Require ip 10.0.0.0/8
    Require ip 203.0.113.5
</Location>

# IP 또는 인증 (둘 중 하나만 통과하면 됨)
<Location /admin>
    <RequireAny>
        Require ip 10.0.0.0/8
        Require valid-user
    </RequireAny>
</Location>

# IP 이면서 인증 (둘 다 필요)
<Location /danger>
    <RequireAll>
        Require ip 10.0.0.0/8
        Require valid-user
    </RequireAll>
</Location>

2.2 → 2.4 접근 제어 문법 변환

Require 지시어 — 쓸 수 있는 조건들

# 실전 조합 — 사내 IP 는 그냥, 밖에서는 인증을 요구
<Location /admin>
    AuthType Basic
    AuthName "Admin"
    AuthUserFile /etc/apache2/.htpasswd
    <RequireAny>
        Require ip 10.0.0.0/8
        Require valid-user
    </RequireAny>
</Location>

# 프록시 뒤에 있으면 remote_addr 이 LB IP 입니다 — 실제 IP 를 복원해야 합니다
# sudo a2enmod remoteip
RemoteIPHeader X-Forwarded-For
# ★ 신뢰할 프록시만 지정
RemoteIPTrustedProxy 10.0.0.0/8
# %a 가 실제 IP
LogFormat "%a %l %u %t \"%r\" %>s %O" combined_realip

# 민감 파일 차단 — 정적 사이트에 항상 넣으세요
<FilesMatch "^\.|\.(bak|sql|env|log|swp)$">
    Require all denied
</FilesMatch>
<DirectoryMatch "/\.git">
    Require all denied
</DirectoryMatch>

# 서버 상태 페이지 — 로컬에서만 (진단에 매우 유용합니다)
# sudo a2enmod status
<Location /server-status>
    SetHandler server-status
    Require local
</Location>
ExtendedStatus On

# sudo a2enmod deflate expires headers

# ── 압축
<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css
    AddOutputFilterByType DEFLATE application/javascript application/json
    AddOutputFilterByType DEFLATE application/xml image/svg+xml

    DeflateCompressionLevel 5

    # 이미 압축된 것은 제외
    SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png|webp|zip|gz|mp4)$ no-gzip dont-vary
</IfModule>

# ── 캐시 헤더
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType image/jpeg      "access plus 1 month"
    ExpiresByType image/png       "access plus 1 month"
    ExpiresByType image/svg+xml   "access plus 1 month"
    ExpiresByType text/css        "access plus 1 year"
    ExpiresByType application/javascript "access plus 1 year"
    ExpiresByType text/html       "access plus 0 seconds"
</IfModule>

# 해시가 붙은 파일은 영구 캐시
<FilesMatch "\.[0-9a-f]{8,}\.(js|css)$">
    Header set Cache-Control "public, max-age=31536000, immutable"
</FilesMatch>

# index.html 은 매번 재검증 (no-cache — 아래 설명 참고)
<Files "index.html">
    Header set Cache-Control "no-cache"
</Files>

보안 헤더도 여기서

<IfModule mod_headers.c>
    Header always set X-Content-Type-Options "nosniff"
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set Referrer-Policy "strict-origin-when-cross-origin"
    Header always set Permissions-Policy "geolocation=(), microphone=(), camera=()"
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"

    # 서버 정보 제거
    Header unset X-Powered-By
    # Server 헤더는 mod_headers 로 지울 수 없습니다 — ServerTokens Prod 로 "Apache" 만 남깁니다
</IfModule>

brotli 를 함께 쓰기 — deflate 보다 20~25% 더 줄어듭니다

# sudo a2enmod brotli
<IfModule mod_brotli.c>
    AddOutputFilterByType BROTLI_COMPRESS text/html text/plain text/css
    AddOutputFilterByType BROTLI_COMPRESS application/javascript application/json
    AddOutputFilterByType BROTLI_COMPRESS image/svg+xml

    # 5 가 속도·압축률 균형점 (mod_brotli 기본값도 5 · 11 은 실시간으로는 너무 느립니다)
    BrotliCompressionQuality 5
    BrotliCompressionWindow  18
</IfModule>

# ★ 사전 압축 파일을 쓰면 CPU 를 아예 안 씁니다 (빌드 때 만들어 두세요)
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{HTTP:Accept-Encoding} br
    RewriteCond %{REQUEST_FILENAME}.br -f
    RewriteRule ^(.*)$ $1.br [L]

    <FilesMatch "\.js\.br$">
        Header set Content-Encoding br
        Header append Vary Accept-Encoding
        ForceType application/javascript
    </FilesMatch>
    <FilesMatch "\.css\.br$">
        Header set Content-Encoding br
        Header append Vary Accept-Encoding
        ForceType text/css
    </FilesMatch>
</IfModule>

캐시 헤더 — 정확히 어떤 값을 줄 것인가

# 실제로 어떤 헤더가 나가는지 확인 — 설정만 보고 판단하지 마세요
curl -sI https://example.com/assets/app.a1b2c3d4.js \
  | grep -iE "cache-control|content-encoding|vary|etag"

# 압축이 실제로 적용됐는지 (크기 비교)
curl -s -o /dev/null -w "raw  %{size_download}\n" https://example.com/app.js
curl -s -o /dev/null -w "gzip %{size_download}\n" -H "Accept-Encoding: gzip" https://example.com/app.js
curl -s -o /dev/null -w "br   %{size_download}\n" -H "Accept-Encoding: br"   https://example.com/app.js

# 오류 응답에도 보안 헤더가 붙는지 (always 확인)
curl -sI https://example.com/없는경로 | grep -i "x-frame\|strict-transport"

# 로그 포맷 정의
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %D" combined_time
# %D = 처리 시간(마이크로초) ← 성능 분석에 필수

CustomLog ${APACHE_LOG_DIR}/access.log combined_time
ErrorLog  ${APACHE_LOG_DIR}/error.log

# 평상시
LogLevel warn
# LogLevel info rewrite:trace3    # rewrite 디버깅 시 (운영에서는 끄세요)
# LogLevel debug proxy:trace5     # 프록시 디버깅

# 특정 요청은 로그에서 제외
SetEnvIf Request_URI "^/health$" dontlog
SetEnvIf Request_URI "\.(css|js|png|jpg|svg)$" dontlog
CustomLog ${APACHE_LOG_DIR}/access.log combined_time env=!dontlog

# 상태 코드 집계
awk '{print $9}' /var/log/apache2/access.log | sort | uniq -c | sort -rn

# 가장 느린 요청 (마지막 필드가 %D 일 때)
awk '{print $NF, $7}' /var/log/apache2/access.log | sort -rn | head -20

# 실시간 오류만
sudo tail -f /var/log/apache2/error.log | grep -E '\[[a-z0-9_]*:(error|crit|alert|emerg)\]'   # 2.4 형식: [모듈:레벨]

서버 상태 페이지

# sudo a2enmod status
ExtendedStatus On
<Location /server-status>
    SetHandler server-status
    Require ip 127.0.0.1
    # ★ 반드시 제한하세요
    Require ip 10.0.0.0/8
</Location>

# curl http://localhost/server-status?auto

언제 무엇을

· 요청을 받고 응답을 보냄
· 정적 파일을 디스크에서 읽어 전달
· HTTPS · 압축 · 캐시 · 로드밸런싱
· 자바 코드는 실행하지 못함

· 자바 서블릿·JSP 를 실행
· 요청마다 스레드를 배정해 코드 실행
· 세션 · 트랜잭션 · 커넥션 풀 관리
· 정적 파일도 줄 수는 있지만 비효율

서블릿 컨테이너란

자바에는 서블릿(Servlet)이라는 표준 규격이 있습니다. "HTTP 요청을 받으면 이런 형태의 객체로 전달하고, 이런 형태로 응답을 돌려준다"는 약속입니다. Tomcat 은 이 규격을 구현한 프로그램이고, Spring 은 그 위에서 도는 프레임워크입니다.

# 자바 먼저 (Tomcat 11 은 Java 17 이상)
sudo apt install -y openjdk-21-jdk
java -version

# 톰캣 내려받기
cd /opt
sudo curl -LO https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.x/bin/apache-tomcat-11.0.x.tar.gz
sudo tar xzf apache-tomcat-11.0.x.tar.gz
sudo mv apache-tomcat-11.0.x tomcat

# 전용 계정 (★ root 로 실행하지 마세요)
sudo useradd -r -s /bin/false tomcat
sudo chown -R tomcat:tomcat /opt/tomcat

# 실행
sudo -u tomcat /opt/tomcat/bin/startup.sh
curl -I http://localhost:8080
sudo -u tomcat /opt/tomcat/bin/shutdown.sh

systemd 서비스로 등록

# /etc/systemd/system/tomcat.service
[Unit]
Description=Apache Tomcat 11
After=network.target

[Service]
Type=forking
User=tomcat
Group=tomcat

Environment="JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64"
Environment="CATALINA_HOME=/opt/tomcat"
Environment="CATALINA_BASE=/opt/tomcat"
Environment="CATALINA_PID=/opt/tomcat/temp/tomcat.pid"
Environment="CATALINA_OPTS=-Xms512m -Xmx1024m -XX:+UseG1GC"

ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh

Restart=on-failure
RestartSec=10
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now tomcat
sudo journalctl -u tomcat -f

<Server port="8005" shutdown="SHUTDOWN">          <!-- 종료 명령을 받는 포트 -->

  <Service name="Catalina">

    <!-- 요청을 받는 창구 -->
    <Connector port="8080"
               protocol="org.apache.coyote.http11.Http11NioProtocol"
               connectionTimeout="20000"
               maxThreads="200"
               minSpareThreads="10"
               acceptCount="100"
               maxConnections="8192"
               URIEncoding="UTF-8"
               compression="off"
               redirectPort="8443" />

    <Engine name="Catalina" defaultHost="localhost">

      <Host name="localhost" appBase="webapps"
            unpackWARs="true" autoDeploy="true">

        <!-- 접근 로그 -->
        <Valve className="org.apache.catalina.valves.AccessLogValve"
               directory="logs" prefix="localhost_access_log"
               suffix=".txt"
               pattern="%h %l %u %t &quot;%r&quot; %s %b %D" />

        <!-- 프록시 뒤에서 실제 IP 복원 -->
        <Valve className="org.apache.catalina.valves.RemoteIpValve"
               remoteIpHeader="X-Forwarded-For"
               protocolHeader="X-Forwarded-Proto"
               internalProxies="127\.0\.0\.1|10\.\d+\.\d+\.\d+" />

      </Host>
    </Engine>
  </Service>
</Server>

프로토콜 구현체

<!-- 프록시 뒤에 있을 때의 권장 설정
     (XML 은 태그 안에 주석을 넣을 수 없으므로 설명은 여기에 모읍니다)
     · address="127.0.0.1"   ★ 외부에서 직접 접근 차단
     · keepAliveTimeout      ★ Nginx 업스트림 keepalive_timeout(기본 60s) 보다 길게
     · compression="off"     압축은 Nginx 가 담당
     · enableLookups="false" ★ DNS 역조회 끄기 (성능)
     · server="server"       서버 정보 숨김
     · proxyName·proxyPort   앞단 도메인 -->
<Connector port="8080"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           address="127.0.0.1"
           maxThreads="200"
           acceptCount="200"
           connectionTimeout="20000"
           keepAliveTimeout="65000"
           maxHttpHeaderSize="16384"
           URIEncoding="UTF-8"
           compression="off"
           enableLookups="false"
           server="server"
           proxyName="example.com"
           proxyPort="443"
           scheme="https"
           secure="true" />

프록시 뒤에 둘 때 꼭 맞춰야 하는 값

<!-- server.xml 의 <Host> 안 — 실제 클라이언트 IP 를 복원합니다 -->
<Valve className="org.apache.catalina.valves.RemoteIpValve"
       remoteIpHeader="X-Forwarded-For"
       protocolHeader="X-Forwarded-Proto"
       internalProxies="127\.0\.0\.1|10\.\d+\.\d+\.\d+" />
<!-- ★ internalProxies 를 반드시 지정하세요.
     안 하면 클라이언트가 X-Forwarded-For 를 위조해
     IP 기반 접근 제어를 헤더 한 줄로 우회할 수 있습니다. -->

# Spring Boot 내장 톰캣이면 설정 파일 한 곳에서 끝납니다
server.address=127.0.0.1
server.port=8080
server.tomcat.threads.max=200
server.tomcat.accept-count=200
server.tomcat.max-connections=8192
server.tomcat.connection-timeout=20s
# ★ Nginx keepalive_timeout(60s) 보다 길게
server.tomcat.keep-alive-timeout=65s
server.tomcat.max-http-form-post-size=10MB
server.max-http-request-header-size=16KB

# 프록시 헤더 신뢰 — 이 한 줄이면 RemoteIpValve 가 자동 등록됩니다
server.forward-headers-strategy=native
server.tomcat.remoteip.internal-proxies=127\\.0\\.0\\.1|10\\.\\d+\\.\\d+\\.\\d+

# 접근 로그 (기본 꺼져 있습니다 — 켜 두세요)
server.tomcat.accesslog.enabled=true
server.tomcat.accesslog.pattern=%h %l %u %t "%r" %s %b %D
#   %D = 처리 시간(Tomcat 10+ 는 마이크로초 · 9 이하는 ms) ★ 이게 없으면 "어느 요청이 느린가"를 못 봅니다

# 배포
sudo cp myapp.war /opt/tomcat/webapps/
# → /opt/tomcat/webapps/myapp/ 로 자동 압축 해제
# → 접속 주소: http://localhost:8080/myapp

# 루트 경로(/)로 배포하려면 파일 이름을 ROOT.war 로
sudo cp myapp.war /opt/tomcat/webapps/ROOT.war

# 제거 — WAR 를 지우면 폴더도 함께 삭제됩니다
sudo rm /opt/tomcat/webapps/myapp.war

경로를 직접 지정하기 — context 파일

<!-- conf/Catalina/localhost/myapp.xml -->
<!-- 파일 이름이 곧 컨텍스트 경로가 됩니다 -->
<Context docBase="/opt/apps/myapp" reloadable="false">

  <!-- 앱에서 쓸 DB 커넥션 풀 -->
  <Resource name="jdbc/mydb"
            auth="Container"
            type="javax.sql.DataSource"
            driverClassName="org.postgresql.Driver"
            url="jdbc:postgresql://db:5432/shop"
            username="app"
            password="${DB_PASSWORD}"
            maxTotal="20" maxIdle="10" maxWaitMillis="3000"
            validationQuery="SELECT 1" testOnBorrow="true" />
</Context>

배포 방식 비교

# application.properties — 내장 톰캣 설정
server.port=8080
# ★ 프록시 뒤라면 로컬만
server.address=127.0.0.1

# 스레드 풀
server.tomcat.threads.max=200
server.tomcat.threads.min-spare=20
server.tomcat.accept-count=200
server.tomcat.max-connections=8192

# 타임아웃
server.tomcat.connection-timeout=20s
# Nginx 업스트림 keepalive_timeout(기본 60s) 보다 길게 — 짧으면 간헐적 502 (t04)
server.tomcat.keep-alive-timeout=65s

# 프록시 뒤에서 실제 IP·프로토콜 인식 (★ 매우 중요)
server.forward-headers-strategy=native
server.tomcat.remoteip.remote-ip-header=X-Forwarded-For
server.tomcat.remoteip.protocol-header=X-Forwarded-Proto
server.tomcat.remoteip.internal-proxies=127\\.0\\.0\\.1|10\\.\\d+\\.\\d+\\.\\d+

# 접근 로그
server.tomcat.accesslog.enabled=true
server.tomcat.accesslog.directory=/var/log/myapp
server.tomcat.accesslog.pattern=%h %l %u %t "%r" %s %b %D

# 업로드 크기
spring.servlet.multipart.max-file-size=50MB
spring.servlet.multipart.max-request-size=50MB

# 우아한 종료 (무중단 배포에 필수)
server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=30s

# 오류 응답에서 정보 노출 줄이기
server.error.include-stacktrace=never
server.error.include-message=never

실행 방식

# 기본
java -jar myapp.jar

# JVM 옵션과 함께 (운영 권장)
#   -Xmx 와 -XX:MaxRAMPercentage 를 같이 주면 -Xmx 가 이깁니다 — 컨테이너라면 비율 하나만 (t10)
java -Xms512m -Xmx1g \
     -XX:+UseG1GC \
     -Dspring.profiles.active=prod \
     -Dfile.encoding=UTF-8 \
     -jar myapp.jar

# 환경 변수로 설정 주입 (설정 파일에 비밀번호를 넣지 마세요)
export SPRING_DATASOURCE_PASSWORD='...'
java -jar myapp.jar

# /etc/systemd/system/myapp.service
[Unit]
Description=My Spring Boot App
After=network.target

[Service]
User=appuser
WorkingDirectory=/opt/myapp
Environment="JAVA_OPTS=-Xms512m -Xmx1g -XX:+UseG1GC"
# 비밀은 이 파일에 (권한 600)
EnvironmentFile=/etc/myapp/env
ExecStart=/usr/bin/java $JAVA_OPTS -jar /opt/myapp/myapp.jar
# SIGTERM 종료를 정상으로 취급
SuccessExitStatus=143
Restart=on-failure
RestartSec=10
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

페이지 하나 = HTML 1 + CSS 2 + JS 3 + 이미지 20
            = 요청 26개

톰캣 스레드 200개로
동시 사용자 8명이면 이미 포화

느린 모바일 사용자 한 명이
스레드를 수 초간 붙잡습니다

Nginx  : 이미지·CSS·JS 25개 처리 (매우 빠름)
Tomcat : HTML(API) 1개만 처리

톰캣 스레드 200개로
동시 사용자 200명 처리 가능

+ 캐시 헤더로 재요청 자체를 없앰

server {
    listen 443 ssl;
    server_name example.com;

    # 정적 자원 — Nginx 가 직접
    location ^~ /static/ {
        alias /opt/myapp/static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    location ^~ /uploads/ {
        alias /var/data/uploads/;
        expires 30d;
        add_header Content-Disposition "attachment";   # 브라우저 실행 방지
    }

    location = /favicon.ico { alias /opt/myapp/static/favicon.ico; access_log off; }

    # 나머지는 톰캣으로
    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 $scheme;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

X-Accel-Redirect — 권한은 앱이, 전송은 Nginx 가

// 앱은 권한만 확인하고 "이 파일을 보내라"고 지시만 합니다 — 전송은 안 합니다
@GetMapping("/files/{id}")
public ResponseEntity<Void> download(@PathVariable Long id, @LoginUser Member me) {

    Attachment att = attachmentService.findAccessible(id, me);   // 권한 검사

    return ResponseEntity.ok()
        // ★ Nginx 만 이해하는 내부 경로 — 브라우저에는 안 나갑니다
        .header("X-Accel-Redirect", "/protected/" + att.storedName())
        .header(HttpHeaders.CONTENT_DISPOSITION,
                ContentDisposition.attachment()
                    .filename(att.originalName(), StandardCharsets.UTF_8).build().toString())
        .header(HttpHeaders.CONTENT_TYPE, att.contentType())
        .build();   // ★ 본문 없음 — 스레드가 즉시 반납됩니다
}

location /protected/ {
    internal;                       # ★ 외부에서 직접 접근 불가 — 앱을 거쳐야만
    alias /var/data/uploads/;
    sendfile on;
    sendfile_max_chunk 512k;        # 큰 파일이 워커를 독점하지 않게
}

Spring Boot 정적 자원을 밖으로 빼는 실전

# 방법 ① 빌드 산출물에서 정적 파일만 뽑아 배포
./gradlew bootJar
mkdir -p /opt/myapp/static
unzip -o build/libs/app.jar 'BOOT-INF/classes/static/*' -d /tmp/x
cp -r /tmp/x/BOOT-INF/classes/static/* /opt/myapp/static/
#   → Nginx 의 location ^~ /static/ 이 이 폴더를 직접 서빙합니다

# 방법 ② 프런트엔드를 완전히 분리 (권장)
#   프런트: Vite·Next 빌드 → dist/ → Nginx 또는 CDN
#   백엔드: API 만 담당 → 톰캣은 JSON 만 만듭니다
#   장점: 배포 주기 분리 · 캐시 전략 분리 · 톰캣 부하 최소

# 톰캣이 정적 파일을 아예 안 다루게 하기 (API 전용 서버라면)
spring.web.resources.add-mappings=false
#   → 없는 경로가 404 로 명확히 떨어집니다.
#     기본값 true 면 정적 리소스를 찾느라 불필요한 파일 시스템 접근이 생기고,
#     API 오타가 404 대신 index.html(200) 로 응답되는 혼란도 사라집니다.

<!-- 톰캣 세션 복제 (참고용 — 실무에서는 잘 안 씁니다) -->
<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
         channelSendOptions="8">
  <Manager className="org.apache.catalina.ha.session.DeltaManager"
           expireSessionsOnShutdown="false"
           notifyListenersOnReplication="true"/>
  ...
</Cluster>
<!-- web.xml 에 <distributable/> 도 필요하고,
     세션에 담는 객체가 전부 Serializable 이어야 합니다 -->

권장 — Spring Session + Redis

# 의존성: spring-session-data-redis — 의존성만 있으면 자동 구성됩니다
# (spring.session.store-type 속성은 Spring Boot 3.0 에서 삭제됐습니다)
spring.session.timeout=30m
spring.session.redis.namespace=myapp:session

spring.data.redis.host=redis.internal
spring.data.redis.port=6379
spring.data.redis.password=${REDIS_PASSWORD}

# 그래도 sticky session 이 필요하다면 (Nginx)
upstream tomcat {
    ip_hash;                      # IP 기반 고정 (모바일에서 불안정)
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
}

# 또는 쿠키 기반 (Nginx Plus 또는 서드파티 모듈 필요)
# sticky cookie srv_id expires=1h;

산정하는 법

필요한 스레드 수 ≈ 목표 RPS × 평균 응답 시간(초)

예) 목표 500 RPS · 평균 응답 0.2초
    → 500 × 0.2 = 100 스레드

여기에 여유 1.5~2배 → maxThreads = 150~200

※ 응답 시간이 대부분 'DB 대기'라면
   스레드를 늘려도 DB 커넥션이 병목이라 효과가 없습니다
   → DB 커넥션 풀과 함께 조정해야 합니다

# Spring Boot
server.tomcat.threads.max=200
server.tomcat.threads.min-spare=20
# 스레드가 다 차면 여기에 대기
server.tomcat.accept-count=200
server.tomcat.max-connections=8192

# DB 커넥션 풀과 균형을 맞추세요
spring.datasource.hikari.maximum-pool-size=20

가상 스레드 Java 21+

# Spring Boot 3.2+ · Java 21+
spring.threads.virtual.enabled=true

# 요청마다 가상 스레드를 만들어 처리합니다
# · 블로킹 IO 대기 중에는 OS 스레드를 반납 → 수만 동시 요청 가능
# · maxThreads 제약에서 사실상 자유로워집니다

스레드 풀과 DB 풀을 함께 맞추기

# ① 지금 스레드가 몇 개 쓰이고 있나 (JMX)
jcmd <pid> ManagementAgent.status
# Spring Boot Actuator 를 쓰면 훨씬 간단합니다
curl -s localhost:8081/actuator/metrics/tomcat.threads.busy
curl -s localhost:8081/actuator/metrics/tomcat.threads.config.max
curl -s localhost:8081/actuator/metrics/hikaricp.connections.pending   # ★ 이게 핵심

# ② 스레드가 어디서 막혀 있나 — 튜닝 전에 반드시
jcmd <pid> Thread.print > dump.txt
grep -c 'java.lang.Thread.State: BLOCKED'       dump.txt   # 락 경합
grep -c 'java.lang.Thread.State: WAITING'       dump.txt   # 외부 대기
grep -A3 '"http-nio-8080-exec' dump.txt | grep -o 'at [a-z.]*' | sort | uniq -c | sort -rn | head
#   → 톰캣 워커 스레드들이 공통으로 멈춰 있는 지점이 곧 병목입니다

# ③ 30초 간격으로 3번 떠서 비교하면 "계속 같은 곳"인지 알 수 있습니다

# 기본 옵션
#   -Xms1g -Xmx1g                  초기·최대 힙 (같게 잡으면 리사이징 비용 없음)
#   -XX:+UseG1GC                   Java 9+ 기본
#   -XX:+HeapDumpOnOutOfMemoryError ★ OOM 시 힙 덤프 저장
#   (줄 끝 \ 뒤에는 주석을 붙일 수 없어 설명을 위로 모았습니다)
java -Xms1g -Xmx1g \
     -XX:+UseG1GC \
     -XX:MaxGCPauseMillis=200 \
     -XX:+HeapDumpOnOutOfMemoryError \
     -XX:HeapDumpPath=/var/log/myapp/ \
     -Xlog:gc*:file=/var/log/myapp/gc.log:time,uptime:filecount=5,filesize=10M \
     -jar myapp.jar

컨테이너 메모리 배분

컨테이너 메모리 2GB 일 때

  힙 (Xmx)              1.4GB   (70%)
  메타스페이스           ~200MB   (클래스 정보)
  스레드 스택            ~200MB   (200 스레드 × 1MB)
  다이렉트 버퍼·코드 캐시 ~150MB
  여유                   ~50MB
  ────────────────────────────
  합계                   2GB

★ 힙만 보고 2GB 를 다 주면 OOMKilled 가 납니다
  (컨테이너는 힙 밖 메모리도 함께 셉니다)

# 실제 힙 사용량 확인
jcmd <pid> GC.heap_info
jstat -gc <pid> 1000 10        # 1초 간격 10회

# 힙 덤프 (OOM 분석용)
jcmd <pid> GC.heap_dump /tmp/heap.hprof
jmap -dump:live,format=b,file=/tmp/heap.hprof <pid>

# JVM 이 인식한 컨테이너 자원 확인
java -XX:+PrintFlagsFinal -version | grep -E 'MaxHeapSize|ActiveProcessorCount'

# /etc/logrotate.d/tomcat — catalina.out 로테이션
/opt/tomcat/logs/catalina.out {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    # ★ 톰캣을 재시작하지 않고 잘라냅니다
    copytruncate
    su tomcat tomcat
}

접근 로그

<Valve className="org.apache.catalina.valves.AccessLogValve"
       directory="logs"
       prefix="access" suffix=".log"
       pattern="%h %l %u %t &quot;%r&quot; %s %b %D &quot;%{User-Agent}i&quot; %{X-Request-Id}i"
       rotatable="true"
       maxDays="30" />
<!-- %D = 처리 시간(Tomcat 10+ 는 마이크로초) · %{헤더}i = 요청 헤더 -->

Spring Boot 라면 로그백으로

<!-- logback-spring.xml -->
<configuration>
  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>/var/log/myapp/app.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
      <fileNamePattern>/var/log/myapp/app.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
      <maxFileSize>100MB</maxFileSize>
      <maxHistory>30</maxHistory>
      <totalSizeCap>5GB</totalSizeCap>
    </rollingPolicy>
    <encoder>
      <pattern>%d{ISO8601} [%thread] %-5level %logger{36} [%X{traceId}] - %msg%n</pattern>
    </encoder>
  </appender>
  <root level="INFO"><appender-ref ref="FILE"/></root>
</configuration>

# /etc/nginx/sites-available/myapp
upstream tomcat {
    server 127.0.0.1:8080;
    keepalive 32;                     # ★ 연결 재사용
}

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

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

    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;

    # 보안 헤더
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;

    # 업로드 크기
    client_max_body_size 50m;

    # 정적 자원
    location ^~ /static/ {
        alias /opt/myapp/static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # 헬스체크 (로그 제외)
    location = /actuator/health {
        proxy_pass http://tomcat;
        access_log off;
    }

    # 관리 엔드포인트는 내부에서만
    location ^~ /actuator/ {
        allow 10.0.0.0/8;
        deny all;
        proxy_pass http://tomcat;
    }

    # 애플리케이션
    location / {
        proxy_pass http://tomcat;

        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-Forwarded-Port  $server_port;

        proxy_http_version 1.1;
        proxy_set_header Connection "";

        proxy_connect_timeout 5s;
        proxy_read_timeout   60s;
        proxy_send_timeout   60s;
    }
}

# 톰캣(Spring Boot) 쪽 — 프록시를 인식하게
server.address=127.0.0.1
server.port=8080
server.forward-headers-strategy=native

# Actuator 는 별도 포트로 빼는 것도 좋은 방법입니다
# ※ 이렇게 빼면 위 Nginx 의 /actuator/ location 은 http://127.0.0.1:8081 로 보내야 합니다
#   (8080 의 tomcat 업스트림으로 보내면 404)
management.server.port=8081
management.server.address=127.0.0.1
management.endpoints.web.exposure.include=health,info,metrics,prometheus

# Spring Boot — 프록시 뒤에 있을 때 반드시
server.forward-headers-strategy=native

# 쿠키에 Secure 플래그 (HTTPS 에서만 전송)
server.servlet.session.cookie.secure=true
server.servlet.session.cookie.http-only=true
server.servlet.session.cookie.same-site=lax

<!-- 순수 톰캣이라면 RemoteIpValve -->
<Valve className="org.apache.catalina.valves.RemoteIpValve"
       remoteIpHeader="X-Forwarded-For"
       protocolHeader="X-Forwarded-Proto"
       protocolHeaderHttpsValue="https"
       internalProxies="127\.0\.0\.1|10\.\d+\.\d+\.\d+|172\.1[6-9]\.\d+\.\d+" />
<!-- 이 밸브가 request.isSecure() 와 getRemoteAddr() 을 올바르게 만들어 줍니다 -->

톰캣에 직접 HTTPS 를 붙여야 한다면

# Let's Encrypt 인증서를 자바 키스토어(PKCS12)로 변환
sudo openssl pkcs12 -export \
  -in  /etc/letsencrypt/live/example.com/fullchain.pem \
  -inkey /etc/letsencrypt/live/example.com/privkey.pem \
  -out /opt/tomcat/conf/keystore.p12 \
  -name tomcat -passout pass:changeit

# Spring Boot
server.port=8443
server.ssl.key-store=/opt/myapp/keystore.p12
server.ssl.key-store-type=PKCS12
server.ssl.key-store-password=${KEYSTORE_PASSWORD}
server.ssl.key-alias=tomcat
server.ssl.enabled-protocols=TLSv1.2,TLSv1.3

① 우아한 종료 (Graceful Shutdown)

# Spring Boot 2.3+
server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=30s

# 동작
# 1) SIGTERM 을 받으면 새 요청 수신을 중단
# 2) 처리 중인 요청을 최대 30초까지 기다림
# 3) 그 후 종료

② LB 에서 먼저 빼기 (드레인)

#!/usr/bin/env bash
set -euo pipefail

# 1) 헬스체크를 실패시켜 LB 가 이 서버를 제외하게 합니다
curl -fsS -X POST http://127.0.0.1:8081/actuator/shutdown-prepare || true
#    (또는 파일 플래그를 두고 헬스 엔드포인트가 그것을 보게 합니다)

# 2) LB 가 인지할 시간을 줍니다 (헬스체크 주기 × 실패 임계값)
sleep 15

# 3) 이제 종료해도 새 요청이 오지 않습니다
sudo systemctl stop myapp

# 4) 새 버전 배포 후 기동
sudo cp myapp-new.jar /opt/myapp/myapp.jar
sudo systemctl start myapp

# 5) 준비될 때까지 기다린 뒤 LB 에 복귀
until curl -fsS http://127.0.0.1:8081/actuator/health | grep -q '"UP"'; do sleep 2; done

③ 롤링 배포 (서버가 여러 대일 때)

# Nginx : 한 대씩 빼면서 배포합니다
upstream tomcat {
    server 10.0.1.11:8080 max_fails=2 fail_timeout=10s;
    server 10.0.1.12:8080 max_fails=2 fail_timeout=10s;
    server 10.0.1.13:8080 max_fails=2 fail_timeout=10s;
}

# 특정 서버를 잠시 제외하려면 down 을 붙이고 reload
#   server 10.0.1.11:8080 down;
# sudo nginx -s reload   (무중단)

① 기본 앱 제거 — 가장 먼저

cd /opt/tomcat/webapps
sudo rm -rf docs examples manager host-manager ROOT
# manager 는 원격 배포 기능이라 침해 시 서버를 통째로 넘겨줍니다
# examples 는 알려진 취약점이 여러 개 있습니다

② 종료 포트 차단

<!-- server.xml -->
<Server port="-1" shutdown="SHUTDOWN">
<!-- 또는 추측 불가능한 문자열 + 방화벽 차단 -->

③ 서버 정보 숨기기

<!-- server = Server 헤더 값 변경 (태그 안에는 주석을 넣을 수 없습니다) -->
<Connector port="8080" ...
           server="server"
           xpoweredBy="false" />

# 오류 페이지의 버전 표기까지 없애려면 ServerInfo.properties 를 덮어씁니다
cd /opt/tomcat/lib
mkdir -p org/apache/catalina/util
cat > org/apache/catalina/util/ServerInfo.properties <<'EOF'
server.info=Server
server.number=0.0.0.0
server.built=
EOF
jar uf catalina.jar org/apache/catalina/util/ServerInfo.properties

④ 오류 페이지 커스터마이징

<!-- conf/web.xml 또는 앱의 web.xml -->
<error-page>
    <error-code>404</error-code>
    <location>/error/404.html</location>
</error-page>
<error-page>
    <exception-type>java.lang.Throwable</exception-type>
    <location>/error/500.html</location>
</error-page>
<!-- 기본 오류 페이지는 스택 트레이스와 톰캣 버전을 그대로 노출합니다 -->

⑤ 그 밖의 점검 항목

스레드 덤프 — 어디서 멈췄나

# 프로세스 ID 찾기
jps -l
# 또는 ps aux | grep java

# 스레드 덤프 (3~5초 간격으로 3회 뜨는 것이 정석)
jstack <pid> > /tmp/dump1.txt
sleep 5; jstack <pid> > /tmp/dump2.txt
sleep 5; jstack <pid> > /tmp/dump3.txt

# 또는
jcmd <pid> Thread.print > /tmp/dump.txt

# 상태별 개수 세기
grep 'java.lang.Thread.State' /tmp/dump1.txt | sort | uniq -c

증상별 진단표

# CPU 를 많이 쓰는 스레드 찾기
top -H -p <pid>                       # TIME 이 큰 스레드의 PID 확인
printf '%x\n' <스레드PID>              # 16진수로 변환 → nid 값
grep -A 20 'nid=0x<16진수>' /tmp/dump.txt

# JFR 로 상세 프로파일링 (운영에서도 부하가 낮습니다)
jcmd <pid> JFR.start duration=60s filename=/tmp/rec.jfr
# JDK Mission Control 로 열어 봅니다

# 실시간 지표
jcmd <pid> VM.native_memory summary    # -XX:NativeMemoryTracking=summary 필요
jstat -gcutil <pid> 1000

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}
server {
    listen 443 ssl;
    http2 on;
    server_name example.com;

    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;

    root /var/www/html;
    index index.html;
}
# + certbot 설치 · 발급 · 갱신 타이머 설정

example.com {
    root * /var/www/html
    file_server
}

# 끝입니다.
# · 인증서 자동 발급
# · 자동 갱신
# · HTTP → HTTPS 리다이렉트 자동
# · HTTP/2 · HTTP/3 자동
# · 보안 기본값 적용

기본으로 켜져 있는 것들

• 자동 HTTPS — Let's Encrypt(또는 ZeroSSL)에서 발급·갱신
• HTTP → HTTPS 리다이렉트 — 별도 설정 없이
• HTTP/2 · HTTP/3 — 기본 활성화
• 안전한 TLS 기본값 — 취약한 프로토콜·암호가 처음부터 비활성
• OCSP 스테이플링, 세션 재개

그럼에도 Nginx 가 여전히 주류인 이유

• 자료와 사례의 양 — 문제가 생겼을 때 검색 결과가 압도적으로 다릅니다
• 조직의 익숙함 — 운영팀이 아는 도구를 쓰는 것이 안전합니다
• 대규모 운영 사례 — 초대형 트래픽 환경의 검증 사례가 Nginx 쪽이 훨씬 많습니다
• 플러그인 방식 — Caddy 는 기능을 추가하려면 재빌드가 필요합니다
• 세밀한 제어 — Nginx 가 제공하는 저수준 튜닝 옵션이 더 많습니다

# ── Ubuntu · Debian (공식 저장소)
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install -y caddy

# ── 바이너리 직접 (어떤 리눅스에서든)
curl -fsSL "https://caddyserver.com/api/download?os=linux&arch=amd64" -o caddy
chmod +x caddy && sudo mv caddy /usr/local/bin/

# ── macOS
brew install caddy

# ── Docker
docker run -d -p 80:80 -p 443:443 -p 443:443/udp \
  -v caddy_data:/data -v caddy_config:/config \
  -v $PWD/Caddyfile:/etc/caddy/Caddyfile:ro \
  caddy:2.10

# 즉석 실행 (개발용)
caddy file-server --root ./public --listen :8080
caddy reverse-proxy --from :8080 --to 127.0.0.1:3000

# 설정 파일로 실행
caddy run --config /etc/caddy/Caddyfile
caddy start                          # 백그라운드
caddy stop

# 서비스로 (apt 설치 시 자동 등록됨)
sudo systemctl enable --now caddy
sudo systemctl reload caddy          # 무중단 반영

# 설정 검증·정리
caddy validate --config /etc/caddy/Caddyfile
caddy fmt --overwrite /etc/caddy/Caddyfile

발급이 안 될 때 — 원인 순서대로

# 개발·테스트 중에는 스테이징 CA 로 — 발급 한도가 사실상 없습니다
{
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
    email admin@example.com
}

# 내부망·사설 도메인 — Caddy 내부 CA 로 자체 서명
intranet.local {
    tls internal
    reverse_proxy 127.0.0.1:3000
}

# 80 번 포트를 열 수 없는 환경 → DNS 챌린지 (와일드카드도 이 방식만 가능)
# ※ DNS 제공자 플러그인이 포함된 빌드가 필요합니다
#   xcaddy build --with github.com/caddy-dns/cloudflare
*.example.com {
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
    reverse_proxy 127.0.0.1:3000
}

# 전역 옵션 (파일 맨 위에 한 번)
{
    email admin@example.com          # 인증서 만료 알림을 받을 주소
    admin off                        # 관리 API 끄기 — 단, caddy reload·systemctl reload 도 안 됩니다(재시작으로 반영)
    servers {
        protocols h1 h2 h3
    }
}

# 사이트 블록
example.com {
    root * /var/www/html
    file_server
    encode gzip zstd

    handle /api/* {
        reverse_proxy 127.0.0.1:3000
    }

    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options nosniff
        -Server                      # 헤더 제거는 앞에 -
    }

    log {
        output file /var/log/caddy/example.log
        format json
    }
}

# 여러 도메인
a.example.com, b.example.com {
    respond "Hello"
}

# HTTP 만 (인증서 발급 안 함)
http://internal.local {
    reverse_proxy 127.0.0.1:8080
}

# SPA 배포 — 이 세 줄이면 됩니다
example.com {
    root * /var/www/spa
    try_files {path} /index.html
    file_server
}

example.com {
    # 가장 단순한 형태 — X-Forwarded-* 헤더가 자동으로 붙습니다
    reverse_proxy 127.0.0.1:3000
}

# 여러 서버 = 자동 로드 밸런싱
example.com {
    reverse_proxy 10.0.1.11:3000 10.0.1.12:3000 10.0.1.13:3000 {
        lb_policy least_conn          # random(기본) · round_robin · ip_hash · first

        health_uri      /health       # ★ 능동적 헬스체크가 기본 기능입니다
        health_interval 10s
        health_timeout  3s
        health_status   2xx

        fail_duration   30s           # 실패한 서버를 제외할 시간
        max_fails       3

        transport http {
            keepalive 30s
            keepalive_idle_conns 32
            dial_timeout 5s
            read_timeout 60s
        }
    }
}

경로별 라우팅

example.com {
    # 정적 프런트엔드
    handle /static/* {
        root * /var/www
        file_server
        header Cache-Control "public, max-age=31536000, immutable"
    }

    # API — 접두사를 떼고 넘김 (/api/users → /users)
    handle_path /api/* {
        reverse_proxy 127.0.0.1:8080
    }

    # 웹소켓 (별도 설정이 필요 없습니다 — 자동 처리)
    handle /ws/* {
        reverse_proxy 127.0.0.1:3000
    }

    # 나머지는 SPA
    handle {
        root * /var/www/spa
        try_files {path} /index.html
        file_server
    }
}

# 프록시 세부 조정
reverse_proxy 127.0.0.1:3000 {
    header_up   X-Real-IP {remote_host}
    header_up   Host {upstream_hostport}
    header_down -Server                    # 백엔드가 보낸 Server 헤더 제거

    flush_interval -1                      # SSE·스트리밍 (버퍼링 끄기)
}

Nginx 설정을 Caddy 로 — 대응표

실전에서 자주 쓰는 프록시 설정

example.com {
    # ── 1) 큰 파일 업로드 (기본 제한 없음 — 오히려 제한을 걸어야 합니다)
    request_body {
        max_size 50MB
    }

    # ── 2) 속도 제한이 필요하면 (플러그인)
    #   xcaddy build --with github.com/mholt/caddy-ratelimit

    # ── 3) 특정 경로만 인증 걸기
    @admin path /admin/*
    basic_auth @admin {
        # caddy hash-password 로 만든 bcrypt 해시
        alice $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
    }

    # ── 4) 백엔드가 죽었을 때 보여 줄 페이지
    handle_errors {
        @502 expression {err.status_code} == 502
        rewrite @502 /maintenance.html
        root * /var/www/static
        file_server
    }

    # ── 5) 요청이 실제로 어디로 갔는지 디버깅
    #   Caddyfile 맨 위 전역 블록에
    #   { debug }
    #   → 매처 판정과 라우팅 결정이 로그에 전부 찍힙니다

    reverse_proxy 127.0.0.1:3000 {
        # 백엔드가 느릴 때 — 기본은 무제한이라 반드시 잡아 주세요
        transport http {
            dial_timeout     5s
            response_header_timeout 30s
            read_timeout     300s      # SSE·스트리밍이면 길게
        }

        # 실패 시 다음 서버로 재시도
        lb_try_duration 5s
        lb_try_interval 250ms
    }
}

# 로그에서 발급 과정을 확인
sudo journalctl -u caddy -f | grep -i -E 'certificate|acme|challenge'

# 테스트 중이라면 스테이징 서버를 쓰세요 (발급 한도가 훨씬 넉넉합니다)
# Caddyfile 전역 옵션에
# {
#     acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
# }
# ※ 스테이징 인증서는 브라우저에서 신뢰되지 않습니다 (경고가 뜹니다)

DNS 챌린지 — 와일드카드·내부 서버용

# *.example.com 같은 와일드카드는 DNS 챌린지만 가능합니다
# DNS 제공자 플러그인이 포함된 빌드가 필요합니다
# xcaddy build --with github.com/caddy-dns/cloudflare

*.example.com {
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
    reverse_proxy 127.0.0.1:3000
}

# 직접 준비한 인증서를 쓰려면
example.com {
    tls /etc/ssl/certs/example.crt /etc/ssl/private/example.key
}

# 내부 CA (개발·사내용 자체 서명)
internal.local {
    tls internal
}

# 인증서 관리를 아예 끄기 — Caddy 2 에는 tls off 가 없습니다
# 주소 앞에 http:// 를 붙이면 그 사이트는 HTTP 로만 서비스합니다
# (전부 끄려면 전역 옵션 { auto_https off })
http://example.com {
    respond "HTTP only"
}

# 지금 폴더를 즉시 서빙 (개발용)
caddy file-server --listen :8080 --browse

# --browse 를 주면 디렉터리 목록도 보여 줍니다 (운영에서는 쓰지 마세요)

example.com {
    root * /var/www/site
    file_server
    encode gzip zstd

    # 정적 자원 캐시
    @static {
        path *.css *.js *.woff2 *.png *.jpg *.svg *.webp
    }
    header @static Cache-Control "public, max-age=31536000, immutable"

    # index.html 은 매번 재검증 (no-cache — 아래 SPA 설명 참고)
    @html path /index.html /
    header @html Cache-Control "no-cache"

    # 커스텀 오류 페이지
    handle_errors {
        rewrite * /{err.status_code}.html
        file_server
    }
}

# 매처 예시
@admin {
    path /admin/*
    not remote_ip 10.0.0.0/8
}
respond @admin "Forbidden" 403

@post method POST
@api header Content-Type application/json
@mobile header User-Agent *Mobile*

# 여러 조건은 AND · 하나라도 만족하려면 별도 매처를 여러 개

사전 압축 파일 사용

example.com {
    root * /var/www/site
    file_server {
        precompressed br gzip        # app.js.br · app.js.gz 가 있으면 그것을 전송
    }
}

SPA 를 제대로 서빙하기 — 캐시 전략이 핵심입니다

example.com {
    root * /var/www/spa
    encode zstd gzip

    # ① 해시가 붙은 자원 — 영원히 캐시 (파일명이 바뀌면 새로 받습니다)
    @hashed path_regexp \.[a-f0-9]{8,}\.(js|css|woff2|png|jpg|svg|webp)$
    header @hashed Cache-Control "public, max-age=31536000, immutable"

    # ② index.html — 절대 캐시 금지
    #    이것을 캐시하면 배포해도 사용자가 옛 버전을 계속 봅니다
    @index path / /index.html
    header @index Cache-Control "no-cache, must-revalidate"

    # ③ 그 외 정적 파일 — 짧게
    @asset path /assets/*
    header @asset Cache-Control "public, max-age=3600"

    # ④ API 는 프록시로
    handle_path /api/* {
        reverse_proxy 127.0.0.1:8080
    }

    # ⑤ 나머지 경로는 전부 index.html (클라이언트 라우팅)
    handle {
        try_files {path} /index.html
        file_server
    }
}

파일 서버에서 조심할 것

# 숨김 파일·민감 경로 차단 — 정적 서버에 항상 넣으세요
@hidden {
    path /.git/* /.env* /.htaccess *.bak *.swp *.sql
}
respond @hidden 404

# 또는 file_server 의 hide 옵션
file_server {
    hide .git .env *.bak
}

example.com {
    header {
        # 보안 헤더
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options    "nosniff"
        X-Frame-Options           "SAMEORIGIN"
        Referrer-Policy           "strict-origin-when-cross-origin"
        Permissions-Policy        "geolocation=(), microphone=(), camera=()"
        Content-Security-Policy   "default-src 'self'; img-src 'self' data:; frame-ancestors 'self'"

        # 서버 정보 제거
        -Server
        -X-Powered-By
    }

    encode {
        zstd
        gzip 5
        minimum_length 1024
        match {
            header Content-Type text/*
            header Content-Type application/json*
            header Content-Type application/javascript*
            header Content-Type image/svg+xml*
        }
    }
}

(security) {
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options nosniff
        X-Frame-Options SAMEORIGIN
        -Server
    }
}

(compress) {
    encode gzip zstd
}

a.example.com {
    import security
    import compress
    reverse_proxy 127.0.0.1:3000
}

b.example.com {
    import security
    import compress
    root * /var/www/b
    file_server
}

로그

example.com {
    log {
        output file /var/log/caddy/access.log {
            roll_size     100MiB
            roll_keep     10
            roll_keep_for 720h
        }
        format json
        level  INFO
    }

    # 특정 경로는 로그에서 제외
    @health path /health
    log_skip @health
}

보안 헤더 — 무엇이 무엇을 막나

# CSP 를 실제로 적용하는 순서 — 한 번에 켜면 사이트가 깨집니다
# ① 먼저 리포트 전용으로 (차단하지 않고 위반만 수집)
header Content-Security-Policy-Report-Only "default-src 'self'; report-uri /csp-report"

# ② 며칠간 리포트를 보고 필요한 출처를 추가
# ③ 위반이 사라지면 Report-Only 를 떼고 실제 적용
header Content-Security-Policy "
    default-src 'self';
    script-src  'self' https://cdn.example.com;
    style-src   'self' 'unsafe-inline';
    img-src     'self' data: https:;
    connect-src 'self' https://api.example.com wss://api.example.com;
    frame-ancestors 'none';
    base-uri 'self';
    form-action 'self'
"

압축 — 무엇을 압축하고 무엇을 하지 말아야 하나

# compose.yaml
services:
  caddy:
    image: caddy:2.10
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"          # ★ HTTP/3 용
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./site:/srv:ro
      - caddy_data:/data       # ★★ 인증서 — 반드시 볼륨으로
      - caddy_config:/config
    depends_on:
      - app

  app:
    build: ./app
    restart: unless-stopped
    expose:
      - "3000"                 # 외부에 열지 않고 caddy 만 접근

volumes:
  caddy_data:
  caddy_config:

# Caddyfile — 컨테이너 이름이 곧 호스트명
example.com {
    handle_path /api/* {
        reverse_proxy app:3000
    }
    handle {
        root * /srv
        try_files {path} /index.html
        file_server
    }
}

# 무중단 설정 반영
docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile

# 설정 검증
docker compose exec caddy caddy validate --config /etc/caddy/Caddyfile

# 로그
docker compose logs -f caddy

# 발급된 인증서 확인
docker compose exec caddy ls -R /data/caddy/certificates

컨테이너에서 자주 막히는 것

# 앞에 CDN·로드밸런서가 있을 때 — 실제 클라이언트 IP 를 살립니다
{
    servers {
        trusted_proxies static 10.0.0.0/8 172.16.0.0/12   # LB 대역만 신뢰
        client_ip_headers X-Forwarded-For
    }
}

example.com {
    # 이제 {client_ip} 가 실제 사용자 IP 입니다
    log {
        format json
    }
    reverse_proxy app:3000 {
        header_up X-Real-IP {client_ip}
    }
}

운영에 넣어 두면 좋은 것

services:
  caddy:
    image: caddy:2.10
    restart: unless-stopped
    ports: ["80:80", "443:443", "443:443/udp"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
      - ./logs:/var/log/caddy          # 로그를 호스트로 빼 두면 조사에 편합니다
    healthcheck:                        # ★ 프록시 자신도 헬스체크 대상입니다
      test: ["CMD", "wget", "-qO-", "http://localhost:2019/config/"]
      interval: 30s
      timeout: 5s
      retries: 3
    logging:                            # 컨테이너 로그가 디스크를 채우지 않게
      driver: json-file
      options: { max-size: "20m", max-file: "5" }
    ulimits:
      nofile: { soft: 65535, hard: 65535 }   # 동시 연결이 많으면 필수

volumes:
  caddy_data:
  caddy_config:

# 관리 API — 재시작 없이 설정을 읽고 바꿀 수 있습니다 (기본 2019 포트, 로컬만)
curl -s localhost:2019/config/ | jq          # 현재 설정 전체
curl -s localhost:2019/reverse_proxy/upstreams | jq   # 업스트림 상태·헬스

# 인증서 파일의 갱신 시각 — 자동 갱신이 잘 돌고 있는지 가끔 봐 두세요
docker compose exec caddy sh -c \
  'ls -l /data/caddy/certificates/*/*/*.crt' 2>/dev/null

# 밖에서 실제로 확인하는 것이 가장 확실합니다
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null \
  | openssl x509 -noout -dates -issuer

# Caddyfile 이 실제로 어떤 JSON 이 되는지 확인
caddy adapt --config /etc/caddy/Caddyfile --pretty

# 관리 API (기본 localhost:2019)
curl localhost:2019/config/ | jq            # 현재 설정 조회
curl localhost:2019/config/apps/http/servers/srv0/routes | jq

# 설정을 API 로 교체 (무중단)
curl -X POST localhost:2019/load \
     -H "Content-Type: application/json" \
     -d @caddy.json

플러그인 — xcaddy 로 재빌드

# xcaddy 설치 (Go 필요)
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

# 필요한 플러그인을 넣어 빌드
xcaddy build \
  --with github.com/caddy-dns/cloudflare \
  --with github.com/greenpau/caddy-security \
  --with github.com/mholt/caddy-ratelimit

sudo mv caddy /usr/local/bin/caddy
caddy list-modules | grep -i cloudflare

# Dockerfile — 플러그인 포함 이미지 만들기
FROM caddy:2.10-builder AS builder
RUN xcaddy build --with github.com/caddy-dns/cloudflare

FROM caddy:2.10
COPY --from=builder /usr/bin/caddy /usr/bin/caddy

HTTPS 가 필수인 실질적 이유

• 브라우저 경고 — HTTP 폼에 입력하면 "안전하지 않음" 경고가 뜹니다
• HTTP/2 · HTTP/3 — 사실상 HTTPS 에서만 동작합니다
• 브라우저 API 제한 — 위치·카메라·서비스워커·클립보드 등이 보안 컨텍스트에서만 동작합니다
• 검색 순위 — 검색엔진이 HTTPS 를 순위 요소로 반영합니다
• 쿠키 보안 속성 — Secure·SameSite=None 이 HTTPS 를 요구합니다

HTTP 로 두면 실제로 무엇이 막히나

# 실제 핸드셰이크 관찰
openssl s_client -connect example.com:443 -servername example.com < /dev/null

# 협상된 프로토콜·암호만 확인
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null \
  | grep -E 'Protocol|Cipher'

# TLS 단계별 소요 시간
curl -w "tls:%{time_appconnect}s connect:%{time_connect}s total:%{time_total}s\n" \
     -o /dev/null -s https://example.com

핸드셰이크에서 나는 오류 — 증상별

# ① 체인이 완전한지 — 가장 먼저 확인할 것
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>&1 \
  | grep -A20 "Certificate chain"
# 서버 인증서 → 중간 인증서까지 나와야 정상입니다 (루트는 안 보내도 됩니다)

# ② 검증 결과
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>&1 \
  | grep "Verify return code"
# "0 (ok)" 가 아니면 문제입니다

# ③ 중간 인증서 없이도 되는지 시험 (엄격 검증)
openssl s_client -connect example.com:443 -servername example.com \
  -verify_return_error -CApath /etc/ssl/certs < /dev/null

# ④ 협상 결과 — 프로토콜과 암호
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null \
  | grep -E "Protocol|Cipher|Server Temp Key"

# ⑤ 어느 단계가 느린지 숫자로
curl -w "dns:%{time_namelookup} tcp:%{time_connect} tls:%{time_appconnect} \
ttfb:%{time_starttransfer} total:%{time_total}\n" -o /dev/null -s https://example.com
# tls - tcp 가 핸드셰이크 시간입니다. 100ms 를 크게 넘으면 OCSP 를 의심하세요.

신뢰 체인

루트 CA (브라우저·OS에 미리 내장)
      │ 서명
      ▼
중간 CA (Let's Encrypt R11 등)   ← chain.pem
      │ 서명
      ▼
내 서버 인증서 (example.com)      ← cert.pem

브라우저는 이 체인을 위로 따라가
'내가 아는 루트'에 닿아야 신뢰합니다.
중간 인증서가 빠지면 체인이 끊깁니다.

인증서 종류

# 인증서 내용 확인
openssl x509 -in fullchain.pem -noout -text | head -30
openssl x509 -in fullchain.pem -noout -subject -issuer -dates
openssl x509 -in fullchain.pem -noout -ext subjectAltName    # 포함된 도메인 목록

# 개인키와 인증서가 짝이 맞는지 (해시가 같아야 합니다)
#   공개키를 비교하므로 RSA·ECDSA 모두 됩니다 (certbot 2.0+ 기본 키는 ECDSA 라 -modulus 는 실패)
openssl x509 -noout -pubkey -in fullchain.pem | openssl md5
openssl pkey -pubout        -in privkey.pem   | openssl md5

# 설치
sudo apt install -y certbot python3-certbot-nginx      # Nginx 플러그인
sudo apt install -y python3-certbot-apache             # Apache 플러그인

# ── 방법 ① 웹서버 설정까지 자동으로 (가장 쉬움)
sudo certbot --nginx -d example.com -d www.example.com

# ── 방법 ② 인증서만 받고 설정은 직접
sudo certbot certonly --nginx -d example.com

# ── 방법 ③ 웹서버를 잠시 멈추고 (standalone)
sudo certbot certonly --standalone -d example.com

# ── 방법 ④ 실행 중인 서버의 문서 루트를 이용 (무중단)
sudo certbot certonly --webroot -w /var/www/html -d example.com

# ── 방법 ⑤ DNS 챌린지 (와일드카드·포트를 못 여는 경우)
sudo certbot certonly --manual --preferred-challenges dns -d '*.example.com'
# 안내에 따라 DNS 에 TXT 레코드를 추가해야 합니다

# webroot 방식을 쓰려면 이 location 이 열려 있어야 합니다
server {
    listen 80;
    server_name example.com;

    location ^~ /.well-known/acme-challenge/ {
        root /var/www/certbot;
        allow all;                        # ★ 인증 없이 접근 가능해야 합니다
    }

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

# 발급된 인증서 확인
sudo certbot certificates
sudo ls -l /etc/letsencrypt/live/example.com/

# 도메인 추가·변경 (기존 인증서를 확장)
sudo certbot --nginx -d example.com -d www.example.com -d api.example.com --expand

# 인증서 폐기·삭제
sudo certbot revoke --cert-path /etc/letsencrypt/live/example.com/cert.pem
sudo certbot delete --cert-name example.com

STEP 0 — 준비물 점검

# Nginx 가 떠 있나
systemctl status nginx --no-pager | head -3

# 80·443 포트가 열려 있나 (ufw 기준)
sudo ufw status | grep -E '80|443'
sudo ufw allow 'Nginx Full'                 # 안 열려 있으면

# 클라우드(AWS·GCP 등)라면 보안 그룹에서도 80·443 인바운드를 열어야 합니다
# 내 서버의 공인 IP 확인
curl -4 -s ifconfig.me; echo

STEP 1 — DNS 연결과 전파 확인

도메인 관리 콘솔(가비아·후이즈·Cloudflare·Route 53 등)에서 A 레코드를 추가합니다: example.com → 서버 공인 IP, 필요하면 www 도 함께.

# 도메인이 내 서버 IP 를 가리키는지 (STEP 0 의 IP 와 같아야 합니다)
dig +short example.com
dig +short www.example.com

# 아직 예전 값이 나오면 TTL 만큼 기다립니다 (보통 수분~1시간)
# 여러 지역에서의 전파 상태는 dnschecker.org 에서 확인할 수 있습니다

STEP 2 — HTTP 서버 블록 준비

# /etc/nginx/sites-available/example.com
server {
    listen 80;
    server_name example.com www.example.com;   # ★ 발급받을 도메인과 정확히 일치

    root /var/www/example.com;
    index index.html;
}

sudo mkdir -p /var/www/example.com
echo '<h1>It works</h1>' | sudo tee /var/www/example.com/index.html

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# 확인 — HTTP 로 접속되는지 (여기까지가 HTTPS 이전의 마지막 모습입니다)
curl -I http://example.com

STEP 3 — 발급 + 자동 설정 (핵심 한 줄)

sudo apt install -y certbot python3-certbot-nginx

# 이 한 줄이 ①발급 ②443 블록 생성 ③인증서 지정 ④HTTP→HTTPS 리다이렉트까지 합니다
sudo certbot --nginx -d example.com -d www.example.com

# 처음 실행하면 이메일(만료 경고 수신용)과 약관 동의를 묻습니다
# "Congratulations!" 가 나오면 성공입니다

STEP 4 — 적용 확인

# ① HTTPS 응답 확인
curl -I https://example.com

# ② HTTP → HTTPS 리다이렉트 확인 (301 + Location: https:// 가 나와야 합니다)
curl -I http://example.com

# ③ 체인이 완전한지 (0 과 1 두 개가 보여야 정상 — s08)
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null \
  | grep -A 5 'Certificate chain'

# ④ 모바일 실기기 브라우저에서도 한 번 열어 보세요 (PC 는 체인 문제를 감춰 줍니다)
# ⑤ ssllabs.com/ssltest 에서 등급 확인 — A 이상이면 합격

STEP 5 — 자동 갱신 확인 (빠뜨리면 90일 뒤 장애)

# 갱신 타이머가 걸려 있나
systemctl list-timers | grep certbot

# 갱신 리허설 — 전 과정을 실제 발급 없이 검증합니다
sudo certbot renew --dry-run
# "Congratulations, all simulated renewals succeeded" 가 나오면 완료입니다

# 패키지로 설치하면 타이머가 이미 등록돼 있습니다
systemctl list-timers | grep certbot
sudo systemctl status certbot.timer

# 갱신 테스트 (실제로 갱신하지 않고 전 과정을 검증)
sudo certbot renew --dry-run

# 수동 갱신 (만료 30일 이내인 것만 실제로 갱신됩니다)
sudo certbot renew

# 강제 갱신 (테스트 외에는 쓰지 마세요 — 발급 한도 소모)
sudo certbot renew --force-renewal

# 갱신 성공 시 자동으로 실행될 훅
sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-web.sh <<'EOF'
#!/usr/bin/env bash
set -e
systemctl reload nginx    || true
systemctl reload apache2  || true
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-web.sh

직접 타이머를 만든다면

# /etc/systemd/system/certbot-renew.service
[Unit]
Description=Certbot renewal
[Service]
Type=oneshot
ExecStart=/usr/bin/certbot renew --quiet --deploy-hook "systemctl reload nginx"

# /etc/systemd/system/certbot-renew.timer
[Unit]
Description=Run certbot twice daily
[Timer]
OnCalendar=*-*-* 03,15:00:00
# ★ 서버가 많으면 분산 (CA 부하 방지)
RandomizedDelaySec=3600
Persistent=true
[Install]
WantedBy=timers.target

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

    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;
}
# sudo nginx -t && sudo systemctl reload nginx

<VirtualHost *:443>
    ServerName example.com
    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
    SSLProtocol -all +TLSv1.2 +TLSv1.3
</VirtualHost>
# sudo apachectl configtest && sudo systemctl reload apache2

# PEM → PKCS12 변환이 필요합니다
openssl pkcs12 -export \
  -in  /etc/letsencrypt/live/example.com/fullchain.pem \
  -inkey /etc/letsencrypt/live/example.com/privkey.pem \
  -out keystore.p12 -name tomcat \
  -passout pass:changeit

# application.properties
# server.ssl.key-store=/opt/app/keystore.p12
# server.ssl.key-store-type=PKCS12
# server.ssl.key-alias=tomcat

example.com {
    # 아무것도 안 써도 자동 발급·갱신됩니다

    # 직접 준비한 인증서를 쓰려면
    # tls /path/cert.pem /path/key.pem
}

여러 도메인 · SNI

# 한 IP 에서 여러 도메인에 각각 다른 인증서
server {
    listen 443 ssl;
    server_name a.example.com;
    ssl_certificate     /etc/letsencrypt/live/a.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/a.example.com/privkey.pem;
}
server {
    listen 443 ssl;
    server_name b.example.com;
    ssl_certificate     /etc/letsencrypt/live/b.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/b.example.com/privkey.pem;
}
# SNI 덕분에 가능합니다 — 클라이언트가 핸드셰이크에서 도메인을 알려 주기 때문입니다

ssl_certificate /etc/letsencrypt/live/x/cert.pem;

# 서버가 보내는 것: [내 인증서] 만
# 브라우저: "이걸 서명한 중간 CA 를 모르겠는데?"
#
# PC 브라우저는 캐시나 AIA fetch 로
# 중간 인증서를 알아서 구해 오는 경우가 있어
# 문제를 못 느낍니다 (그래서 발견이 늦습니다)

ssl_certificate /etc/letsencrypt/live/x/fullchain.pem;

# 서버가 보내는 것:
#   [내 인증서] + [중간 CA 인증서]
#
# 모든 클라이언트가 체인을 완성할 수 있습니다

# 체인이 제대로 나가는지 확인
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null \
  | grep -A 5 'Certificate chain'

순서도 중요합니다

fullchain.pem 의 올바른 순서

-----BEGIN CERTIFICATE-----   ← ① 서버 인증서 (내 도메인)
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----   ← ② 중간 CA
...
-----END CERTIFICATE-----

★ 순서가 뒤바뀌면 일부 클라이언트가 거부합니다
★ 루트 CA 는 넣지 않아도 됩니다 (클라이언트가 이미 갖고 있음)
  넣어도 동작하지만 전송량만 늘어납니다

# Nginx — 권장 설정 (현대적 호환성)
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;         # TLS1.3 에서는 클라이언트 우선이 권장됩니다
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;

# 세션 재개 (재접속 지연 감소)
ssl_session_cache   shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;               # 티켓 키 관리가 어렵다면 끄는 편이 안전

# OCSP 스테이플링 (인증서 폐기 확인을 서버가 대신)
# ※ OCSP 주소가 있는 인증서에만 해당 — Let's Encrypt 는 2025년 OCSP 종료 (s02)
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
resolver 1.1.1.1 8.8.8.8 valid=300s;
resolver_timeout 5s;

알아 둘 개념

• 전방 비밀성 (Forward Secrecy) — 개인키가 나중에 유출돼도 과거 트래픽을 복호화할 수 없게 하는 성질. ECDHE 로 시작하는 암호가 이를 제공합니다
• AEAD — 암호화와 무결성 검증을 함께 하는 방식(GCM·CHACHA20-POLY1305). TLS 1.3 은 AEAD 만 씁니다
• ECDSA vs RSA — ECDSA 인증서가 더 작고 빠릅니다. 둘 다 발급해 클라이언트에 맞게 제공할 수도 있습니다

# 우리 서버가 어떤 프로토콜·암호를 지원하는지 점검
nmap --script ssl-enum-ciphers -p 443 example.com

# 특정 버전만 시도해 보기
openssl s_client -connect example.com:443 -tls1_2 < /dev/null
openssl s_client -connect example.com:443 -tls1_1 < /dev/null   # 실패해야 정상

HSTS — 브라우저에게 HTTPS 를 강제

# Nginx
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

# preload 목록에 등록하려면 (아래 경고를 반드시 읽으세요)
# add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

혼합 콘텐츠 (Mixed Content)

HTTPS 페이지 안에서 HTTP 리소스를 불러오면 브라우저가 차단하거나 경고합니다. 이미지·스크립트·CSS·폰트가 모두 대상입니다.

<!-- ✗ 차단됨 -->
<script src="http://cdn.example.com/lib.js"></script>

<!-- ✓ 명시적 HTTPS -->
<script src="https://cdn.example.com/lib.js"></script>

<!-- ✓ 프로토콜 상대 경로 (현재는 그냥 https 를 쓰는 편이 낫습니다) -->
<script src="//cdn.example.com/lib.js"></script>

# 임시 대응 — 브라우저에게 HTTP 요청을 HTTPS 로 바꿔 달라고 요청
add_header Content-Security-Policy "upgrade-insecure-requests" always;
# 근본 해결은 코드에서 URL 을 고치는 것입니다

# Nginx — 클라이언트 인증서 요구
server {
    listen 443 ssl;
    server_name api-internal.example.com;

    ssl_certificate     /etc/ssl/server.crt;
    ssl_certificate_key /etc/ssl/server.key;

    # 클라이언트 인증서 검증
    ssl_client_certificate /etc/ssl/ca.crt;      # 클라이언트를 서명한 CA
    ssl_verify_client on;                        # on · optional · off
    ssl_verify_depth 2;

    location / {
        # 검증 결과를 앱에 전달
        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
        proxy_set_header X-SSL-Client-DN     $ssl_client_s_dn;
        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;

        proxy_pass http://backend;
    }
}

# 사설 CA 와 클라이언트 인증서 만들기
# 1) CA 키·인증서
openssl req -x509 -newkey rsa:4096 -days 3650 -nodes \
  -keyout ca.key -out ca.crt -subj "/CN=Internal CA"

# 2) 클라이언트 키·CSR
openssl req -newkey rsa:2048 -nodes \
  -keyout client.key -out client.csr -subj "/CN=service-a"

# 3) CA 로 서명
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out client.crt -days 365

# 4) 사용
curl --cert client.crt --key client.key https://api-internal.example.com/

일반 TLS 와 무엇이 다른가

# 경로별로 다르게 — API 만 mTLS, 문서는 공개
server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate     /etc/ssl/server.crt;
    ssl_certificate_key /etc/ssl/server.key;

    ssl_client_certificate /etc/ssl/ca.crt;
    ssl_verify_client optional;              # ★ 요구하되 거부하지는 않음

    # 공개 문서 — 인증서 없어도 통과
    location /docs/ {
        root /var/www;
    }

    # API — 검증 성공한 경우만
    location /v1/ {
        if ($ssl_client_verify != SUCCESS) { return 403; }

        # Nginx 에는 CN 만 주는 변수가 없습니다 — DN 전체를 넘기고 앱에서 CN 을 꺼내세요
        proxy_set_header X-Client-DN     $ssl_client_s_dn;
        proxy_set_header X-Client-Serial $ssl_client_serial;
        proxy_set_header X-Client-Verify $ssl_client_verify;
        proxy_pass http://backend;
    }
}

# 폐기 목록(CRL) — 인증서를 무효화하는 유일한 수단입니다
openssl ca -config ca.cnf -revoke client.crt          # 폐기 기록
openssl ca -config ca.cnf -gencrl -out crl.pem        # 목록 재생성

# Nginx 에 적용 (재생성할 때마다 reload 필요)
#   ssl_crl /etc/ssl/crl.pem;

# 클라이언트 인증서 정보 확인
openssl x509 -in client.crt -noout -subject -dates -serial

# 실제로 되는지 시험
curl --cert client.crt --key client.key https://api.example.com/v1/ping
curl https://api.example.com/v1/ping        # ← 403 이 나와야 정상 (optional 블록)

# 남은 일수 확인 (한 줄)
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null \
  | openssl x509 -noout -enddate

# 파일에서 확인
openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -enddate

# 30일 이내면 실패로 처리 (모니터링·CI 에 붙이기 좋습니다)
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null \
  | openssl x509 -noout -checkend $((30*86400)) \
  && echo "OK: 30일 이상 남음" || echo "WARNING: 30일 이내 만료"

#!/usr/bin/env bash
# 여러 도메인을 한 번에 점검하는 스크립트
DOMAINS=(example.com api.example.com admin.example.com)
WARN_DAYS=21

for d in "${DOMAINS[@]}"; do
  end=$(echo | openssl s_client -connect "$d:443" -servername "$d" 2>/dev/null \
        | openssl x509 -noout -enddate 2>/dev/null | cut -d= -f2)
  if [ -z "$end" ]; then
    echo "ERROR  $d : 인증서를 가져오지 못했습니다"
    continue
  fi
  left=$(( ( $(date -d "$end" +%s) - $(date +%s) ) / 86400 ))
  if   [ "$left" -lt 0  ];          then echo "EXPIRED $d : ${left}일"
  elif [ "$left" -lt $WARN_DAYS ];  then echo "WARN    $d : ${left}일 남음"
  else                                   echo "OK      $d : ${left}일 남음"
  fi
done

# Prometheus 알람 규칙
groups:
  - name: tls
    rules:
      - alert: TLSCertExpiringSoon
        expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 21
        for: 1h
        labels: { severity: warning }
        annotations:
          summary: "{{ $labels.instance }} 인증서가 {{ $value | printf \"%.0f\" }}일 뒤 만료"

      - alert: TLSCertExpiringCritical
        expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 7
        for: 10m
        labels: { severity: critical }

# ── 기본 확인
openssl s_client -connect example.com:443 -servername example.com < /dev/null

# 인증서 정보만
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

# 체인 전체
openssl s_client -connect example.com:443 -servername example.com -showcerts < /dev/null

# 협상 결과
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null \
  | grep -E 'Protocol|Cipher|Verify return code'

# ── 특정 버전으로 시도
openssl s_client -connect example.com:443 -tls1_3 < /dev/null
openssl s_client -connect example.com:443 -tls1_1 < /dev/null   # 실패해야 정상

# ── curl 로
curl -vI https://example.com 2>&1 | grep -E 'SSL|subject|issuer|expire'
curl --resolve example.com:443:1.2.3.4 -I https://example.com   # DNS 전환 전 테스트

# ── 지원 암호 전수 조사
nmap --script ssl-enum-ciphers -p 443 example.com

자주 만나는 오류