역방향 프록시 구성

~11 min · production, nginx, caddy

Level 0Poller

0 XP0/60 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

WebSocket 프록시는 기본 동작이 아니야

대부분의 HTTP/1.1 역방향 프록시는 기본적으로 Upgrade 헤더를 전달하지 않아. 그래서 WebSocket 핸드셰이크가 백엔드에 닿기도 전에 프록시에서 400 으로 실패해. 명시적으로 켜야 하고, 켠 뒤에는 유휴 시간 제한도 늘려 오래 유지되는 연결이 세션 중간에 끊기지 않게 해야 해.

Nginx 와 Caddy

Nginx 에서는 proxy_set_header Upgrade $http_upgrade 와 Connection $connection_upgrade 를 명시해야 해. Caddy 는 WebSocket 을 알아보고 자동으로 전달하므로 특별한 설정이 없어. 빠른 개념 검증에서는 Caddy 가 쓰기 편하고, Nginx 가 운영 기본값처럼 쓰이는 건 기능 차이보다 익숙함 때문이야.

Code

Nginx WebSocket 프록시 전체 설정·nginx

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

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

    ssl_certificate     /etc/ssl/example.com.crt;
    ssl_certificate_key /etc/ssl/example.com.key;

    location /ws {
        proxy_pass http://websocket_backend;
        proxy_http_version 1.1;

        # Forward upgrade headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # Standard headers
        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;

        # Long-lived connections need long timeouts
        proxy_read_timeout  3600s;
        proxy_send_timeout  3600s;

        # Disable buffering for streaming
        proxy_buffering off;
    }
}

Caddy — 같은 일을 10줄로·text

api.example.com {
    reverse_proxy /ws/* websocket_backend:8000
    # Caddy auto-handles Upgrade headers and TLS via Let's Encrypt.
}

External links

Nginx 블로그: WebSocket 프록시로 NGINX 사용

Exercise

FastAPI WebSocket 서버 앞에 Nginx 를 세우고 일부러 Upgrade 헤더를 빼 400 응답을 확인해. 다시 추가해 핸드셰이크가 성공하는지 봐. proxy_read_timeout 을 30초로 설정해 유휴 연결이 30초마다 끊기는 것을 확인한 뒤 3600초로 되돌려.

Progress

Progress is local-only — sign in to sync across devices.

← Previous수평 확장 Next →SSL/TLS 와 보안

이 페이지에서 버그를 발견하셨거나 피드백이 있으세요?문제 신고

🔔 답글 알림 (로그인 필요)

로그인 — 댓글을 남기려면 로그인해 주세요.

아직 댓글이 없어요. 첫 댓글을 남겨보세요.