Nginx 리버스 프록시 설정 완벽 가이드
Ubuntu 24.04 환경에서 Nginx 리버스 프록시를 구축하는 방법을 설명합니다. proxy_pass 설정부터 헤더 전달, 웹소켓 처리, 업로드 제한까지 필수 지시어를 한 줄씩 분석하여 안정적인 서버 운영을 돕습니다.
Nginx 리버스 프록시 설정의 역할
Nginx 리버스 프록시는 80번 및 443번 포트로 들어오는 요청을 받아 로컬 포트에서 대기 중인 애플리케이션으로 전달한 뒤, 애플리케이션의 응답을 브라우저로 반환합니다. 설정은 하나의 server 블록으로 구성되며, 이 블록은 매우 간결합니다. 설정의 핵심은 실제 클라이언트가 누구인지, 클라이언트가 어떤 프로토콜을 사용했는지 애플리케이션에 알리는 5~6줄의 설정에 있습니다.
아래의 모든 내용은 Ubuntu 24.04 환경에서 배포판의 nginx 패키지를 사용하여 처음부터 구축하는 과정을 다룹니다. 시작점은 이미 127.0.0.1:3000에서 응답하고 있는 애플리케이션입니다. 아직 프록시를 결정하지 않았다면, Nginx와 Caddy 및 Traefik 비교를 먼저 읽어보시기 바랍니다. 이어지는 내용은 Nginx 설정의 각 줄이 의미하는 바입니다.
이 설정들을 직접 서버에서 실행해 보십시오. 설정을 다시 불러오기(reload) 전에는 반드시 sudo nginx -t으로 변경 사항을 테스트하고 출력되는 내용을 확인하십시오.
Ubuntu에서 Nginx 설정 파일의 위치
sudo apt update
sudo apt install -y nginx
ls -l /etc/nginx/sites-enabled/메인 설정 파일은 /etc/nginx/nginx.conf입니다. 이 파일은 http { } 블록 내에서 전역 옵션을 설정한 뒤, /etc/nginx/conf.d/*.conf과 /etc/nginx/sites-enabled/* 두 디렉터리의 내용을 불러옵니다. Ubuntu와 Debian에서는 사이트별로 하나의 파일을 /etc/nginx/sites-available/에 작성하고, /etc/nginx/sites-enabled/로 심볼릭 링크를 생성하여 사이트를 활성화합니다. 심볼릭 링크를 삭제하면 사이트는 비활성화되지만 설정 파일은 그대로 유지됩니다.
이후에 사용될 두 지시어인 map와 upstream은 http 컨텍스트에서만 작동하며, server 블록 내부에서는 사용할 수 없습니다. 이 지시어들은 /etc/nginx/conf.d/ 아래의 별도 파일에 작성하십시오. 해당 디렉터리는 http 수준에서 포함되기 때문입니다.
패키지에는 default이라는 이름의 활성화된 사이트가 포함되어 있습니다. 이 사이트는 default_server로 표시되어 있는데, 이는 설정 내의 어떤 server_name와도 일치하지 않는 Host 헤더를 가진 모든 요청에 응답한다는 의미입니다. 이 사이트가 활성화되어 있으면, 사용자가 정의한 도메인과 일치하지 않는 요청은 애플리케이션이 아닌 이 사이트로 전달됩니다. 본인의 사이트가 정상적으로 작동하면 해당 심볼릭 링크를 삭제하십시오.
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx하나의 애플리케이션을 프록시하는 가장 작은 서버 블록
server {
listen 80;
listen [::]:80;
server_name app.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
}
}이 내용을 /etc/nginx/sites-available/app.example.com으로 저장한 다음, 활성화하고 로드합니다.
sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
curl -sI -H 'Host: app.example.com' http://127.0.0.1/listen 80;은 IPv4에 바인딩하고 listen [::]:80;는 IPv6에 바인딩합니다. 두 번째 줄을 생략하면 서버로 들어오는 모든 IPv6 연결이 거부됩니다. DNS(domain name system) 조회 결과로 AAAA 레코드를 반환하는 듀얼 스택 브라우저는 보통 IPv4로 폴백(fallback)하여 문제를 숨기지만, IPv6 전용 방문자나 처음 받은 주소로만 시도하는 클라이언트는 연결 거부를 경험하게 됩니다. 반면 IPv4 사용자는 사이트가 정상적으로 작동하므로, 전달받는 버그 리포트에는 "저는 잘 되는데요"라고 적히게 됩니다.
server_name은 브라우저가 전송하는 Host 헤더와 대조됩니다. 공백으로 구분하여 여러 이름을 나열할 수 있습니다. 일치하는 블록이 없으면 nginx는 default_server로 설정된 블록을 사용하므로, 패키지에 포함된 기본 사이트 설정을 제거해야 합니다.
location /은 요청 경로에 대한 접두사 일치 방식이며, /은 모든 경로와 일치합니다. proxy_pass은 nginx가 연결을 맺을 주소입니다. 애플리케이션을 127.0.0.1에 바인딩하여 nginx를 통해서만 접근할 수 있도록 유지하십시오. 애플리케이션이 컨테이너에서 실행 중이라면 3000:3000이 아닌 127.0.0.1:3000:3000으로 게시하십시오. Docker는 자체 규칙을 작성하여 ufw를 우회하고 포트를 직접 게시하기 때문에, ufw 설정과 관계없이 게시된 포트는 인터넷에서 직접 접근할 수 있습니다. Docker는 해당 트래픽을 필터링하는 위치로 DOCKER-USER 체인을 안내하지만, 127.0.0.1에 바인딩하는 것이 더 간단한 해결책입니다.
curl 줄은 서버 자체에서 올바른 Host 헤더를 전송하므로, DNS를 설정하기 전에 블록을 테스트할 수 있습니다.
별도의 설정이 없을 때 nginx가 업스트림으로 전달하는 내용
proxy_pass 설정만 단독으로 사용하면 애플리케이션에서 네 가지 정보가 가려집니다.
Ubuntu 24.04에서 제공하는 nginx 1.24.0 패키지는 기본적으로 백엔드와 HTTP/1.0으로 통신하며 Connection: close 헤더를 전송합니다. 따라서 모든 요청마다 새로운 업스트림 연결이 생성되며 프로토콜 업그레이드가 불가능합니다. 2026년 3월에 출시된 nginx 1.29.7 버전부터는 이러한 기본값이 변경되었습니다. 해당 버전 이후부터 nginx는 업스트림과 HTTP/1.1로 통신하고 Connection 헤더를 전송하지 않으며, 요청마다 연결을 새로 맺는 대신 풀링된 연결을 재사용합니다. 하지만 이 경우에도 WebSocket 업그레이드를 위해서는 아래에 명시된 헤더가 여전히 필요합니다.
Host 헤더는 proxy_pass의 값인 127.0.0.1:3000로 재작성됩니다. Host를 기반으로 절대 경로 링크를 생성하는 애플리케이션은 이제 외부에서 접근할 수 없는 링크를 생성하게 됩니다.
애플리케이션에 도달하는 연결은 nginx를 거치므로, 애플리케이션은 클라이언트 주소를 127.0.0.1으로 인식합니다. 이로 인해 애플리케이션 내부의 모든 로그와 속도 제한(rate limit) 설정은 방문자가 아닌 프록시 서버를 기록하게 됩니다.
애플리케이션은 루프백 주소에서 일반 HTTP 연결을 수신하므로, 브라우저가 HTTPS를 사용했는지 알 수 없습니다.
네 줄의 설정으로 이 모든 문제를 해결할 수 있습니다.
설정해야 할 4가지 헤더와 각 헤더가 백엔드에 제공하는 정보
location / {
proxy_pass http://127.0.0.1:3000;
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;
}Host는 방문자가 입력한 도메인 이름을 전달합니다. $host는 요청에서 포트 번호를 제거하고 소문자로 변환한 이름입니다. 이 헤더를 설정하면 애플리케이션이 올바른 절대 경로 URL을 생성할 수 있습니다. 로그인 후 리다이렉트나 비밀번호 재설정 이메일에 포함된 링크가 여기에 해당합니다. 이 헤더를 생략하면 애플리케이션은 127.0.0.1:3000을 자신의 이름으로 인식합니다. nginx의 기본값인 proxy_redirect은 proxy_pass 주소를 가리키는 Location 또는 Refresh 헤더를 재작성하므로, 일반적인 로그인 후 리다이렉트는 대개 올바르게 작동합니다. 하지만 애플리케이션이 페이지나 이메일에 작성하는 절대 경로 URL(예: 비밀번호 재설정 링크)은 방문자의 브라우저가 열 수 없는 주소인 127.0.0.1:3000을 가리키게 됩니다. 만약 8080 포트와 같이 특정 포트가 포함된 주소가 필요하다면, 클라이언트가 보낸 헤더를 그대로 사용하는 $http_host를 사용하십시오.
X-Real-IP은 단일 값을 전달합니다. $remote_addr는 nginx가 연결을 수락한 주소입니다. 애플리케이션은 자체 접근 로그 기록이나 속도 제한(rate limiting)을 위해 이 값을 읽습니다.
X-Forwarded-For는 목록을 전달합니다. $proxy_add_x_forwarded_for은 클라이언트가 이미 보낸 헤더 값 뒤에 $remote_addr을 추가하므로, 값은 쉼표로 구분되며 nginx가 추가한 항목이 마지막에 위치합니다. 이 세부 사항은 헤더의 신뢰 여부를 결정합니다. 클라이언트는 임의의 X-Forwarded-For을 보낼 수 있으므로, 첫 번째 항목을 읽는 애플리케이션은 잘못된 주소를 전달받을 수 있습니다. nginx가 엣지 서버인 경우 $remote_addr를 사용하여 클라이언트가 보낸 버전을 무시하십시오. CDN이나 다른 프록시가 앞단에 있는 경우 realip 모듈의 set_real_ip_from과 real_ip_header을 사용하여 $remote_addr 자체가 실제 클라이언트 주소가 되도록 설정하십시오.
X-Forwarded-Proto은 http 또는 https를 전달합니다. 프레임워크는 이 값을 읽어 쿠키를 Secure으로 표시할지 여부와 HTTPS로의 리다이렉트를 강제할지 여부를 결정합니다. TLS 사이트에서 이 헤더를 생략하면 HTTPS 강제 설정이 된 애플리케이션은 http을 보게 됩니다. 애플리케이션은 HTTPS 주소로 리다이렉트 응답을 보내고, nginx를 통해 다음 요청을 받지만 여전히 http로 인식하여 다시 리다이렉트를 수행합니다. 결과적으로 브라우저는 요청을 포기하고 ERR_TOO_MANY_REDIRECTS 오류를 표시합니다.
모든 location 블록에 이 4줄을 반복해서 작성하면 설정이 서로 어긋나기 쉽습니다. 하나의 파일에 모아두고 include 하십시오.
# /etc/nginx/snippets/proxy-headers.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;location / {
include snippets/proxy-headers.conf;
proxy_pass http://127.0.0.1:3000;
}이곳의 상속에는 함정이 있습니다. location 블록은 자신만의 proxy_set_header 지시어를 정의하지 않을 때만 server 블록의 설정을 상속받습니다. location 내부에 proxy_set_header을 하나라도 추가하면, server 레벨에서 정의된 모든 헤더는 해당 location에서 무시됩니다. 따라서 모든 헤더를 단일 레벨에서 관리하거나, 프록시를 수행하는 각 location마다 include를 사용하여 스니펫을 포함하십시오.
WebSocket 애플리케이션이 연결되었다가 바로 끊기는 이유는 무엇입니까?
기본 설정이 업그레이드를 허용하지 않으며, 기본 읽기 타임아웃 설정이 60초 동안 유휴 상태인 터널을 닫아버리기 때문입니다. WebSocket은 Upgrade: websocket 및 Connection: Upgrade 헤더를 포함한 HTTP 요청으로 시작됩니다. 이들은 홉별(hop-by-hop) 헤더이므로 프록시가 이를 전달하지 않고 소비해야 합니다. Ubuntu 24.04의 nginx 1.24.0에서는 업스트림 프로토콜이 기본적으로 HTTP/1.0으로 설정되어 있는데, 이 버전은 업그레이드 메커니즘을 지원하지 않습니다. 따라서 두 설정 모두 수동으로 다시 지정해야 합니다.
map 설정은 http 컨텍스트 내의 별도 파일에 작성합니다.
# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}그다음 location 설정을 추가합니다.
location / {
include snippets/proxy-headers.conf;
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}map을 사용하는 이유는 하나의 location에서 두 가지 유형의 트래픽을 모두 처리하기 위해서입니다. 일반적인 요청에서는 $http_upgrade이 비어 있으므로 $connection_upgrade은 close이 됩니다. 업그레이드 요청 시에는 websocket 값을 가지므로 업스트림으로 전달되는 헤더는 Connection: upgrade이 됩니다. proxy_set_header Connection "upgrade";을 하드코딩하면 모든 일반 페이지 요청에도 해당 헤더가 전송되며, 일부 백엔드는 이러한 요청에 대해 400 오류로 응답합니다.
proxy_http_version 1.1;는 nginx 1.29.7 버전부터 기본값이므로 해당 버전에서는 이 줄을 추가해도 아무런 변화가 없으며 문제도 발생하지 않습니다. 1.24.0 패키지에서는 반드시 필요합니다. Upgrade 및 Connection 줄은 nginx가 기본적으로 이 두 헤더를 전달하지 않으므로 모든 버전에서 필수입니다.
proxy_read_timeout는 "로딩은 되는데 업데이트가 멈춘다"는 현상의 원인입니다. 기본값은 60초이며, 이는 연결의 전체 수명이 아니라 백엔드로부터 데이터를 읽는 간격을 측정합니다. 60초 동안 아무런 데이터가 오가지 않는 WebSocket은 nginx에 의해 닫히며, 브라우저 콘솔에는 1006 코드로 소켓이 종료되었다고 표시됩니다. 1분보다 짧은 주기로 자체 하트비트를 보내는 애플리케이션은 이 문제를 겪지 않지만, 그렇지 않은 애플리케이션은 1분마다 연결이 끊깁니다. 실시간 편집기나 대시보드에서 이 문제가 가장 먼저 나타나며, HTTPS 뒤에서 운영되는 n8n 인스턴스가 대표적인 사례입니다.
proxy_pass의 끝에 붙는 슬래시가 URL을 변경하는 이유는 무엇입니까?
규칙은 한 문장으로 정의됩니다. proxy_pass가 URI(Uniform Resource Identifier)로 끝나면, 설령 슬래시 하나만 있는 /이라 하더라도, nginx는 요청 경로에서 location 접두사와 일치하는 부분을 제거하고 그 자리에 해당 URI를 삽입합니다. proxy_pass이 호스트와 포트에서 끝난다면, 요청 경로는 변경되지 않고 그대로 전달됩니다.
location /app/ {
proxy_pass http://127.0.0.1:3000/;
}/app/status에 대한 요청은 백엔드에 /status으로 전달됩니다.
location /app/ {
proxy_pass http://127.0.0.1:3000;
}/app/status에 대한 요청은 백엔드에 /app/status로 전달됩니다.
어떤 형식을 사용할지는 애플리케이션에 따라 다릅니다. 기본 경로(base-path)나 하위 폴더 설정이 있는 애플리케이션은 두 번째 형식을 원하며, 해당 설정에 /app을 알려주어야 합니다. 접두사에 대해 아무것도 모르는 애플리케이션은 첫 번째 형식이 필요합니다. 첫 번째 형식은 즉시 확인할 수 있는 문제가 있습니다. 애플리케이션이 반환하는 HTML에 /static/main.css와 같은 절대 경로가 포함되어 있으면, 브라우저는 사이트 루트에서 해당 파일을 찾으려 시도합니다. 일치하는 location이 없으므로 페이지는 스타일이 적용되지 않은 채 렌더링됩니다. 브라우저의 네트워크 탭을 확인하면 해당 에셋 요청이 404 오류로 반환되는 것을 볼 수 있습니다. 해결 방법은 애플리케이션 자체의 기본 경로 설정을 수정하거나, 동일한 백엔드를 가리키는 두 번째 location /static/를 추가하는 것입니다.
정규 표현식(regex) location은 proxy_pass에 URI를 포함할 수 없습니다. sudo nginx -t은 해당 설정을 거부하며 그 이유를 "proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block이라고 명시합니다.
이러한 유형의 문제는 각 애플리케이션에 고유한 도메인 이름인 app.example.com를 부여하고 location /에서 프록시하도록 설정하면 완전히 사라집니다. 하위 경로(sub-path) 방식은 DNS 레코드를 추가할 수 없는 상황에서만 고려할 가치가 있습니다.
하나의 도메인 이름 뒤에 여러 백엔드를 두려면 어떻게 해야 합니까?
upstream 블록을 사용합니다. 이 블록은 http 컨텍스트에 속하므로, 같은 파일 내의 server 블록 위나 /etc/nginx/conf.d/에 작성합니다.
upstream app_backend {
least_conn;
server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
server 127.0.0.1:3001 max_fails=3 fail_timeout=30s;
keepalive 32;
}그다음 location에서 이를 지정합니다: proxy_pass http://app_backend;.
기본 방식은 라운드 로빈입니다. least_conn은 활성 연결 수가 가장 적은 백엔드로 각 요청을 전달하며, 요청 처리 시간이 일정하지 않을 때 적합합니다. ip_hash는 특정 클라이언트 주소를 하나의 백엔드에 고정합니다. 애플리케이션이 세션을 자체 메모리에 유지하는 경우 ip_hash이 필요합니다. 라운드 로빈을 사용하면 요청이 세션 정보를 가지고 있지 않은 인스턴스로 전달될 때 사용자가 무작위로 로그아웃되기 때문입니다. 세션을 공유 저장소로 옮기는 것이 더 나은 해결책입니다.
max_fails=3 fail_timeout=30s는 30초 동안 3번의 실패가 발생하면 해당 서버를 30초 동안 제외한다는 의미입니다. 블록 내의 모든 서버가 이 상태가 되면 클라이언트는 502 오류를 받으며, 에러 로그에는 no live upstreams while connecting to upstream가 기록됩니다.
keepalive 32은 워커 프로세스당 최대 32개의 유휴 연결을 백엔드로 유지하여 대부분의 요청에서 TCP 핸드셰이크 과정을 생략합니다. Ubuntu 24.04의 1.24.0 버전에서는 이 줄이 캐시를 활성화하는 역할을 합니다. nginx 1.29.7부터는 캐시가 기본적으로 켜져 있지만, 문서화된 기본값은 keepalive 32 local;이며 local 매개변수는 캐시된 연결이 서로 다른 location 간에 공유되는 것을 방지합니다. 따라서 1.29.7 이상 버전에서 단순히 keepalive 32;를 작성하는 것은 기본값을 재확인하는 것이 아닙니다. local을 생략하면 동일한 업스트림 서버로 프록시하는 모든 location이 풀링된 연결을 재사용하게 되는데, 이는 기본 동작과 다른 점입니다. 해당 버전에서는 이 줄을 생략하거나 기본값을 유지하려면 keepalive 32 local;을 작성하고, 공유를 원할 때만 단독으로 작성하십시오. local 매개변수는 1.29.7에서 새로 추가되었으므로 1.24.0 패키지에서는 사용할 수 없습니다. HTTP 백엔드의 경우, nginx가 권장하는 풀 설정은 proxy_http_version을 1.1(nginx 1.29.4 이상에서는 2)로 설정하고 Connection 헤더를 비워 업스트림으로 전달하는 것입니다. nginx는 HTTP/1.0 지속적 연결을 지원하는 백엔드에 Connection: Keep-Alive을 보내는 방식도 문서화하고 있으나, 이 방법은 권장하지 않습니다. 1.29.7 버전부터는 권장 설정의 두 요소 모두 기본값으로 적용됩니다. 1.24.0 버전에서는 proxy_http_version 1.1;과 proxy_set_header Connection "";를 location에 직접 추가해야 합니다. 그렇지 않으면 nginx가 Connection: close과 함께 HTTP/1.0을 계속 보내게 되어 풀이 재사용되지 않습니다. 동일한 location에서 WebSocket 맵을 사용하는 경우, 빈 케이스를 close에서 빈 문자열로 변경하여 일반 요청에 Connection 헤더가 포함되지 않도록 해야 풀링된 연결이 재사용됩니다.
map $http_upgrade $connection_upgrade {
default upgrade;
'' '';
}upstream 블록 내부의 이름은 nginx가 시작될 때 해석됩니다. 백엔드가 재시작 시 새로운 주소를 할당받는 컨테이너라면, nginx는 리로드하기 전까지 이전 주소를 계속 사용합니다. nginx 1.27.3 이상 버전은 resolver, upstream 블록 내의 zone, 그리고 각 server 줄의 resolve 매개변수를 통해 리로드 없이 이러한 변경 사항을 추적할 수 있지만, 1.24.0 패키지는 이보다 이전 버전입니다. Docker 네트워크 내부에서는 내장 리졸버를 사용하여 요청 시점에 조회가 이루어지도록 변경할 수 있습니다.
resolver 127.0.0.11 valid=10s;
set $backend http://app:3000;
proxy_pass $backend;컨테이너가 자주 생성되고 삭제되어 nginx 설정을 계속 수정해야 하는 상황이라면, 컨테이너 레이블을 읽는 프록시를 사용하는 것이 더 효율적입니다. 여러 Docker Compose 앱 앞단의 Traefik은 컨테이너 자체에서 라우팅 정보를 구성합니다.
업로드 시 413 Request Entity Too Large 오류가 발생하는 이유는 무엇입니까?
client_max_body_size의 기본값은 1 메가바이트입니다. 이보다 큰 요청 본문은 nginx에 의해 거부되며 413 오류가 발생하고, 오류 로그에는 client intended to send too large body가 기록됩니다. 서버 블록 또는 업로드가 발생하는 location 블록에서 이 값을 높이십시오.
client_max_body_size 512m;0 값을 설정하면 해당 검사가 완전히 비활성화됩니다. 512m를 설정하더라도 nginx는 여전히 해당 제한을 초과하는 요청 본문을 거부하므로, 이 설정을 변경한 후에도 413 오류가 발생한다면 백엔드가 원인이 아님을 알 수 있습니다. 애플리케이션 자체의 업로드 제한을 확인하기 전에, 업로드를 처리하는 location의 유효한 client_max_body_size 설정과 nginx 오류 로그를 먼저 확인하십시오.
기본적으로 nginx는 업스트림 연결을 열기 전에 요청 본문 전체를 읽으며, 용량이 큰 데이터는 먼저 디스크의 임시 파일에 기록합니다. 이는 백엔드가 로컬 속도로 업로드를 전달받게 하여 느린 클라이언트로부터 애플리케이션을 보호합니다. 매우 큰 업로드의 경우 스트리밍 방식을 사용할 수 있습니다.
proxy_request_buffering off;1.24.0 패키지에서 HTTP/1.1 청크 업로드를 수행할 때는 해당 location에 proxy_http_version 1.1;도 설정해야 합니다. 그렇지 않으면 nginx가 본문을 버퍼링합니다. 이 경우 백엔드는 데이터가 도착하는 대로 본문을 전달받으므로 이를 처리할 수 있어야 합니다. nginx가 본문을 업스트림으로 전송하기 시작하면, 다른 업스트림으로 요청을 재시도할 수 없습니다.
기본값이 60초인 client_body_timeout은 전체 업로드 시간이 아니라 본문을 읽는 두 시점 사이의 간격에 적용됩니다. 느리더라도 꾸준히 진행되는 업로드는 유지되지만, 중단된 업로드는 연결이 끊깁니다.
응답 버퍼링과 실시간 출력을 차단하는 설정
proxy_buffering은 기본적으로 활성화되어 있으며, 일반적으로는 이 설정이 권장됩니다. Nginx는 애플리케이션이 응답을 작성하는 속도만큼 빠르게 이를 읽어 들여 저장한 뒤, 속도가 느린 클라이언트의 페이스에 맞춰 데이터를 전달합니다. 덕분에 애플리케이션 워커는 느린 다운로드가 완료될 때까지 기다릴 필요 없이 작업을 일찍 종료할 수 있습니다.
이 기능은 스트리밍 응답을 차단합니다. 서버 전송 이벤트(Server-sent events)나 실시간 로그 출력의 경우, 버퍼가 가득 찰 때까지 사용자에게 아무런 내용도 표시되지 않습니다. 해당 위치에서만 버퍼링을 끄십시오.
proxy_buffering off;애플리케이션을 직접 제어할 수 있다면, 스트리밍 응답에만 X-Accel-Buffering: no 헤더를 전송하는 것이 더 나은 방법입니다. Nginx는 응답마다 이 헤더를 읽어 해당 응답에 대해서만 버퍼링을 비활성화하므로, 일반적인 페이지는 버퍼링의 이점을 그대로 유지할 수 있습니다.
에러 로그에 upstream sent too big header while reading response header from upstream이 표시된다면, 응답 헤더가 하나의 버퍼에 들어가지 않은 것입니다. proxy_buffer_size는 기본적으로 메모리 페이지 하나 크기(플랫폼에 따라 4KB 또는 8KB)로 설정되어 있는데, 긴 쿠키나 큰 인증 헤더가 포함되면 이 용량을 초과하게 됩니다. 두 값을 모두 높이십시오.
proxy_buffer_size 16k;
proxy_buffers 8 16k;이 설정에서 TLS는 어디에 위치해야 합니까?
Nginx에서 모든 설정의 앞단에 위치합니다. TLS(Transport Layer Security)는 프록시에서 종료되며, Nginx에서 애플리케이션으로 향하는 연결은 루프백 주소를 통해 일반 HTTP로 유지되므로 네트워크상의 다른 어떤 요소도 이를 읽을 수 없습니다. 애플리케이션은 4개의 헤더 중 네 번째인 X-Forwarded-Proto를 통해 방문자가 HTTPS를 사용했음을 알 수 있습니다.
인증서 경로를 직접 작성하지 마십시오. DNS 레코드를 서버로 지정하고 방화벽을 연 다음, Certbot이 이 서버 블록을 직접 수정하도록 하십시오. Certbot은 ssl_certificate 경로를 포함하는 listen 443 ssl 라인을 추가하고 포트 80에서 리다이렉트를 설정합니다. Certbot을 사용하여 Nginx용 Let's Encrypt 인증서 발급하기에서 발급 및 갱신 타이머에 대해 다룹니다.
sudo ufw allow 'Nginx Full'
sudo ufw statusNginx Full은 Nginx 패키지가 설치하는 애플리케이션 프로필이며, 포트 80과 포트 443을 동시에 엽니다. 모든 방문자를 HTTPS로 리다이렉트한 후에도 HTTP-01 갱신 챌린지를 위해 포트 80은 계속 열려 있어야 합니다.
설정 테스트 및 리로드
sudo nginx -t
sudo systemctl reload nginxnginx -t는 포함된 모든 파일을 구문 분석하여 테스트 성공 여부를 보고하거나, 오류가 발생한 파일과 줄 번호를 출력합니다. 리로드하기 전에 반드시 이 출력을 확인하십시오. 설정이 잘못된 상태에서 리로드하면 해당 설정은 적용되지 않습니다. Nginx는 이전 설정을 그대로 유지하므로 사이트는 계속 운영되지만, 변경 사항은 아무런 동작도 하지 않게 됩니다. systemctl restart은 이와 다르게 동작하며 더 위험합니다. 리스타트는 실행 중인 서버를 먼저 종료하기 때문에, 설정 오류가 있으면 Nginx가 아예 실행되지 않는 상태가 됩니다. 기본적으로 리로드를 사용하고, 반드시 필요한 경우에만 리스타트를 수행하십시오.
sudo tail -f /var/log/nginx/error.log
sudo ss -lntp | grep -E ':(80|443|3000)'ss 행은 각 포트를 점유하고 있는 프로세스를 보여줍니다. 이를 통해 애플리케이션이 proxy_pass가 가리키는 위치에서 실제로 리스닝 중인지 확인할 수 있습니다.
실제로 마주하게 될 오류들
502 Bad Gateway, 에러 로그에 connect() failed (111: Connection refused) while connecting to upstream이 기록된 경우. proxy_pass 주소에서 응답하는 서비스가 없습니다. 애플리케이션이 중단되었거나, 다른 포트에 바인딩되었거나, 호스트에서 접근할 수 없는 컨테이너 내부 주소로 바인딩된 상태입니다.
502 오류와 no live upstreams while connecting to upstream. upstream 블록 내의 모든 서버가 max_fails에 의해 실패 상태로 표시되었습니다. 백엔드를 복구하십시오. fail_timeout 시간이 만료되면 Nginx가 다시 연결을 시도합니다.
504 Gateway Time-out, upstream timed out (110: Connection timed out) while reading response header from upstream 기록. 백엔드가 연결을 수락했으나 proxy_read_timeout 초 동안 아무런 응답을 보내지 않았습니다. 실제로 처리가 오래 걸리는 작업이라면 타임아웃을 늘리는 것이 맞지만, 애플리케이션이 멈춘 상태라면 잘못된 해결책입니다.
모든 경로에서 애플리케이션이 404를 반환하는 경우. 후행 슬래시 규칙이 경로를 재작성했습니다. 애플리케이션 로그에 기록된 경로와 실제 요청한 경로를 비교하십시오.
다른 사이트가 응답하는 경우. server_name이 Host 헤더와 일치하지 않아 요청이 default_server 블록으로 넘어갔습니다.
페이지는 로드되지만 약 1분 뒤 인터페이스가 멈추는 경우. WebSocket 관련 문제입니다. Upgrade 처리가 누락되었거나, proxy_read_timeout 설정이 여전히 60초로 되어 있기 때문입니다.
FAQ
proxy_pass를 추가한 뒤 nginx가 502 Bad Gateway를 반환하는 이유는 무엇입니까?
nginx가 proxy_pass에 지정된 주소로 연결을 설정할 수 없기 때문입니다. /var/log/nginx/error.log의 에러 로그에서 원인을 확인할 수 있습니다. connect() failed (111: Connection refused) while connecting to upstream은 해당 주소에서 수신 대기 중인 프로세스가 없음을 의미하며, no live upstreams는 upstream 블록 내의 모든 서버가 실패 상태로 표시되었음을 의미합니다. sudo ss -lntp | grep 3000를 실행하여 어떤 프로세스가 해당 포트를 점유하고 있는지, 그리고 어떤 주소에 바인딩되어 있는지 확인하십시오. 컨테이너 내부 주소에 바인딩된 애플리케이션이나 설정한 포트와 다른 포트를 사용하는 경우 이 에러가 발생합니다.
nginx 뒤에 있는 애플리케이션이 약 1분 후에 연결이 끊기는 이유는 무엇입니까?
해당 연결이 WebSocket인데 proxy_read_timeout 설정이 기본값인 60초로 유지되고 있기 때문입니다. 이 설정은 백엔드로부터 데이터를 읽는 간격을 측정합니다. 통신이 없는 소켓은 nginx에 의해 닫히며 브라우저 콘솔에는 1006 종료 코드가 표시됩니다. proxy_http_version 1.1을 설정하고(nginx 1.29.7부터 기본값이지만 Ubuntu 24.04가 제공하는 1.24.0 패키지에는 포함되지 않음), map를 사용하여 $http_upgrade에 Upgrade 및 Connection 헤더를 전달하며, proxy_read_timeout을 3600s와 같은 값으로 높이십시오. Upgrade 헤더가 없으면 업그레이드 자체가 발생하지 않으므로 애플리케이션은 폴링 방식으로 전환되거나 실시간 업데이트가 표시되지 않습니다.
proxy_pass에서 마지막 슬래시(/)가 중요합니까?
네, 슬래시 유무에 따라 백엔드가 수신하는 경로가 달라집니다. location /app/와 proxy_pass http://127.0.0.1:3000/ 설정에서 /app/status에 대한 요청은 /status로 백엔드에 전달됩니다. 이는 호스트와 포트 뒤의 URI가 일치하는 location 접두사를 대체하기 때문입니다. 마지막 슬래시를 제거하면 동일한 요청이 /app/status로 전달됩니다. 접두사를 제거하면 애플리케이션의 에셋 링크가 깨지는 경우가 많습니다. 링크가 절대 경로로 유지되어 사이트 루트에서 404 에러가 발생하기 때문입니다. 따라서 base-path 설정이 있는 애플리케이션은 경로를 그대로 전달하는 방식을 사용하는 것이 좋습니다.
애플리케이션 로그에 모든 방문자의 IP 주소가 127.0.0.1로 기록되는 이유는 무엇입니까?
애플리케이션이 수신하는 연결이 실제로 루프백 주소의 nginx로부터 오기 때문입니다. 방문자의 주소는 설정한 헤더를 통해서만 애플리케이션에 도달합니다. 단일 값은 proxy_set_header X-Real-IP $remote_addr;를, 연결된 체인은 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;을 사용하십시오. 이후 애플리케이션에서 해당 헤더를 신뢰하도록 설정해야 합니다. 클라이언트가 직접 X-Forwarded-For을 보낼 수 있다는 점을 기억하십시오. 따라서 nginx가 엣지 서버인 경우, 헤더를 추가하지 말고 $remote_addr를 사용하여 덮어쓰십시오.
nginx와 애플리케이션 사이의 연결에 TLS가 필요합니까?
애플리케이션이 동일한 서버에서 실행되고 127.0.0.1에 바인딩된 경우에는 필요하지 않습니다. 해당 트래픽은 머신 외부로 나가지 않기 때문입니다. nginx에서 TLS를 종료하고 루프백을 통한 일반 HTTP로 proxy_pass를 유지하십시오. 그리고 방문자가 HTTPS를 사용했음을 애플리케이션이 알 수 있도록 X-Forwarded-Proto $scheme를 전달하십시오. 백엔드가 제어할 수 없는 네트워크 너머의 다른 호스트에 있는 경우, 해당 구간은 별도의 보호가 필요합니다. 백엔드까지 HTTPS를 사용하거나 두 머신 사이에 프라이빗 터널을 구성하십시오.