原文地址：http://nginx.com/resources/admin-guide/web-server/

NGINX Web Server
Nginx web server

This section describes:

• the most common configuration of a web server
• how to set up virtual servers and define locations for request processing
• how to use variables
• how to return specific status codes
• how to rewrite the URI of a request
• how to configure HTTP error pages

本章讨论：

• 最经常使用的 web server的配置
• 怎样搭建虚拟主机以及定义请求过程的位置
• 怎样使用变量
• 怎样设定返回状态码
• 怎样重写一个请求的URL
• 怎样配置HTTP错误页

Overall, the configuration of NGINX as a web server is a matter of defining which URLs it can process and how it processes them. On a lower level, the configuration consists of a set of virtual servers that are responsible for processing requests for particular domains or IP addresses.

Each virtual server defines special configuration instances called locations that control processing of specific sets of URIs. Each location defines its own scenario of what happens to requests that are mapped to this location. NGINX provides full control over this process. Each location can proxy the request or return a file. In addition, the URI can be modified, so that the request is redirected to another location or virtual server. Also, a specific error code can be returned and you can configure a specific page to corresponds to each error code.

总的来说，Nginx 作为一个Webserver的配置几乎相同就是定义哪些URL能处理和怎样处理。

底层点说，这个配置由一组负责处理特定域名或者IP地址的请求的虚拟server。

每个虚拟server定义了一个称为locations的特有的配置实例来控制能处理的指定的URL。

每个location定义了对映射到本location的URL处理方式。Nginx通过这个过程提供全局控制。每个location能代理这个请求或者返回一个文件。另外，这个URL还能够被改动，把这个请求重定向到别的location或者虚拟server。相同。能够返回特定的错误码，而且你能够为每个错误码配置一个对应的页面。

Configuration File
配置文件

Configuring NGINX is similar to other services in that it has a text-based configuration file written in a particular format. By default this file is named nginx.conf. The location of your nginx.conf depends on the package system used to install NGINX and the operating system. Typically, it is one of /usr/local/nginx/conf, /etc/nginx, or /usr/local/etc/nginx directories.

配置Nginx类似于其它的服务，它有一个基于文本的有着特殊格式的配置文件。默认情况下这个文件名称为nginx.conf。

你的nginx.conf的位置取决于安装Nginx使用的包管理系统和操作系统。通常在/usr/local/nginx/conf, /etc/nginx 或者 /usr/local/etc/nginx 当中一个文件夹中。

The configuration file is created using directives and parameters. Each directive ends with a semicolon. You may also add additional instructions within 大braces. Below are some examples.

配置文件是使用指令和參数来创建的。每一个指令以分号结束。也能够在括号内加入其它说明，看以下演示样例：

user             nobody;
error_log        logs/error.log notice;
worker_processes 1;

Using include, you can also split configuration into a hierarchy of files, including file contents:

使用include。能够把配置分散到不同层级的文件里，包括文件内容：

include mime.types;

There are a few special directives referred to as contexts. These contexts are events, http,server, and location.

有几个特殊的指令被称为上下文环境，这些上下文环境有 events, http,server, 和 location.。

Any directives placed outside of the contexts are considered to be in the main context. The example below shows a full configuration file using contexts.

任务一个在上下文环境之外的指令被当作主环境。

以下这个样例採用上下文环境展示了一个完事的配置文件。

user nobody; # a directive in the ‘main‘ context

events {
    # configuration of events
}

http {

    # Configuration specific to HTTP and affecting all virtual servers

    server {
        # configuration of virtual server 1

        location /one {
            # configuration for processing URIs with ‘/one‘
        }

        location /two {
            # configuration for processing URIs with ‘/two‘
        }
    }

    server {
        # configuration of virtual server 2
    }
}

As you might guess, configuration related to HTTP resides within the http context. The server context configures a specific virtual server within the http context. Finally, the location context is used within the server contect to instruct NGINX to process a particular set of URIs.

你可能会想，跟HTTP有关的配置放在http上下文环境中。server 这个上下文环境在http上下文中配置一个指定的虚拟服务器。

最后，location上下文环境在server上下文中用以指导Nginx去处理特定一些的URL。

In most cases, a context that is defined inside another context will inherits its directives. When that happens, and you then declare the the same directive on the current level, the directive on the current level will override the inherited one. For more information on context inheritence see the proxy_set_header documentation.

多数情况下，定义在还有一个上下文环境里的上下文将继承全部指令。在这样的情况下。假设你在当前层里声明了相同的指令，当前层的指令将会覆盖继承下来的。有关上下文继承很多其它信息请看：proxy_set_header documentation

For the changes in the configuration file to take effect you have two options. First you can simply restart nginx. Alternatively, you can send the reload signal to upgrade the configuration without interrupting the processing of current requests.

有两种办法能够使配置文件的更改生效。第一种是简单粗暴的重新启动Nginx。还有一种。你能够发送一个重载信号以更新配置而不用打断当前请求处理进程。

Setting Up a Virtual Server
搭建虚拟server

To process HTTP requests, your NGINX configuration file should define at least one virtual server. When NGINX processes a request, it will first select the virtual server that will serve the request.

为了处理HTTP请求，你的Nginx配置文的应该定义至少一个虚拟server。当Nginx要处理一个请求时，首选虚拟server来处理该请求。

Servers are defined using the server directive, which is placed in the http context, for example:

定义服务器使用 server 指令。放在 http 上下文环境中，比如：

http {
    server {
        # Server configuration
    }
}

It is possible to add multiple server directives into the http context to define multiple virtual servers.

在http上下文中能够加入多个server指令来定义多个虚拟服务器；

The server directive should also include a listen directive. This directive specifies the IP address and port (or Unix domain socket and path) which the server will listen. The IP address can be either IPv4 or IPv6. Keep in mind that IPv6 must be specified in the square brackets.

server 指令还应该包括一个 listen 指令。这个指令指定服务器监听的IP地址和port（或者Unix域套接字和路径）。IP 地址能够是IPv4或IPv6的。记住IPv6必需要使用方括号指定。

The example below shows configuration of a server that listens on the 127.0.0.1 address and8080 port:

以下这个样例配置了一个server监听127.0.0.1这个地址和8080port：

server {
    listen 127.0.0.1:8080;
    # The rest of server configuration
}

If a port is omitted, the standard port will be used. Likewise, if an address is omitted, the server will listen on all addresses. Note that if the listen directive is not specified, the “standard” port is 80/tcp and the “default” port is 8000/tcp, depending on superuser privileges.

假设port參数省略了。就使标准port。

还有，假设地址省略了，server就监听全部地址。注意假设listen 指令没有设置。那么“标准”port为 80/tcp 和 默认“port”为 8000/tcp。使用哪个取决于超级管理员权限。

If there are several servers that match the IP address and port of the request, NGINX tests the request’s “Host” header field against the server_name directives of the server blocks. The parameter of this directive can be an exact name, a wildcard, or a regular expression. A wildcard name includes an asterisk that starts or finishes the name and will match any string. A regular expression should be preceded with a tilde (~). The example below illustrates the case of an exact name.

假设一个请求匹配上多个服务器的IP地址和port，那么NGINX查找请求头里的“Host”字段来相应server块里的server_name 指令。

这个指令的參数能够是一个确切的名字，一个通配符或者一个正則表達式。

一个在开头或者结尾包括星号的通配符名字能匹配不论什么字符串。一个正则须要以波浪号（~）开头。

以下举了一个使用精确名称的样例：

server {
    listen      80;
    server_name example.org www.example.org;
    …
}

If several names match the “Host” header, NGINX selects one, trying the names in the following order:

假设多个名称匹配上“Host”头。Nginx使用下列的顺序选择一个：

1. Exact name. 
2. Longest wildcard name starting with an asterisk, such as *.example.org.
3. Longest wildcard name ending with an asterisk, such as mail.*.
4. First matching regular expression (in order of appearance in the configuration file).

1. 精确匹配
2. 以星号开头的最长的通配符名字，比如：*.example.org。

3. 以星号结束的最长的通配符名字，比如：mail.*。
4. 第一个匹配上正則表達式的（以配置文件中的位置为顺序）。

If the “Host” header field does not match a server name, NGINX will route the request to the default server for this port. The default server is the first one listed in the nginx.conf file. This will be overridden if the default_server parameter is set in the listen directive within a server context. An example is given below.

假设“Host”头字段匹配不上不论什么一个主机名，Nginx将把这个请求路由到该port的默认主机。默认主机是nginx.conf文件中的第一个。

假设某个主机上下文里的listen指令后跟了default_server參数。那么这个默认主机将被覆盖。实比例如以下：

server {
    listen      80 default_server;
    …
}

Configuring Locations
配置locations

One aspect NGINX includes in the virtual server configuration is the ability to send traffic to different proxies or serve different files based on the request URIs. These blocks are defined using the location directive placed within a server directive.

Nginx虚拟主机配置里的当中一个牛逼之处在于依据请求URLs把流量分发到不同的代理或主机。这些功能的组件在server指令中的location指令里定义。

For example, you can configure the virtual server to send a portion of requests to a proxied server, send another portion to a different proxied server, and serve the rest with files from the local file system. To accommodate this you configure the virtual server to define three location blocks, one for each case.

比如，你能够配置虚拟主机把请求的一部分发给一个代理server。还有一部分发送给还有一台代理server，剩下的通过本地文件系统的文件来处理。要实现这些功能，你须要在虚拟主机里定义三个location组件。每部分一个。

NGINX tests request URIs against the parameters of all location directives and applies the directives that reside within the selected location. Inside each location block, it is usually possible (with a few exceptions) to place even more location directives to further split the configuration into parts that are relevant to specific groups of requests.

Nginx针对全部location指令里的參数来检測请求URL，应用选中的location中的全部指令。在每一个location组件中， 通常（也有例外）会放置很多其它的location指令进一步把配置依据特定的请求群组分成几个部分。

NOTE: In this guide, the word “location” refers to a single location directive and its context.

The parameter of the location directive can be a prefix string or a regular expression. A URI should start with a prefix string in order to match it.

注意：在这篇指南中，”location” 这个词指一个单独的location指令和他的上下文环境。location 指令的參数能够是一个前缀字符串也能够是一个正則表達式。

一个URI应该从一个前缀字符串開始匹配。

Below is an example of a location with a prefix string parameter. It will match requests such as/some/path/document.html.

以下是一个曾经缀字符串为參数的location，它将匹配如/some/path/document.html 这种请求。

location /some/path/ {
    …
}

A regular expression is preceded with a tilde (~). In the following example the location which includes a regular expression in the parameter matches URIs that include “.html” or “.htm”.

一个正則表達式是以波浪号（~）開始的，以下这包括了正則表達式的參数的location实例将匹配包括”.html”或者”.htm”的URI。

location ~ \.html?
 {
#译者注：此处几个意思，应该是 ~\.htm?
 才对吧
    …
}

Higher priority is given to regular expressions, unless the “^~” modifier is used. Among the prefix strings NGINX selects the most specific one (that is, the longest and most complete string). The exact logic for selecting a location to process a request is given below:

正則表達式的优先级更高。除非使用了”^~”修饰符。

在前缀字符串里Nginx选择最详细的（即匹配最长和最多的字符串）。选择location来处理请求的确切逻辑例如以下：

1. Test the URI against all prefix strings.
2. The “=” modifier defines an exact match of the URI and a prefix string. If the exact match is found, the search stops.
3. If the “^~” modifier prepends the longest matching prefix string, the regular expressions are not checked.
4. Store the longest matching prefix string.
5. Start testing the URI against regular expressions.
6. Break on the first matching regular expression and use the corresponding location.
7. If no regular expression matches, use the location corresponding to the stored prefix string.

1. 针对全部前缀匹配字符串检測URL
2. “=“修饰符定义了一个URL的精确匹配的一个前缀字符串。假设找到精确匹配。搜索停止。
3. 假设最长匹配前缀串的前面有”^~"，那这个正則表達式就不检測。
4. 保存最长匹配前缀串。

5. 開始针对正則表達式检測URL。
6. 在第一个匹配的正則表達式处退出搜索，而且使用这个location。
7. 假设没有正则匹配上。那么就使用已存储的前缀串指向的location。

A typical example of using the “=” modifier is with the usage of “/”. If the “/” request needs to be served often, specifying the location parameter as “= /” will speed up processing of these requests. As noted above, this is due to the search being stopped after the first comparison.

一个典型的”=“修饰符的使用是和”/“一起使用的。假设”/“请求常常被訪问。那么设location的參数为”=/“能加快处理这些请求的速度。如前面所提到的，这是由于搜索在第一次比較之后就停止了。

location = / {
    ...
}

A location can contain directives that allow you to define how to resolve a request—serve a static file or pass the request to a proxy. In the following example a virtual server has two locations showing each resolution.

location 里的指令能够定义假设处理一个请求——提供一个静态文件还是把请求传递给一个代理。

以下这个实例中虚拟主机有两个location分别实现这两种方案。

server {
    location / {
        proxy_pass http://www.example.com;
    }

    location /images/ {
        root /data;
    }
}

The proxy_pass directive passes the request to the proxied server located at the URL you supply. The response from the proxied server will then be passed back to the client. In the example above, all requests with URIs that do not start with “/images/” will be passed to the proxied server.

 proxy_pass 指令把你请求的请求传递给你提供的URL相应的代理server。代理server处理后的响应又返回给client。上例中，全部不以”/images/“开头的URL请求都将传递给代理server。

The root directive specifies the file system path in which the static files are located. The request URI associated with the location is then added to the path to obtain the static files. In the example above, in response to the URI “/images/example.png”, NGINX will send the “/data/images/example.png” file.

 root 指令指定静态文件在文件系统中的位置。分配到该location的请求URL被加入到路径后来获取静态文件。上例中，Nginx会把”/data/images/example.png”文件发送到URI"/images/exmple.png”的响应里。

Variables
变量

The nginx.conf file also allow you to set variables. Variables help you create configurations that behave differently depending on defined circumstances. Variables are named values that are calculated at run time and are used in parameters of directives. A variable is denoted by the “$” sign at the beginning of its name. Variables define information based upon nginx’s state, such as the properties of the currently processed request.

nginx.conf文件中也能够设置变量。

变量帮你创建依据情况而行为可变的配置。命名过的变量将在执行时计算出值以作指令的參数。

变量使用 “$” 符号在其名字前进行标记。变量定义的信息取决于Nginx的状态，比如前面处理的请求的属性。

There are plenty of predefined variables, such as the core HTTP variables, but you can also define custom variables using the set, map, and geo directives. Most variables are computed at run time and contain information related to a specific request. For example, $remote_addr contains the client IP address and $uri holds the current URI value.

有大量如 core HTTP 变量的提前定义变量。然而你也能够使用 set, map, 和 geo 指令定义自己定义变量。

多数变量在执行时计算得出而且包括特定请求的相关信息。比如，$remote_addr 包括了clientIP地址，还有$uri收保存当前URI的值。

Returning Specific Codes

返回指定状态码

Some website URIs may require immediate return of a response with a specific error or redirect code. An example of this would be if a page has been moved temporarily or permanently. The easiest way to do this is to use the return directive. For example:

有些站点的URL须要直接返回一个带有指定错误码或者重定向码的响应。比如当一个页面被暂时或永久删除的时候。

实现这个功能最简单的方法就是直接使用  return  指令。比如：

location /wrong/url {
    return 404;
}

The first parameter of return is a response code. Additionally, the directive may have a second parameter set to the URL of a redirect (for codes 301, 302, 303, and 307) or the text to return in the response body. For example:

return  的第一个參数是响应码。另外 ，它也能够使用第二个參数设置为URL或者重定向（对于码301,302.302,和307）或者放在响应体里返回的文本。比如：

location /permanently/moved/url {
    return 301 http://www.example.com/moved/here;
}

The return directive can be specified in either location or server context.

return指令在location或server上下文环境里使用。

Rewriting the URI
重写URI

A request URI can be modified multiple times during request processing through the use of the

rewrite. This directive has two required and one optional parameters. The first parameter is a regular expression to test the request URI. The second parameter is the URI to replace the current one if it matches the regular expression. The optional third parameter is a flag that can indicate to stop processing further rewrite directives. For example:

一个请求的URL能够在请求处理过程中使用 rewrite 指令进行多次改动。这个指令有两个必须的參数和一个可选參数。第一个參数是检測请求URI的正则式。第二个參数是用来替换匹配了正则式的URI的。

第三个可选參数是一个指示是否停止进程执行其它的重写指令的标志位。

location /users/ {
    rewrite ^/users/(.*)$ /show?
user=$1 break;
}

As this example shows, the second parameter users captures though matching of regular expressions.

如例所看到的，第二个參数通过匹配正则工捕捉”users”。

The rewrite directives can be used in both the server and location levels. You can include multiple rewrite directives in the same server or location. The rewrite directives are executed one-by-one in the order of their appearance. The rewrite directives on the virtual server level are executed once when that virtual server is selected.

rewrite指令能同一时候在server和location层使用。能够在同一个server或location里放多条rewrite指令。

rewrite指令依据前面顺序一条一条运行。配置在虚拟主机上的rewrite运行一量虚拟主机被选中就运行。

Once this set of rewriting instruction is processed, a location is selected according to the new URI. Then if a selected location contains rewrite directives, they are executed in turn. If the URI matches any of those, then a search for the new location starts after all defined rewrite directives are processed.

一旦这组重写指令集被运行了。就依据新的URI选择一个location。假设被选中的location包括rewrite指令集，就轮流的运行。假设RUI匹配上当中一个，全部定义的rewrite 指令运行完后就開始搜索新的location。

The following example shows rewrite directives in combination with a return directive.

下述样例展示 了rewrite 指令集与return指令组合使用。

server {
    ...
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  last;
    return  403;
    ...
}

This example configuration distinguishes two types of URIs. URIs such as/download/some/media/file are changed to /download/some/mp3/file.mp3. The second rewrite and return are skipped (due to the last flag) but NGINX continues processing the request, which now has a different URI. Similarly, such URIs as /download/some/audio/file are replaced with /download/some/mp3/file.ra. If a URI doesn’t match any of these cases, the return directive comes into action and returns a 403 error code.

上例中。配置了两类可区分的URI，URI如/download/some/media/file被改动为 /download/some/mp3/file.mp3。第二个rewrite指令和return指令会跳过（由于last标志位）可是Nginx会继续处理这个拥有新URI的请求。相同的，URL如/download/some/audio/file则被替换为/download/some/mp3/file.ra。

假设一个URI匹配不上不论什么一个rewrite，那return指令就生效并返回一个403错误码。

There are two parameters that interrupt processing of rewrite directives:

有两个參数能中断rewrite指令集的进程：

• last stops execution of the rewrite directives in the current virtual server or location, but the search for a location continues. So the rewrite directives in the new location will be executed.
• last 停止当前虚拟主机或location中的rewrite指令集，可是继续搜索新的location。因此新的location中的rewrite指令集还是会被运行。

• The break parameter as well as the break directive stop processing of rewrite directives on the current level and stop the search of a location. So the rewrite directives in the new location will not be executed.
• break參数同 break 指令一样停止当前层的rewrite指令集进程而且停止location的搜索，因此新的location里的rewrite指令集将不会被运行。

Configuring Error Pages
配置错误页

To configure the pages returned for particular error codes, use the error_page directive. This directive allows you to set rules for a particular error code, such as the URI of a page to return as a response for a particular error code. You could also set error code to substitute for another one. In the following example, the error_page directive sets a page to return in case of a 404 error.

要为特定的错误码配置页面，使用error_page 指令。这个指令能够为特定的错误码设置规则。比如对一个特定的错误码返回的页面的URI。你也能够使用一个错误码替换还有一个。下例中。error_page 指令为404错误码设置了一个返回页面。

error_page 404 /404.html;

Note that this directive does not mean that the error will be returned immediately (this is what return does), but simply provides settings for treating errors when they occur. The error code can come from a proxied server or appear as a result of processing a request by NGINX (for example, 404 pops up when NGINX can’t find a file requested by the client).

注意这个指令并不是意味着这个错误会直接返回（那是return干的事），而仅仅是为处理错误的发生提供配置。这个错误码可能来自一个代理server也可能来自Nginx对请求处理的结果（比如，当Nginx找不到client所请求的文件的时候弹出404）。

In the following example, if a page is not found, the 301 code replaces the 404 code, and a redirect to a different URL is made.

以下这个样例中，假设一个页面找不到。使用301码替换404，而且重定向到一个制作好的不同的URL。

location /old/path.html {
    error_page 404 =301 http:/example.com/new/path.html;
}

This type of replacement may be useful when a page has a new URI, but clients still try to access it with the old address. The 301 code informs a browser that the page has moved permanently. Setting a 301 code tells the browser to replace the old address with the new one automatically upon return.

这类的替换可能会用在一个页面更新了URI。可是client还一直訪问旧地址的情况。301码用于通知浏览器一个页面被永久的删除了。在返回时自己主动设置一个301码告诉浏览器更换旧地址为新地址。

The following configuration is an example of passing a request to the backend when a file is not found. Since the error_page directive below has no status code specified after the equal sign, the response the client gets will have the status code returned by the proxied server (not necessarily 404).

以下这个配置举例当文件找不到的时候把请求发送给backend。

由于error_page指令以下在等号后没有指定状态码，因此client拿到的则代理server返回的状态码（不一定是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/;
    }
}

Note that the parameter set for the error_page directive here includes the $uri variable, which holds the URI of the current request. The open_file_cache_errors directive prevents writing an error message if a file is not found. This is not necessary here since missing files will be correctly handled. Due to the use of the error_page directive NGINX makes an internal redirect if a file is not found. More specifically, the /images/some/file URI is replaced with/fetch/images/some/file and a new search for a location starts. As a result, the request ends up in the second location and is proxied.

注意这里设置的error_page指令的參数包括了$uri这个变量，这个变量保存了当前请求的URI的值。 假设文件找不到，open_file_cache_errors 指令阻止写错误消息。这里没有必要由于丢失的文件能被正确的处理。由于这里使用error_page让Nginx做了一个内部重定向假设文件不存在的话。更详细的说，images/some/fileURI会被替换为/fetch/images/some/file而且对开启一个新的对location的搜索。结果是这个请求在第二个location结束并被代理了。