nginx 설정 위치와 적용 순서 정리

nginx 설정 위치는 설치 방식에 따라 달라지고, 같은 파일 안에서도 블록이 겹치면 더 안쪽에 선언된 값이 이깁니다. 이 글은 패키지로 설치한 서버와 소스로 빌드한 서버에서 설정 파일이 놓이는 자리, include로 묶이는 순서, 그리고 지금 실제로 어떤 값이 적용되고 있는지 확인하는 방법을 정리합니다. 배포 직후 설정이 반영되지 않아 헤매는 시간을 줄이는 것이 목적입니다.

한눈에 보기

가장 먼저 확인할 것은 "이 서버에 nginx를 어떻게 설치했는가"입니다. 배포판 패키지로 설치했다면 /etc/nginx 아래를 기준으로 보고, 소스에서 직접 빌드했다면 빌드할 때 지정한 prefix 아래를 봅니다. 두 경우 모두 주 설정 파일 이름은 nginx.conf이고, 그 파일이 include로 다른 파일을 끌어오는 구조도 같습니다.

정리하면 다음과 같습니다.

• 주 설정 파일은 nginx.conf 하나이고, 나머지는 include로 붙는 조각 파일입니다.
• 패키지 설치는 /etc/nginx, 소스 빌드는 /usr/local/nginx/conf가 기본 자리입니다.
• 사이트별 설정은 conf.d 또는 sites-enabled에 나눠 두는 경우가 많습니다.
• 블록은 main, events, http, server, location 순으로 감싸지고, 안쪽 블록이 바깥 값을 덮어씁니다.
• 최종적으로 어떤 설정이 적용됐는지는 nginx -T로 한 번에 확인할 수 있습니다.

nginx 설정 파일 위치 비교

설치 방식별로 자주 만나는 경로를 표로 정리했습니다. 배포판마다 패키징 정책이 조금씩 다르므로, 표에 없는 경로를 쓰는 환경도 있을 수 있습니다.

표에서 눈여겨볼 점은 sites-available과 sites-enabled가 nginx 자체 기능이 아니라 데비안 계열 패키지가 만든 관행이라는 것입니다. nginx는 디렉터리를 특별히 취급하지 않고, nginx.conf에 적힌 include 경로에 있는 파일을 그대로 읽습니다. 그래서 sites-enabled를 쓰지 않는 환경이라면 conf.d에 파일을 하나 더 두는 방식으로 같은 효과를 낼 수 있습니다.

설정이 적용되는 순서

nginx는 설정 파일을 한 덩어리로 해석하지 않습니다. nginx.conf를 위에서 아래로 읽다가 include 지시어를 만나면, 그 파일의 내용을 마치 그 자리에 복사해 넣은 것처럼 이어서 읽습니다. 즉 include를 어디에 두었는지가 곧 적용 순서가 됩니다.

블록 구조는 다음과 같이 겹칩니다.

• main 컨텍스트: nginx.conf 최상단 영역으로, 프로세스 수나 실행 사용자 같은 전역 설정이 놓입니다.
• events 블록: 연결 처리 방식과 관련된 설정이 들어갑니다.
• http 블록: 프록시, 로그, MIME 타입처럼 HTTP 전반에 걸친 설정이 모입니다.
• server 블록: 가상 호스트 단위입니다. listen과 server_name으로 요청을 받을 대상을 정합니다.
• location 블록: URI 경로 단위입니다. 실제로 프록시를 걸거나 정적 파일을 서빙하는 지점입니다.

값이 겹칠 때의 규칙은 단순합니다. 같은 지시어가 안쪽 블록에도 있으면 안쪽 값이 쓰이고, 안쪽에 없으면 바깥 블록의 값을 물려받습니다. 다만 모든 지시어가 같은 상속 규칙을 따르지는 않습니다. 예를 들어 add_header는 상속되지만, 하위 블록에 add_header가 하나라도 선언되면 상위 블록의 헤더 목록을 물려받지 않습니다. 이런 예외는 지시어별 문서를 확인하는 편이 안전합니다.

요청이 들어왔을 때 어느 server와 location이 선택되는지도 순서의 일부입니다. server는 listen으로 후보를 좁힌 뒤 server_name이 가장 잘 맞는 블록을 고릅니다. location은 정확 일치가 가장 먼저 검사되고, 그다음 정규식 검사를 생략하는 접두 일치, 정규식 일치, 마지막으로 가장 긴 접두 일치 순으로 판단합니다. 이 우선순위를 모르면 "분명히 적었는데 다른 블록이 잡힌다"는 상황이 생깁니다.

단계별로 위치와 순서 확인하기

손으로 경로를 추측하는 대신, 서버에서 바로 확인하는 절차를 권합니다.

1. nginx -V로 빌드 정보를 확인합니다. 출력에 --conf-path가 함께 나오므로, 이 서버가 어느 nginx.conf를 기준으로 동작하는지 알 수 있습니다.
2. 해당 경로의 nginx.conf를 열어 include 줄을 모두 찾습니다. 어떤 디렉터리가 어떤 순서로 붙는지 여기서 결정됩니다.
3. nginx -t로 문법을 검사합니다. 오류가 있으면 파일과 줄 번호를 함께 알려주므로, 위치를 잘못 잡았을 때 가장 먼저 할 일입니다.
4. nginx -T로 병합된 최종 설정을 출력합니다. include가 모두 풀린 결과가 보이므로, 중복 선언이나 순서 문제를 눈으로 확인할 수 있습니다.
5. 실행 중인 프로세스를 확인해 실제 구동 중인 마스터 프로세스가 어떤 설정을 쓰는지 봅니다. 재시작 없이 반영하려면 systemctl reload nginx 또는 nginx -s reload를 사용합니다.

여기서 nginx -t와 nginx -T의 차이가 자주 헷갈립니다. 전자는 검사만 하고, 후자는 검사 결과와 함께 병합된 설정 전문을 보여줍니다. 배포 스크립트에는 검사용으로 nginx -t를 넣고, 디버깅할 때는 nginx -T를 쓰는 식으로 역할을 나누면 편합니다.

상황별 선택

환경마다 손에 익은 방식이 다르므로, 상황별로 어디를 만지는 것이 자연스러운지 정리했습니다.

배포판 패키지를 쓰는 경우는 /etc/nginx/nginx.conf를 크게 건드리지 않고 conf.d나 sites-enabled에 파일을 추가하는 방식이 관리하기 쉽습니다. 사이트 설정을 파일 단위로 분리해 두면 특정 사이트만 되돌리기가 간단합니다.

소스로 빌드한 경우는 prefix 아래 conf 디렉터리가 작업 공간이 됩니다. 패키지가 만들어 주는 conf.d가 없을 수 있으므로, nginx.conf에 include 줄을 직접 추가하고 디렉터리를 함께 만들어 두는 편이 좋습니다.

컨테이너로 운영하는 경우는 이미지 안의 기본 설정을 그대로 두고, 호스트의 설정 파일을 마운트해 덮어쓰는 패턴이 일반적입니다. 이때 마운트한 파일이 이미지 안의 include 경로와 맞물려야 하므로, 이미지의 nginx.conf에 적힌 include 경로를 먼저 확인해야 합니다.

여러 도메인을 한 서버에서 받는 경우는 도메인마다 server 블록을 분리하고, 공통 설정은 http 블록에 두는 구성이 깔끔합니다. 공통값을 server마다 복사해 두면 나중에 한 곳만 바꿔야 할 때 누락이 생깁니다.

주의할 점

• conf.d와 sites-enabled를 동시에 include 하면 같은 설정이 두 번 로드될 수 있습니다. 어느 쪽을 쓸지 정하고 한쪽만 남기는 편이 안전합니다.
• sites-enabled에 심볼릭 링크를 쓸 때 원본 파일을 지우면 링크가 깨집니다. 링크가 깨진 채로 reload 하면 설정 검사 단계에서 실패합니다.
• include에 와일드카드를 쓰면 매칭되는 파일을 이름 순으로 읽는 것으로 알려져 있습니다. 그래서 파일 이름 앞에 순번을 붙여 적용 순서를 고정하는 관행이 널리 쓰입니다.
• root와 alias는 동작이 달라서, 상속을 가정하고 경로를 적으면 의도와 다른 디렉터리를 가리킬 수 있습니다.
• 설정 파일 권한을 느슨하게 두면 민감한 값이 노출될 수 있습니다. 마스터 프로세스만 읽을 수 있게 관리하는 편이 좋습니다.
• reload는 기존 연결을 유지한 채 새 설정으로 교체하지만, 문법 오류가 있으면 조용히 이전 설정으로 남습니다. reload 후에는 반드시 결과를 확인해야 합니다.

자주 묻는 질문

nginx 설정 파일 위치는 어디인가요?

설치 방식에 따라 다르지만, 배포판 패키지는 /etc/nginx/nginx.conf, 소스 컴파일은 /usr/local/nginx/conf/nginx.conf가 기본입니다. 정확한 경로는 nginx -V 출력의 --conf-path 항목에서 확인할 수 있습니다.

sites-available과 sites-enabled는 무엇이 다른가요?

nginx 자체 기능이 아니라 데비안 계열 패키지가 만든 관행입니다. sites-available에 원본 설정을 두고, 실제로 적용할 사이트만 sites-enabled에 심볼릭 링크로 연결하는 방식입니다.

include 순서를 바꾸면 적용 결과가 달라지나요?

같은 지시어를 여러 파일에서 선언했다면 순서에 따라 마지막에 읽힌 값이 남을 수 있습니다. 반면 server나 location처럼 선택 규칙이 따로 있는 블록은 파일 순서보다 매칭 규칙이 우선합니다.

nginx -t와 nginx -T는 무엇이 다른가요?

nginx -t는 설정 문법을 검사하고 결과만 알려줍니다. nginx -T는 검사와 함께 include가 모두 풀린 최종 설정을 출력하므로, 중복 선언이나 순서를 추적할 때 사용합니다.

컨테이너에서는 설정을 어디에 두나요?

이미지 안의 /etc/nginx 구조를 그대로 두고, 호스트의 설정 파일을 해당 경로에 마운트하는 방식이 일반적입니다. 마운트하기 전에 이미지의 nginx.conf에 적힌 include 경로를 먼저 확인해야 합니다.

출처

• nginx 공식 문서, Beginner's Guide: https://nginx.org/en/docs/beginners_guide.html
• nginx 공식 문서, Core Module (include 지시어): https://nginx.org/en/docs/ngx_core_module.html
• nginx 공식 문서, HTTP Core Module (location 매칭 규칙): https://nginx.org/en/docs/http/ngx_http_core_module.html
• NGINX 공식 관리자 가이드, Managing Configuration Files: https://docs.nginx.com/nginx/admin-guide/basic-functionality/managing-configuration-files/

설정 위치를 정리했다면 다음은 반영 절차를 손에 익히는 차례입니다. reload와 restart가 각각 어떤 상황에 맞는지, 무중단 배포에서 어느 쪽을 골라야 하는지는 nginx reload와 restart 차이 글에서 이어서 확인하실 수 있습니다.