====== nginx使用与配置 ======

[[http://nginx.org/ | nginx]]（engine x）是一个 HTTP ，反向代理，邮件代理，通用 TCP/UDP 代理服务器，最初由 **Igor Sysoev** 设计实现。

===== 入门指南 =====

==== 基本概念 ====

nginx 有一个主进程和若干工作进程。主进程的主要作用是读取和评估配置信息，以及维护工作进程。工作进程对请求进行实际处理。nginx使用基于事件的模型和依赖于操作系统的机制来有效地在多个工作进程之间分配请求。工作进程的数量在配置文件中定义，可以固定为某个值，也可以根据可用CPU内核的数量进行自动调整。

==== 启动，停止和重新加载配置 ====

要启动nginx，运行可执行文件。启动后，就可以通过使用''-s''参数调用可执行文件来对其进行控制。使用以下语法：

  nginx -s signal

其中signal可能是以下之一：

  * stop — 快速关机
  * quit — 正常关机，即等待工作进程完成对当前请求的服务后停止nginx进程
  * reload — 重新加载配置文件
  * reopen — 重新打开日志文件

要获取所有正在运行的nginx进程的列表，可以使用ps实用程序，例如：

  ps -ax | grep nginx

==== 配置文件的结构 ====

nginx及其模块的工作方式在配置文件中确定。默认情况下，配置文件名为nginx.conf，并放置在目录%%/usr/local/nginx/conf%%、%%/etc/nginx%%或%%/usr/local/etc/nginx%%中。

nginx由模块组成，这些模块受配置文件中的指令控制。 指令分为简单指令和块指令。 一个简单的指令由指令名称和参数组成，用空格分隔，并以分号（;）结尾。块指令的结构与简单指令相同，但它不是以分号结尾，而是带有一组用花括号（{}）括起来的附加指令（instruction）。 如果一个块指令可以包含其他指令（directive），则将其称为上下文（如：events, http, server, location）。

在配置文件中，如果一个指令不在任何上下文中，则被视为在主上下文中。''events''和''http''指令位于主上下文中，''server''指令位于''http''中，而''location''指令位于''server''中。 

%%＃%%号后的内容被视为注释。


==== 基本应用 ====

=== 配置一个静态内容服务器 ===

网络服务器的一项重要任务是分发文件（例如图像或静态HTML页面）。这里将实现一个示例，其中将根据请求从不同的本地目录提供文件：%%/data/www%%（包含HTML文件）和%%/data/images%%（包含图像）。这将需要设置''http''指令内的''server''块指令，并在其中包含两个''location''块。配置文件的''server''块如下：

<code>
server {
    location / {
        root /data/www;
    }

    location /images/ {
        root /data;
    }
}
</code>

通常，配置文件可以包括多个''server''块，这些''server''块通过它们侦听的端口和服务器名称来区分。 一旦nginx决定了哪个服务器处理请求，它就会根据''server''块内定义的''location''指令的参数检查请求中指定的URI。

''location''块指定的前缀与请求中的URI进行匹配。对于匹配的请求，会将URI添加到''root''指令中指定的路径，以形成本地文件系统上所请求文件的路径。 如果有多个匹配的''location''块，nginx将选择前缀最长的''location''块。 上面的位置块提供了最短的前缀，长度为1，因此，只有在所有其他位置块均未提供匹配项时，才会使用该块。对于以 %%/images/%% 开始的请求，%%location /%%也能匹配，但%%location /images/%%有更长的前缀，所以匹配后者。 

=== 配置一个简单的代理服务器 ===

nginx的一经常的用途是作为代理服务器，这意味着服务器接收请求，将请求传递给被代理的服务器，然后从被代理服务器接收响应并将它们发送给客户端。

这里配置一个基本的代理服务器，该服务器对图像请求从本地目录中的文件提供服务，对所有其他请求发送到被代理的服务器。本示例中，两个服务器将定义在单个nginx实例上。

首先，在nginx配置文件中添加一个包含以下内容的''server''块来定义被代理服务器：

<code>
server {
    listen 8080;
    root /data/up1;

    location / {
    }
}
</code>

这里， ''root''指令位于''server''环境下，在匹配的''block''块中没有自己的''root''指令时使用这个路径。 

接下来，配置代理服务器：

<code>
server {
    location / {
        proxy_pass http://localhost:8080/;
    }

    location ~ \.(gif|jpg|png)$ {
        root /data/images;
    }
}
</code>

第一个''location''块，使用 ''proxy_pass''，并在参数中指定被代理服务器的协议、名称和端口。第二个''location''块，使用正则表达是匹配所有以%%.gif, .jpg, .png%%的URIs 并映射到 %%/data/images%%目录中。

nginx在选择 ''location''块是，首先检查指定了前缀的''location''块，并记住前缀最长的''location''块；然后检查正则表达式，如果有匹配，则选取这个''location''块，否则，选取前面记忆的''location''块。 

=== 配置FastCGI代理 ===

nginx可用于将请求路由到FastCGI服务器，该服务器运行各种框架和编程语言（例如PHP）构建的应用程序。

代理FastCGI服务器最基本的Nginx配置包括：使用''fastcgi_pass''指令而不是''proxy_pass''指令来代理CGI请求，以及使用''fastcgi_param''指令来设置传递给FastCGI服务器的参数。在PHP中，''SCRIPT_FILENAME''参数用于确定脚本名称，而''QUERY_STRING''参数用于传递请求参数。

<code>
server {
    location / {
        fastcgi_pass  localhost:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param QUERY_STRING    $query_string;
    }

    location ~ \.(gif|jpg|png)$ {
        root /data/images;
    }
}
</code>

这里，通过FastCGI协议，路由除静态图像外的所有请求到%%localhost:9000%%上的被代理服务器。

===== 命令行参数 =====

nginx 支持下列命令行参数:

  * -? | -h — 打印命令行帮助
  * -c file — 指定配置文件
  * -g directives — 设置全局配置指令
  * -p prefix — 设置nginx的路径前缀
  * -q — 在配置文件测试时，禁止non-error消息
  * -s signal — 向主进程发送信号
  * -t — 测试配置文件
  * -T — 测试配置文件，并输出到标准输出
  * -v — 打印nginx的版本
  * -V — 打印nginx的版本、编译器版本，配置参数

===== 模块配置 =====

==== 核心功能模块 ====

=== events ===

  * Syntax: 	events { ... }
  * Default: 	—
  * Context: 	main

为配置文件提供一个上下文环境，在其中可以指定影响连接处理的指令。

=== include ===

  * Syntax: 	include file | mask;
  * Default: 	—
  * Context: 	any

在当前文件中包含另一个文件或一组，被包含的文件需包含语法正确的指令和块。

=== user ===

  * Syntax: 	user user [group];
  * Default: 	user nobody nobody;
  * Context: 	main

定义工作进程使用的用户和组凭据。 如果省略组，则使用名称与用户相同的组。

=== worker_processes ===

  * Syntax: 	worker_processes number | auto;
  * Default: 	worker_processes 1;
  * Context: 	main

定义工作进程数。

最佳值取决于许多因素，包括（但不限于）CPU内核数，存储数据的硬盘驱动器数以及加载模式。 如有疑问，将其设置为可用的CPU内核数将是一个不错的开始（值“auto”将尝试自动检测可用的CPU内核数）。

==== ngx_http_core_module ====

=== 指令 ===

== alias ==

  * Syntax: 	alias path;
  * Default: 	—
  * Context: 	location

为''location''定义一个别名。

其中，''path''可以包含变量，但不能是%%$document_root%% 和 %%$realpath_root%%。

如果在使用正则表达式定义的''location''内使用别名，则该正则表达式应包含捕获，而别名应引用这些捕获。例如：

<code>
    location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
        alias /data/w3/images/$1;
    }
</code>

如果 ''location''的路径与该指令路径的后部分匹配，则最好使用''root''指令。

== HTTP ==

  * Syntax: 	http { ... }
  * Default: 	—
  * Context: 	main

为配置文件提供一个上下文环境，在其中可以指定HTTP的 ''server'' 指令。

== listen ==

  * Syntax: 	
    * listen address[:port] [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
    * listen port [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
    * listen unix:path [default_server] [ssl] [http2 | spdy] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
  * Default: 	listen *:80 | *:8000;
  * Context: 	server

设置IP的地址和端口，或UNIX-domain套接字的路径，服务器将在其上接受请求。 既可以指定地址和端口，也可以仅指定地址或端口；地址可以是主机名；IPv6 地址要加方括号；UNIX-domain套接字要使用''unix:''前缀。例如：

<code>
listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;
listen [::]:8000;
listen [::1];
listen unix:/var/run/nginx.sock;
</code>

如果仅指定了地址，则使用端口80；如果没有该指令，nginx有超级用户权限，则使用 %%*:80%%，否则使用%%*:8000%%。

== location ==

  * Syntax:
    * location [ = | ~ | ~* | ^~ ] uri { ... }
    * location @name { ... }
  * Default: 	—
  * Context: 	server, location

设置依赖于请求URI的配置。

''location''可以通过前缀字符串或正则表达式定义。正则表达式由前面的%%〜*%%修饰符（不区分大小写）或%%〜%%修饰符（不区分大小写）指定。

nginx匹配''location''块的过程是，首先检查使用前缀字符串定义的''location''块，选择并记住具有最长前缀的''location''块；然后按照在配置文件中出现的顺序检查正则表达式，正则表达式的搜索在第一个匹配项上终止，并使用相应的配置；如果未找到与正则表达式匹配的内容，则使用前面记住的前缀位置的配置。

除下述特殊情况外，''location''块可以嵌套使用。

正则表达式可以包含捕获，从而在其他指令中使用。

如果匹配的最长前缀''location''块有%%^~%%修饰符，则停止检查正则表达式。

使用%%=%%修饰符可以定义URI和''location''块的精确匹配。 如果找到完全匹配的内容，搜索将终止。这样的''location''块显然不能包含嵌套。

%%@%%前缀定义命名''location''块。 这样的位置不用于常规请求处理，而是用于请求重定向。 它们不能嵌套，也不能包含嵌套位置。

如果''location''块由以斜杠字符结尾的前缀字符串定义，并且请求由''proxy_pass''，''fastcgi_pass''，''uwsgi_pass''，''scgi_pass''，''memcached_pass''或''grpc_pass''中的一个处理，则将执行一个特殊处理。 

== root ==

  * Syntax: 	root path;
  * Default: 	root html;
  * Context: 	http, server, location, if in location

设置请求的根目录。

其中，''path''可以包含变量，但%%$document_root%% 和 %%$realpath_root%%除外。

只需通过将URI添加到root指令的值即可构造文件的路径。如果必须修改URI，则应使用alias指令。

== server ==

  * Syntax: 	server { ... }
  * Default: 	—
  * Context: 	http

设置虚拟服务器的配置。

基于IP的虚拟服务器（基于IP地址）和基于名称的虚拟服务器（基于“主机”请求标头字段）之间没有明确区分。然而，listen指令描述了应该接受连接的所有地址和端口，而server_name指令列出了所有服务器名称。

== server_name ==

  * Syntax: 	server_name name ...;
  * Default: 	server_name "";
  * Context: 	server

设置虚拟服务器的名称。

服务器名称可以包含一个星号（%%*%%）来代替名称的第一部分或最后一部分，这样的名称称为通配符名称。

也可以在服务器名称中使用正则表达式，在名称前加上波浪号（“〜”）。正则表达式可以包含捕获，这些捕获可以在其他指令中使用；正则表达式中的命名捕获会创建变量，可在其他指令中使用该变量。

也可以指定一个空服务器名称。给于给定的地址：端口对，它允许该服务器处理请求标头不带主机域的请求。这是默认设置。

在按名称搜索虚拟服务器的过程中，如果名称匹配多个指定的变体（例如，通配符名称和正则表达式匹配），则将按照以下优先级顺序选择第一个匹配的变体：

  * 确切的名字
  * 以星号开头的最长通配符名称
  * 最长的以星号结尾的通配符名称
  * 第一个匹配的正则表达式（按在配置文件中出现的顺序）

=== 内嵌变量 ===

ngx_http_core_module模块支持名称与Apache Server变量匹配的内嵌变量。 这些是代表客户端请求标头字段的变量，例如%%$http_user_agent%%，%%$http_cookie%%等，另外还有其他变量。

==== ngx_http_autoindex_module ====

ngx_http_autoindex_module模块处理以斜杠（''/''）结尾的请求，并生成目录列表。 通常，当ngx_http_index_module模块找不到index文件时，会将请求传递给ngx_http_autoindex_module模块。

=== autoindex ===

  * Syntax: 	autoindex on | off;
  * Default: 	autoindex off;
  * Context: 	http, server, location

启用或禁用目录列表输出。

=== autoindex_exact_size ===

  * Syntax: 	autoindex_exact_size on | off;
  * Default: 	autoindex_exact_size on;
  * Context: 	http, server, location

对于HTML格式，指定是在目录列表中输出确切的文件大小，还是四舍五入为KB，MB和GB。

=== autoindex_format ===

  * Syntax: 	autoindex_format html | xml | json | jsonp;
  * Default: 	autoindex_format html;
  * Context: 	http, server, location

设置目录列表的格式。

使用JSONP格式时，将使用回调请求参数设置回调函数的名称。 如果参数缺失或值为空，则使用JSON格式。

可以使用ngx_http_xslt_module模块转换XML输出。

=== autoindex_localtime ===

  * Syntax: 	autoindex_localtime on | off;
  * Default: 	autoindex_localtime off;
  * Context: 	http, server, location

对于HTML格式，指定输出目录列表中的时间使用本地时区还是UTC。

==== ngx_http_index_module ====

ngx_http_index_module模块处理以斜杠（''/''）结尾的请求。 此类请求也可以由ngx_http_autoindex_module和ngx_http_random_index_module模块处理。

=== index ===

  * Syntax: 	index file ...;
  * Default: 	index index.html;
  * Context: 	http, server, location

定义将用作index的文件。 文件名可以包含变量。 文件以指定顺序检查。 列表的最后一项可以是具有绝对路径的文件。 例如：

  index index.$geo.html index.0.html /index.html;

==== Other Module ====