웹 서버로 NGINX 및 NGINX Plus 구성하기

가상 서버 멀티 Tenancy, URI 및 응답 재작성, 변수 및 오류 처리를 지원하는 웹 서버로 NGINX 및 NGINX Plus 를 구성합니다.

이 문서에서는 웹 서버로 NGINX Open Source 및 NGINX Plus 를 구성하는 방법을 설명하며, 다음 섹션을 포함합니다.

가상 서버 설정
Location 구성
- NGINX Location 우선순위
변수 사용
특정 상태 코드 반환
요청에서 URI 재작성하기
HTTP 응답 재작성
오류 처리

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 지시문은 파일을 찾을 수 없는 경우 오류 메시지를 쓰지 않도록 합니다. 여기서는 누락된 파일이 올바르게 처리되므로 이 옵션이 필요하지 않습니다.

웹 서버로 NGINX 및 NGINX Plus 구성하기

1. 가상 서버 설정

2. Location 구성

2-1. NGINX Location 우선순위

3. 변수 사용

4. 특정 상태 코드 반환

5. 요청에서 URI 재작성하기

6. HTTP 응답 재작성

7. 오류 처리

Company

API Gateway

Contacts

웹 서버로 NGINX 및 NGINX Plus 구성하기

1. 가상 서버 설정

2. Location 구성

2-1. NGINX Location 우선순위

3. 변수 사용

4. 특정 상태 코드 반환

5. 요청에서 URI 재작성하기

6. HTTP 응답 재작성

7. 오류 처리

Newsletter