nginx 설정 방법, 파일부터 프록시까지

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

오늘의 인사이트 요약

1. nginx 설정 파일 위치는 설치 방식마다 달라서 nginx -T로 실제 읽히는 설정부터 확인합니다.

2. 설정은 http 안에 server, server 안에 location을 두고, 리버스 프록시는 location에 proxy_pass를 적습니다.

3. nginx 설정 적용은 nginx -t 검사 뒤 nginx -s reload로 합니다.

nginx는 정적 파일을 제공하거나 요청을 애플리케이션 서버로 전달하는 웹 서버입니다. 설정은 실제로 읽는 파일을 찾은 뒤 server·location 블록을 수정하고 검사해 적용합니다. 오늘은 nginx 설정 방법을 파일 위치부터 리버스 프록시와 reload 순서까지 알아보겠습니다.

nginx 설정 파일 위치는 설치 방식마다 다릅니다

nginx 공식 입문 가이드는 nginx.conf의 위치를 /usr/local/nginx/conf, /etc/nginx, /usr/local/etc/nginx 중 하나로 안내합니다.

사이트별 설정은 따로 떼어 둡니다.

데비안·우분투 패키지는 sites-available에 사이트 설정을 두고 sites-enabled에 심볼릭 링크를 걸어 켭니다. macOS Homebrew라면 $HOMEBREW_PREFIX/etc/**nginx**/nginx.conf와 servers/ 폴더를 읽고 기본 포트는 8080입니다.

헷갈릴 때는 nginx 설정 확인 명령부터 칩니다.

**nginx** -T는 설정을 검사하면서 읽어 들인 파일 전체를 출력해서 엉뚱한 파일을 고치고 있었다면 바로 드러납니다.

nginx 설정 방법의 뼈대는 server와 location 블록입니다

단순 지시어는 세미콜론으로 끝냅니다. 여러 지시어를 묶는 블록에는 중괄호를 사용합니다. server는 http 안에, location은 server 안에 들어갑니다.

server {
    listen 80;
    server_name example.com;
    location / { root /data/www; }
}

server는 받을 도메인과 포트를 정합니다.

listen에 포트를, **server_name**에 도메인을 적습니다. 도메인마다 server 블록을 두면 서버 한 대로 여러 사이트를 받습니다.

location은 일치 방식에 따라 선택됩니다.

일반 접두사 location에서는 가장 긴 접두사를 먼저 찾습니다. 이후 정규식 location을 순서대로 검사해 처음 일치한 것을 사용합니다. 다만 =의 정확한 일치는 즉시 선택되고, 선택된 접두사에 ^~가 있으면 정규식 검사를 건너뜁니다. 아래 도식은 일반 접두사와 정규식의 기본 순서를 간략히 표현한 것입니다.

nginx 리버스 프록시는 proxy_pass 한 줄에서 시작합니다

바깥 요청을 nginx가 받아 내부 서버로 넘기는 구성으로, 화면과 API를 한 도메인 아래 묶을 때 씁니다.

location /api/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Host 헤더는 직접 넘겨야 합니다.

공식 문서상 기본값은 Host를 $proxy_host로 바꿔 보냅니다. 백엔드가 원래 도메인을 알아야 한다면 위 예시처럼 $host를 넘깁니다.

proxy_pass 뒤의 경로가 전달 주소를 바꿉니다.

경로를 붙이면 location과 맞은 부분이 그 경로로 바뀝니다. HTTPS를 설정할 때는 listen 443 ssl과 함께 ssl_certificate·ssl_certificate_key, 인증서 체인과 접근 권한을 지정합니다.

nginx 설정 적용은 검사하고 reload하는 순서입니다

nginx -t는 참조하는 파일까지 열어 봅니다.

공식 명령줄 문서에 따르면 -t는 문법 검사 뒤 설정이 가리키는 파일을 열 수 있는지도 봅니다. 틀린 인증서 경로도 여기서 잡힙니다.

새 설정을 적용하지 못하면 기존 설정으로 동작합니다.

**nginx** -s reload를 받은 마스터 프로세스는 새 워커를 띄우고 기존 워커는 처리 중인 요청을 마친 뒤 종료합니다. 적용에 실패하면 기존 설정으로 계속 동작합니다.

고친 사람만 아는 설정은 다음 배포 때 다시 발목을 잡습니다. 서버 작업을 맡길 곳에는 이렇게 물어보면 됩니다. 이 설정은 어느 파일에, 왜 적혀 있나요?

구체적인 설정과 사용 조건은 nginx 입문 가이드 · nginx proxy_pass 문서에서 더 자세히 보실 수 있습니다.

요청이 전달되는 경로까지 함께 살펴봅니다

똑똑한개발자는 웹·앱과 관리자 시스템의 백엔드·인프라 개발을 함께합니다. 사용자 화면과 API가 연결되는 서비스에서는 화면 기능과 요청이 전달되는 경로를 함께 살펴야 하는데요. 서버·애플리케이션의 연결 관계를 살펴 서비스에 필요한 개발 범위를 구체화합니다.

서버 설정과 애플리케이션 연결을 어디부터 확인할지 고민되시나요? 아래 똑똑한개발자 링크로 문의해 주시면 요청 경로와 서버 구성, 필요한 개발 작업을 함께 검토하겠습니다.

감사합니다. :)

📚 이어서 읽어보세요

• CORS 에러 해결 방법

• 가비아 도메인 Vercel 연결 방법