사용 방법
- 용도를 고릅니다. 앱 서버 앞단의 리버스 프록시, 정적 파일, SPA(React·Vue 빌드 결과), PHP-FPM 중 하나입니다.
- 도메인을 공백으로 구분해 입력합니다. 첫 번째가 대표 도메인이며 인증서 기본 경로와 파일 이름에 쓰입니다.
- 프록시는 앱 서버 주소(예:
http://127.0.0.1:3000), 나머지는 웹 루트 경로를 적습니다. - HTTPS, gzip, 보안 헤더 같은 옵션을 켜고 끕니다. 생성된 설정을 복사하거나
도메인.conf로 내려받아/etc/nginx/conf.d/에 두고sudo nginx -t로 확인한 뒤sudo systemctl reload nginx로 적용합니다.
옵션이 만드는 설정
| 옵션 | 생성되는 설정 |
|---|---|
| HTTPS | listen 443 ssl;, 인증서·개인키 경로, ssl_protocols TLSv1.2 TLSv1.3;, 세션 캐시 |
| HTTP 리디렉션 | 80 포트 서버가 return 301 https://$host$request_uri; |
| HTTP/2 | http2 on; (nginx 1.25.1 이상 문법) |
| HSTS | Strict-Transport-Security "max-age=31536000" (1년) |
| gzip | gzip on; 과 텍스트·JSON·JS·SVG 등 압축 대상 MIME 형식 |
| 보안 헤더 | X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy |
| 웹소켓 | Upgrade·Connection 헤더와 map $http_upgrade $connection_upgrade |
| 정적 파일 캐시 | css·js·이미지·폰트 확장자에 expires 30d; |
| 숨김 파일 차단 | .git, .env 같은 점 파일 요청을 거부하되 .well-known 은 허용 |
| www 정리 | 대표 도메인이 아닌 쪽 서버 블록이 대표 도메인으로 301 |
생성되는 구조 예시
기본값(리버스 프록시, HTTPS, 도메인 example.com www.example.com)으로는 서버 블록이 두 개 나옵니다. 첫 번째는 80 포트에서 모든 요청을 https://$host$request_uri 로 보냅니다. 두 번째는 443 포트에서 인증서를 읽고, proxy_pass http://127.0.0.1:3000; 과 Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto 헤더를 앱에 넘깁니다. 인증서 경로를 비워 두면 Let’s Encrypt 기본 위치인 /etc/letsencrypt/live/example.com/fullchain.pem 이 들어갑니다.
알아 둘 점
- 인증서가 먼저 필요합니다. 443 블록은 인증서 파일이 없으면
nginx -t가 실패합니다. 하단 명령에certbot certonly예시가 나옵니다. webroot 방식을 쓰려면 “webroot 인증 경로 열기” 를 켜고 80 포트 블록으로 먼저 적용하세요. - add_header 상속 규칙: 하위
location에add_header가 하나라도 있으면 상위(server)의add_header는 모두 무시됩니다. 직접location에 헤더를 추가한다면 보안 헤더도 그 안에 다시 적어야 합니다. - proxy_pass 의 경로: 주소 끝에 경로(
/api/)를 붙이면 매칭된 경로가 그 경로로 치환되어 전달됩니다. 경로 없이 쓰면 원래 요청 경로가 그대로 갑니다. - HSTS: 켜면 브라우저가 1년 동안 HTTPS 로만 접속합니다. 인증서 갱신까지 안정적으로 되는지 확인한 뒤에 켜세요.
- 웹소켓 map:
$connection_upgrade는 다른 설정 파일에서 이미 정의했다면 중복 오류가 납니다. 그 경우 생성된map블록만 지우세요. - 입력한 도메인과 경로는 영문·숫자·
.·-·/등 안전한 문자만 허용하며, 세미콜론이나 중괄호가 들어가면 그 값을 쓰지 않고 알려 줍니다. - 생성된 설정은 운영 서버에 반영하기 전에 검토하세요. 속도 제한, 캐시 프록시, 로그 형식 같은 운영 설정은 포함하지 않습니다.
- 컨테이너로 운영한다면 docker-compose 생성기와 Dockerfile 생성기를, 서버 포트 정책은 방화벽 규칙 생성기를 함께 쓰세요. 응답 코드 의미는 HTTP 상태 코드, 검색 로봇 설정은 robots.txt 생성기, 서브넷 계산은 IP 서브넷 계산기에서 할 수 있습니다.
자주 묻는 질문
설정 파일은 어디에 두나요?
배포판에 따라 다릅니다. Debian·Ubuntu 와 대부분의 도커 이미지는 /etc/nginx/conf.d/*.conf 를 읽습니다. Debian 계열의 sites-available/sites-enabled 방식을 쓴다면 같은 내용을 sites-available 에 두고 링크를 만들면 됩니다.
502 Bad Gateway 가 나오면 어떻게 하나요?
nginx 가 proxy_pass 주소의 앱에 연결하지 못한 것입니다. 앱이 실행 중인지, 주소와 포트가 맞는지, 도커라면 127.0.0.1 이 아니라 서비스 이름을 써야 하는지 확인하세요. 오류 로그는 /var/log/nginx/error.log 에 남습니다.
인증서는 어떻게 발급받나요?
Let’s Encrypt 의 certbot 이 일반적입니다. 이 도구는 certbot certonly 명령 예시를 함께 보여 줍니다. 발급과 자동 갱신 설정은 서버 환경에 맞게 확인하세요.
정적 파일이 404 로 나오면 어떻게 하나요?
root 경로가 맞는지, nginx 사용자(보통 www-data)가 해당 폴더를 읽을 권한이 있는지 확인하세요. SPA 라면 용도를 SPA 로 골라야 새로고침 시 index.html 로 되돌아갑니다.
입력한 내용이 서버로 전송되나요?
아니요. 설정은 브라우저 안에서만 만들어집니다.
입력한 내용은 브라우저 안에서만 처리되며 서버로 전송되지 않습니다.