- Published on
nginx 설정 파일 쉽게 하는 법: 구조부터 적용까지
- Authors

- Name
- Indo Yoon


nginx 설정 파일은 main부터 location까지 블록이 계층이고, 사이트는 include로 나누는 구성이 읽기 쉬워요. 파일을 새로 쓰기 전에 지금 읽히는 경로를 백업해야 리로드 실패 때 돌아갈 곳이 있어요. 문법 검사와 재적용은 다른 단계예요. 아래는 블록 역할, 위치, 작성 순서, 프록시 예시예요.

한눈에 보기
프로세스 설정은 main, 연결은 events, HTTP 공통은 http, 도메인은 server, URI는 location이에요. 백엔드는 upstream으로 묶거나 proxy_pass로 직접 보내요. 고친 파일은 include되어야 적용돼요. 재시작보다 검사 후 재적용이 연결 유지에 맞아요.
설정 블록 구조 비교
표는 블록별 역할과 주로 두는 지시어를 나눈 거예요. 지시어를 잘못된 블록에 두면 문맥 오류나 적용 범위 실수가 나요. upstream은 http 문맥에 두고 server에서 이름으로 참조해요.
| 블록 | 역할 | 주로 두는 디렉티브 |
|---|---|---|
| main | 프로세스 전반 설정 | user, worker_processes, error_log, pid |
| events | 연결 처리 방식 | worker_connections |
| http | HTTP 전반 공통 설정 | include, default_type, log_format, access_log, sendfile |
| server | 가상 호스트 단위 | listen, server_name, root, return |
| location | URI 단위 처리 | try_files, proxy_pass, alias, expires |
| upstream | 백엔드 서버 묶음 | server, least_conn, ip_hash |
설정 파일이 놓이는 위치
배포판 패키지, 직접 빌드, 컨테이너는 본파일 경로가 달라요. 실행 중인 프로세스가 연 파일과 include 목록이 기준이에요. conf.d와 sites-enabled는 본파일이 읽을 때만 의미가 있어요. 이미지 안 파일을 고쳐도 마운트가 덮으면 다음 기동에 사라져요.
http {
include /etc/nginx/mime.types;
default_type application/octet-stream;
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent"';
access_log /var/log/nginx/access.log main;
sendfile on;
keepalive_timeout 65;
include /etc/nginx/conf.d/*.conf;
}
단계별로 설정 파일 작성하기
백업부터 재적용까지 순서를 지키면 내려간 서비스를 되돌리기 쉬워요.
1. 현재 설정을 먼저 백업합니다
본파일과 include된 조각을 함께 복사해 둬요. 저장소와 서버 중 원본이 어디인지도 적어요. 백업 없이 새로 쓰면 롤백이 어려워요.
2. main과 events 블록을 확인합니다
사용자, 워커, pid, 오류 로그가 main에 있는지 봐요. 연결 처리 수는 events에 둬요. 이 값을 사이트 파일에 넣지 않아요.
3. http 블록에 공통 설정을 모읍니다
MIME, 로그 형식, include, 공통 헤더는 http에 모아요. 사이트마다 다른 값만 server로 내려요. include 순서가 나중 값을 덮는지 봐요.
4. server 블록으로 가상 호스트를 만듭니다
listen과 server_name으로 도메인을 나눠요. 기본 서버가 의도한 사이트인지 확인해요. 인증서와 로그는 도메인별로 나누면 장애 범위가 줄어요.
5. location 블록으로 URI를 나눕니다
표의 지정자처럼 정확한 일치, 우선 접두, 정규식, 일반 접두가 선택이 달라요. 정적 파일과 API를 location으로 나누면 프록시 범위가 분명해요. alias와 root의 끝 슬래시를 맞춰요.
| 지정자 | 의미 | 예시 |
|---|---|---|
= | 정확히 일치 | location = /health { } |
^~ | 접두 일치, 정규식 검사 생략 | location ^~ /static/ { } |
~ | 대소문자 구분 정규식 | location ~ \.php$ { } |
~* | 대소문자 무시 정규식 | `location ~* .(jpg |
| 없음 | 일반 접두 일치 | location /api/ { } |
6. 문법을 검사합니다
실행 중인 것과 같은 설정 경로로 검사해요. 실패 메시지의 파일과 줄을 고치고 다시 검사해요. 조각 파일만 검사하면 상위 문맥이 빠져요.
sudo nginx -t
7. 재적용합니다
검사 통과 뒤 리로드로 재적용해요. 재시작은 연결을 끊을 수 있어서 기본 선택이 아니에요. 다른 프로세스에 신호를 보내지 않게 관리 방법을 통일해요.
sudo nginx -s reload
# 또는
sudo systemctl reload nginx
리버스 프록시 구성 예시
백엔드가 하나면 location에서 proxy_pass로 보내고, 여러 대면 upstream 이름을 써요. 호스트와 전달 헤더를 넘기지 않으면 백엔드가 잘못된 요청으로 볼 수 있어요. 헬스 경로는 프록시하지 않고 로컬에서 응답하게 나눌 수 있어요. 예시는 설치본 문서의 지시어 이름과 맞춰 적용해요.
upstream app_backend {
least_conn;
server 127.0.0.1:3000;
server 127.0.0.1:3001;
}
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://app_backend;
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;
proxy_http_version 1.1;
proxy_set_header Connection "";
}
}
server {
listen 80;
server_name www.example.com;
root /var/www/site;
location /assets/ {
try_files $uri =404;
expires 7d;
}
location / {
try_files $uri $uri/ /index.html;
}
location /api/ {
proxy_pass http://app_backend;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
상황별 선택
표는 정적 파일, 백엔드 한 대, 여러 대, 도메인 분리, TLS 종료, 경로 일부 프록시를 고르는 방법으로 나눈 거예요. 복잡한 정규식보다 접두로 나눌 수 있으면 접두가 읽기 쉬워요. 새 도메인은 server를 추가하고 include에 포함되는지 확인해요.
| 상황 | 고르는 방법 | 이유 |
|---|---|---|
| 정적 파일만 제공 | root + try_files | 파일 시스템 경로를 그대로 매핑해 단순해요 |
| 백엔드 한 대 뒤에 두기 | proxy_pass 직접 지정 | upstream 블록 없이도 충분해요 |
| 백엔드 여러 대 | upstream + 분배 방식 | 서버 목록을 한곳에서 관리할 수 있습니다 |
| 도메인 여러 개 | server 블록 분리 | 인증서와 로그를 도메인별로 나눌 수 있습니다 |
| HTTPS 종료 | listen에 ssl 지정 | 인증서 관리를 nginx 한곳으로 모읍니다 |
| 경로 일부만 다른 서버로 | location 단위 proxy_pass | 한 도메인 안에서 라우팅을 나눌 수 있습니다 |
주의할 점
include되지 않은 파일은 재적용해도 안 읽혀요. proxy_pass 슬래시는 URI를 넘기는 방식이 달라요. 기본 서버를 비우면 모르는 호스트가 다른 사이트로 가요. 문법 오류 파일을 재시작으로 반복하면 서비스가 내려간 채로 남아요.

자주 묻는 질문
재시작 필요, 검사 위치, server_name, include 순서, 잘못 고친 뒤 복구가 반복돼요.
설정을 바꾼 뒤에는 꼭 재시작해야 하나요?
대부분의 설정은 검사 후 재적용으로 충분해요. 바이너리나 프로세스 구성 변경은 문서의 절차를 따라요. 재시작을 기본으로 두지 마세요.
문법 검사는 어디서 실행하나요?
그 nginx가 읽는 설정 경로를 대상으로 서버나 컨테이너 안에서 실행해요. 호스트에서 다른 경로를 검사하면 운영과 다른 결과예요. 성공 메시지에 나온 파일 경로를 확인해요.
server_name에 도메인을 여러 개 적어도 되나요?
한 서버 블록에 여러 이름을 적을 수 있어요. 인증서와 로그를 나누려면 블록을 나누는 편이 좋아요. 기본 서버와 이름이 겹치지 않게 해요.
include로 파일을 나누면 순서가 중요한가요?
같은 지시어를 여러 파일에서 쓰면 나중에 읽힌 값이 남을 수 있어요. 디렉터리 와일드카드는 파일 이름 순인 경우가 많아요. 공통 값을 먼저, 사이트 예외를 나중에 읽히게 정리해요.
설정 파일을 잘못 고쳐서 서비스가 내려갔을 때는 어떻게 하나요?
백업 파일로 되돌리고 문법 검사 뒤 다시 기동하거나 재적용해요. 오류 메시지의 파일만 고치고 전체를 다시 검사해요. 재시작을 반복하기 전에 검사부터 해요.
출처
- nginx 공식 문서, Beginner's Guide: https://nginx.org/en/docs/beginners_guide.html
- nginx 공식 문서, ngx_http_core_module: https://nginx.org/en/docs/http/ngx_http_core_module.html
- nginx 공식 문서, Server names: https://nginx.org/en/docs/http/server_names.html
- nginx 공식 관리 가이드, Managing configuration files: https://docs.nginx.com/nginx/admin-guide/basic-functionality/managing-configuration-files/
재적용과 재시작의 차이는 nginx 재적용과 재시작의 차이에서 이어져요.