
웹 서버로 NGINX 및 NGINX Plus 구성하기
가상 서버 멀티 Tenancy, URI 및 응답 재작성, 변수 및 오류 처리를 지원하는 웹 서버로 NGINX 및 NGINX Plus 를 구성합니다.
이 문서에서는 웹 서버로 NGINX Open Source 및 NGINX Plus 를 구성하는 방법을 설명하며, 다음 섹션을 포함합니다.
Note: 이 문서의 정보는 NGINX Open Source와 NGINX Plus 모두에 적용됩니다. 읽기 쉽도록 이 글의 나머지 부분에서는 NGINX Plus에 대해서만 설명합니다.
높은 수준에서 NGINX Plus를 웹 서버로 구성하는 것은 처리하는 URL과 해당 URL의 리소스에 대한 HTTP 요청을 처리하는 방법을 정의하는 문제입니다. 더 낮은 수준에서 구성은 특정 도메인 또는 IP 주소에 대한 요청 처리를 제어하는 가상 서버 집합을 정의합니다. 구성 파일에 대한 자세한 내용은 NGINX Plus 및 NGINX 구성 파일 만들기를 참조하세요.
HTTP 트래픽에 대한 각 가상 서버는 특정 URI 집합의 처리를 제어하는 location이라는 특수 구성 인스턴스를 정의합니다. 각 Location은 이 Location에 매핑된 요청에 어떤 일이 발생하는지에 대한 자체 시나리오를 정의합니다. NGINX Plus는 이 프로세스에 대한 완전한 제어 기능을 제공합니다. 각 Location은 요청을 Proxy하거나 파일을 반환할 수 있습니다. 또한 URI를 수정하여 요청이 다른 위치나 가상 서버로 리다이렉션되도록 할 수 있습니다. 또한 특정 오류 코드를 반환할 수 있으며 각 오류 코드에 해당하는 특정 페이지를 구성할 수 있습니다.
목차
1. 가상 서버 설정
2. Location 구성
2-1. NGINX Location 우선순위
3. 변수 사용
4. 특정 상태 코드 반환
5. 요청에서 URI 재작성하기
6. HTTP 응답 재작성
7. 오류 처리
1. 가상 서버 설정
NGINX Plus 구성 파일에는 가상 서버를 정의하는 server 지시문이 하나 이상 포함되어야 합니다. NGINX Plus는 요청을 처리할 때 먼저 요청을 처리할 가상 서버를 선택합니다.
가상 서버는 예를 들어 http
컨텍스트에서 server
지시문으로 정의됩니다.
http {
server {
# Server configuration
}
}
여러 server
지시문을 http
컨텍스트에 추가하여 여러 가상 서버를 정의할 수 있습니다.
server
구성 블록에는 일반적으로 서버가 요청을 수신 대기하는 IP 주소와 포트(또는 Unix 도메인 소켓 및 경로)를 지정하는 listen
지시문이 포함됩니다. IPv4 주소와 IPv6 주소를 모두 사용할 수 있으며, IPv6 주소는 대괄호로 묶어야 합니다.
아래 예는 IP 주소 127.0.0.1 및 포트 8080에서 수신 대기하는 서버의 구성을 보여줍니다:
server {
listen 127.0.0.1:8080;
# Additional server configuration
}
포트를 생략하면 표준 포트가 사용됩니다. 마찬가지로 주소를 생략하면 서버는 모든 주소에서 수신 대기합니다. listen
지시문이 전혀 포함되지 않은 경우, superuser 권한에 따라 “표준” 포트는 80/tcp
이고 “기본” 포트는 8000/tcp
입니다.
요청의 IP 주소 및 포트와 일치하는 서버가 여러 대 있는 경우, NGINX Plus는 요청의 Host
헤더 필드를 server
블록의 server_name
지시문과 비교하여 테스트합니다. server_name
의 매개변수는 전체(정확한) 이름, 와일드카드 또는 정규식일 수 있습니다. 와일드카드는 시작, 끝 또는 둘 다에 별표(*
)가 포함된 문자 문자열로, 별표는 모든 문자 순서와 일치합니다. 정규 표현식 앞에 물결표(~
)를 붙이면 됩니다. 이 예는 정확한 이름을 보여줍니다.
server {
listen 80;
server_name example.org www.example.org;
#...
}
Host
헤더와 일치하는 이름이 여러 개 있는 경우 NGINX Plus는 다음 순서로 이름을 검색하여 가장 먼저 찾은 일치하는 이름을 사용하여 하나를 선택합니다.
- 정확한 명칭
- 별표로 시작하는 가장 긴 와일드카드(예:
*.example.org
) - 메일과 같이 별표로 끝나는 가장 긴 와일드카드(예:
mail.*
). - 첫 번째로 일치하는 정규식(설정 파일에 나타나는 순서대로)
Host
헤더 필드가 서버 이름과 일치하지 않으면 NGINX Plus는 요청이 도착한 포트의 기본 서버로 요청을 라우팅합니다. 기본 서버는 특정 서버를 기본값으로 명시적으로 지정하기 위해 listen
지시문에 default_server
매개변수를 포함하지 않는 한 nginx.conf 파일에 나열된 첫 번째 서버입니다.
server {
listen 80 default_server;
#...
}
2. Location 구성
NGINX Plus 는 요청 URI에 따라 다른 Proxy로 트래픽을 보내거나 다른 파일을 제공할 수 있습니다. 이러한 블록은 server
지시문 내에 location
지시문을 사용하여 정의합니다.
예를 들어 3개의 location
블록을 정의하여 가상 서버가 일부 요청을 하나의 Proxy 서버로 보내고, 다른 요청은 다른 Proxy 서버로 보내고, 나머지 요청은 로컬 파일 시스템에서 파일을 전달하여 제공하도록 지시할 수 있습니다.
NGINX Plus는 모든 location
지시문의 매개변수에 대해 요청 URI를 테스트하고 일치하는 위치에 정의된 지시문을 적용합니다. 각 location
블록 내부에는 일반적으로 (몇 가지 예외를 제외하고) 더 많은 location
지시문을 배치하여 특정 요청 그룹에 대한 처리를 더욱 세분화할 수 있습니다.
Note: 이 가이드에서 위치라는 단어는 단일 location
컨텍스트를 의미합니다.
location
지시문에 사용할 수 있는 매개변수에는 접두사 문자열(경로 명)과 정규식의 두 가지 유형이 있습니다. 요청 URI가 접두사 문자열과 일치하려면 접두사 문자열로 시작해야 합니다.
pathname 매개변수가 있는 다음 샘플 위치는 /some/path/document.html과 같이 /some/path/로 시작하는 요청 URI와 일치합니다. (/some/path가 해당 URI의 시작 부분에 오지 않기 때문에 /my-site/some/path와는 일치하지 않습니다.)
location /some/path/ {
#...
}
정규식 앞에는 대/소문자를 구분하여 일치시키는 경우 물결표(~
), 대/소문자를 구분하지 않고 일치시키는 경우 물결표-별표(~*
)가 붙습니다. 다음 예는 위치에 관계없이 .html 또는 .htm 문자열이 포함된 URI를 일치시킵니다.
location ~ \.html? {
#...
}
2-1. NGINX Location 우선순위
URI와 가장 일치하는 위치를 찾기 위해 NGINX Plus는 먼저 접두사 문자열이 있는 위치와 URI를 비교합니다. 그런 다음 정규식을 사용하여 위치를 검색합니다.
수식어가 ^~
가 사용되지 않는 한 정규식이 더 높은 우선순위를 갖습니다. 접두사 문자열 중 가장 구체적인 문자열(즉, 가장 길고 완전한 문자열)을 NGINX Plus가 선택합니다. 요청을 처리할 위치를 선택하는 정확한 로직은 다음과 같습니다.
- 모든 접두사 문자열에 대해 URI를 테스트합니다.
- (등호 기호)
=
수식어는 URI와 접두사 문자열이 정확히 일치하는 것을 정의합니다. 정확히 일치하는 항목이 발견되면 검색이 중지됩니다. ^~
수식어가 가장 긴 일치하는 접두사 문자열 앞에 붙는 경우 정규식은 확인되지 않습니다.- 일치하는 접두사 문자열 중 가장 긴 문자열을 저장합니다.
- 정규 표현식에 대해 URI를 테스트합니다.
- 일치하는 첫 번째 정규식이 발견되면 처리를 중지하고 해당 위치를 사용합니다.
- 일치하는 정규식이 없는 경우 저장된 접두사 문자열에 해당하는 위치를 사용합니다.
=
수식어의 일반적인 사용 사례는 /(슬래시)에 대한 요청입니다. /에 대한 요청이 빈번한 경우 = /
를 location 지시문의 매개변수로 지정하면 첫 번째 비교 후에 일치 항목 검색이 중지되므로 처리 속도가 빨라집니다.
location = / {
#...
}
location
컨텍스트에는 정적 파일을 제공하거나 요청을 Proxy된 서버로 전달하는 등 요청을 해결하는 방법을 정의하는 지시문이 포함될 수 있습니다. 다음 예제에서는 첫 번째 location
컨텍스트와 일치하는 요청은 /data 디렉터리의 파일을 제공하고 두 번째와 일치하는 요청은 www.example.com
도메인에 대한 콘텐츠를 호스팅하는 Proxy 서버로 전달합니다.
server {
location /images/ {
root /data;
}
location / {
proxy_pass http://www.example.com;
}
}
root
지시문은 서비스할 정적 파일을 검색할 파일 시스템 경로를 지정합니다. 경로에 해당 위치와 연결된 요청 URI를 추가하여 제공할 정적 파일의 전체 이름을 얻습니다. 위의 예에서 /images/example.png에 대한 요청에 대한 응답으로 NGINX Plus는 /data/images/example.png 파일을 전달합니다.
proxy_pass
지시문은 구성된 URL로 액세스한 Proxy 서버로 요청을 전달합니다. 그러면 Proxy된 서버의 응답이 클라이언트로 다시 전달됩니다. 위의 예제에서는 /images/로 시작하지 않는 URI를 가진 모든 요청이 Proxy된 서버로 전달됩니다.
3. 변수 사용
구성 파일에 변수를 사용하여 정의된 상황에 따라 NGINX Plus가 요청을 다르게 처리하도록 할 수 있습니다. 변수는 런타임에 계산되고 지시문의 매개변수로 사용되는 지정된 값입니다. 변수는 이름 앞에 $
(달러) 기호로 표시됩니다. 변수는 현재 처리 중인 요청의 속성 등 NGINX의 상태에 따라 정보를 정의합니다.
핵심 HTTP
변수와 같은 여러 가지 사전 정의된 변수가 있으며, set
, map
, geo
지시문을 사용하여 사용자 정의 변수를 정의할 수 있습니다. 대부분의 변수는 런타임에 계산되며 특정 요청과 관련된 정보를 포함합니다. 예를 들어 $remote_addr
에는 클라이언트 IP 주소가 포함되고 $uri
에는 현재 URI 값이 저장됩니다.
4. 특정 상태 코드 반환
일부 웹사이트 URI는 페이지가 일시적 또는 영구적으로 이동된 경우와 같이 특정 오류 또는 리다이렉션 코드가 포함된 응답을 즉시 반환해야 합니다. 가장 쉬운 방법은 return 지시문을 사용하는 것입니다. 예를 들면 다음과 같습니다.
location /wrong/url {
return 404;
}
return
의 첫 번째 매개변수는 응답 코드입니다. 선택적 두 번째 매개변수는 리다이렉션의 URL(코드 301
, 302
, 303
및 307
의 경우) 또는 응답 본문에서 반환할 텍스트일 수 있습니다. 예를 들면 다음과 같습니다.
location /permanently/moved/url {
return 301 http://www.example.com/moved/here;
}
return
지시문은 location
및 server
컨텍스트에 모두 포함될 수 있습니다.
5. 요청에서 URI 재작성하기
하나의 선택 매개변수와 두 개의 필수 매개변수가 있는 rewrite
지시문을 사용하여 요청을 처리하는 동안 요청 URI를 여러 번 수정할 수 있습니다. 첫 번째(필수) 매개변수는 요청 URI가 일치해야 하는 정규식입니다. 두 번째 매개변수는 일치하는 URI를 대체할 URI입니다. 세 번째 매개변수(선택 사항)는 추가 rewrite
지시문의 처리를 중지하거나 리다이렉션(코드 301
또는 302
)을 보낼 수 있는 Flag입니다.
예를 들면 다음과 같습니다.
location /users/ {
rewrite ^/users/(.*)$ /show?user=$1 break;
}
이 예제에서 볼 수 있듯이, 사용자
가 정규식 일치를 통해 캡처하는 두 번째 매개변수는 다음과 같습니다.
server
및 location
컨텍스트 모두에 여러 개의 rewrite
지시문을 포함할 수 있습니다. NGINX Plus는 지시문이 발생하는 순서대로 하나씩 실행합니다. server
컨텍스트의 rewrite
지시문은 해당 컨텍스트가 선택되면 한 번 실행됩니다.
NGINX는 일련의 rewrite
지시문을 처리한 후 새 URI에 따라 location
컨텍스트를 선택합니다. 선택한 위치에 rewrite
지시문이 포함되어 있으면 차례로 실행됩니다. URI가 이러한 지시문 중 하나라도 일치하면 정의된 모든 rewrite
지시문이 처리된 후 새 위치에 대한 검색이 시작됩니다.
다음 예제는 return
지시문과 함께 rewrite
지시문을 보여줍니다.
server {
#...
rewrite ^(/download/.*)/media/(\w+)\.?.*$ $1/mp3/$2.mp3 last;
rewrite ^(/download/.*)/audio/(\w+)\.?.*$ $1/mp3/$2.ra last;
return 403;
#...
}
이 예제 구성은 두 세트의 URI를 구분합니다. /download/some/media/file과 같은 URI는 /download/some/mp3/file.mp3로 변경됩니다. 마지막
Flag로 인해 후속 지시문(두 번째 rewrite
및 return
지시문)은 건너뛰지만 NGINX Plus는 요청을 계속 처리하며, 다른 URI를 갖게 됩니다. 마찬가지로 /download/some/audio/file과 같은 URI는 /download/some/mp3/file.ra로 대체됩니다. URI가 두 rewrite
지시문 중 하나와 일치하지 않으면 NGINX Plus는 403
오류 코드를 클라이언트에 반환합니다.
rewrite
지시문 처리를 중단하는 두 가지 매개변수가 있습니다.
last
– 현재server
또는location
컨텍스트에서rewrite
지시문의 실행을 중지하지만 NGINX Plus는 재작성된 URI와 일치하는 위치를 검색하고 새 위치의 모든rewrite
지시문을 적용합니다(즉, URI를 다시 변경할 수 있습니다).break
–break
지시문과 마찬가지로 현재 컨텍스트에서rewrite
지시문 처리를 중지하고 새 URI와 일치하는 위치에 대한 검색을 취소합니다. 새 위치의rewrite
지시문은 실행되지 않습니다.
6. HTTP 응답 재작성
때때로 HTTP 응답의 콘텐츠를 다시 작성하거나 변경하여 한 문자열을 다른 문자열로 대체해야 하는 경우가 있습니다. sub_filter
지시문을 사용하여 적용할 재작성을 정의할 수 있습니다. 이 지시문은 변수와 대체 체인(Chain)을 지원하므로 더 복잡한 변경이 가능합니다.
예를 들어 Proxy 이외의 서버를 참조하는 절대 링크를 변경할 수 있습니다.
location / {
sub_filter /blog/ /blog-staging/;
sub_filter_once off;
}
또 다른 예는 http://
에서 https://
로 스키마를 변경하고 localhost
주소를 요청 헤더 필드의 호스트 명으로 바꿉니다. sub_filter_once
지시문은 한 위치 내에서 sub_filter
지시문을 연속적으로 적용하도록 NGINX에 지시합니다.
location / {
sub_filter 'href="http://127.0.0.1:8080/' 'href="https://$host/';
sub_filter 'img src="http://127.0.0.1:8080/' 'img src="https://$host/';
sub_filter_once on;
}
Note: 다른 sub_filter
와 일치하는 항목이 발생할 경우 이미 sub_filter
로 수정된 응답의 일부가 다시 대체되지 않도록 합니다.
7. 오류 처리
error_page
지시문을 사용하면 오류 코드와 함께 사용자 정의 페이지를 반환하거나, 응답에 다른 오류 코드를 대체하거나, 브라우저를 다른 URI로 리다이렉션하도록 NGINX Plus를 구성할 수 있습니다. 다음 예제에서 error_page
지시문은 404
오류 코드와 함께 반환할 페이지(/404.html)를 지정합니다.
error_page 404 /404.html;
Note: 이 지시문은 오류를 즉시 반환하는 것이 아니라( return
지시문이 이를 처리합니다), 오류가 발생했을 때 어떻게 처리할지 지정하는 것입니다. 오류 코드는 Proxy된 서버에서 발생하거나 NGINX Plus에서 처리하는 동안 발생할 수 있습니다(예: 404
는 클라이언트가 요청한 파일을 찾을 수 없을 때 발생합니다).
다음 예제에서는 NGINX Plus가 페이지를 찾을 수 없는 경우 코드 301
을 코드 404
로 대체하고 클라이언트를 http:/example.com/new/path.html로 리다이렉션합니다. 이 구성은 클라이언트가 여전히 이전 URI에서 페이지에 액세스하려고 할 때 유용합니다. 301
코드는 페이지가 영구적으로 이동했음을 브라우저에 알려주며, 브라우저는 페이지로 돌아갈 때 이전 주소를 새 주소로 자동 교체해야 합니다.
location /old/path.html {
error_page 404 =301 http:/example.com/new/path.html;
}
다음 구성은 파일을 찾을 수 없을 때 요청을 Backend로 전달하는 예제입니다. error_page
지시문의 등호 뒤에 상태 코드가 지정되지 않았으므로 클라이언트에 대한 응답에는 Proxy된 서버가 반환한 상태 코드(반드시 404
일 필요는 없습니다)가 있습니다.
server {
...
location /images/ {
# Set the root directory to search for the file
root /data/www;
# Disable logging of errors related to file existence
open_file_cache_errors off;
# Make an internal redirect if the file is not found
error_page 404 = /fetch$uri;
}
location /fetch/ {
proxy_pass http://backend/;
}
}
error_page
지시문은 파일을 찾을 수 없을 때 내부 리다이렉션을 수행하도록 NGINX Plus에 지시합니다. error_page
지시문의 마지막 매개변수에 있는 $uri 변수는 리다이렉션에서 전달되는 현재 요청의 URI를 보유합니다.
예를 들어 /images/some/file을 찾을 수 없는 경우 /fetch/images/some/file로 대체되고 위치에 대한 새 검색이 시작됩니다. 결과적으로 요청은 두 번째 location
컨텍스트에서 끝나고 http://backend/로 Proxy
됩니다.
open_file_cache_errors
지시문은 파일을 찾을 수 없는 경우 오류 메시지를 쓰지 않도록 합니다. 여기서는 누락된 파일이 올바르게 처리되므로 이 옵션이 필요하지 않습니다.