Nginx学习笔记（持续更新）

1.  Nginx原理及基础概念

1.1 Nginx的进程模型如下图所示：

 

• Nginx从容重启操作流程：

        首先master进程在接到信号后，会先重新加载配置文件，然后再启动新的worker进程，并向所有老的worker进程发送信号，告诉他们可以光荣退休了。新的worker在启动后，就开始接收新的请求，而老的worker在收到来自master的信号后，就不再接收新的请求，并且在当前进程中的所有未处理完的请求处理完成后，再退出。

1.2 Nginx性能高效的原因

• nginx采用了异步非阻塞的方式来处理请求，采用epoll触发机制。
• nginx为了更好地利用多核特性，提供了cpu亲缘性的绑定选项，可以将某一个进程绑定在某一个核上，这样就不会因为进程的切换带来cache的失效。Nginx还有很多为了高效作出的优化。

       1.3 Nginx基础概念

        1.3.1 connection：

        首先，nginx在启动时，会解析配置文件，得到需要监听的端口与ip地址，然后在nginx的master进程里面，先初始化好这个监控的socket(创建socket，设置addr，reuse等选项，绑定到指定的ip地址端口，再listen)，然后再fork出多个子进程出来，然后子进程会竞争accept新的连接。此时，客户端就可以向nginx发起连接了。当客户端与服务端通过三次握手建立好一个连接后，nginx的某一个子进程会accept成功，得到这个建立好的连接的socket，然后创建nginx对连接的封装，即ngx_connection_t结构体。接着，设置读写事件处理函数并添加读写事件来与客户端进行数据的交换。最后，nginx或客户端来主动关掉连接，到此，一个连接就寿终正寝了。

        nginx通过设置worker_connectons来设置每个进程支持的最大连接数。如果该值大于nofile，那么实际的最大连接数是nofile，nginx会有警告。nginx在实现时，是通过一个连接池来管理的，每个worker进程都有一个独立的连接池，连接池的大小是worker_connections。这里的连接池里面保存的其实不是真实的连接，它只是一个worker_connections大小的一个ngx_connection_t结构的数组。并且，nginx会通过一个链表free_connections来保存所有的空闲ngx_connection_t，每次获取一个连接时，就从空闲连接链表中获取一个，用完后，再放回空闲连接链表里面。

        对于HTTP请求本地资源来说，能够支持的最大并发数量是worker_connections * worker_processes，而如果是HTTP作为反向代理来说，最大并发数量应该是worker_connections * worker_processes/2。因为作为反向代理服务器，每个并发会建立与客户端的连接和与后端服务的连接，会占用两个连接。

        nginx的处理得先打开accept_mutex选项，此时，只有获得了accept_mutex的进程才会去添加accept事件，也就是说，nginx会控制进程是否添加accept事件。nginx使用一个叫ngx_accept_disabled的变量来控制是否去竞争accept_mutex锁。在第一段代码中，计算ngx_accept_disabled的值，这个值是nginx单进程的所有连接总数的八分之一，减去剩下的空闲连接数量，得到的这个ngx_accept_disabled有一个规律，当剩余连接数小于总连接数的八分之一时，其值才大于0，而且剩余的连接数越小，这个值越大。再看第二段代码，当ngx_accept_disabled大于0时，不会去尝试获取accept_mutex锁，并且将ngx_accept_disabled减1，于是，每次执行到此处时，都会去减1，直到小于0。不去获取accept_mutex锁，就是等于让出获取连接的机会，很显然可以看出，当空余连接越少时，ngx_accept_disable越大，于是让出的机会就越多，这样其它进程获取锁的机会也就越大。不去accept，自己的连接就控制下来了，其它进程的连接池就会得到利用，这样，nginx就控制了多进程间连接的平衡了。

1.3.2 request

        对于nginx来说，一个请求是从ngx_http_init_request开始的，在这个函数中，会设置读事件为ngx_http_process_request_line，也就是说，接下来的网络事件，会由ngx_http_process_request_line来执行。从ngx_http_process_request_line的函数名，我们可以看到，这就是来处理请求行的，正好与之前讲的，处理请求的第一件事就是处理请求行是一致的。通过ngx_http_read_request_header来读取请求数据。然后调用ngx_http_parse_request_line函数来解析请求行。

        当请求头读取完成后，就开始进行请求的处理了。nginx通过ngx_http_request_t来保存解析请求与输出响应相关的数据。

        在解析完请求行后，nginx会设置读事件的handler为ngx_http_process_request_headers，然后后续的请求就在ngx_http_process_request_headers中进行读取与解析。ngx_http_process_request_headers函数用来读取请求头，跟请求行一样，还是调用ngx_http_read_request_header来读取请求头，调用ngx_http_parse_header_line来解析一行请求头，解析到的请求头会保存到ngx_http_request_t的域headers_in中，headers_in是一个链表结构，保存所有的请求头。而HTTP中有些请求是需要特别处理的，这些请求头与请求处理函数存放在一个映射表里面，即ngx_http_headers_in，在初始化时，会生成一个hash表，当每解析到一个请求头后，就会先在这个hash表中查找，如果有找到，则调用相应的处理函数来处理这个请求头。比如:Host头的处理函数是ngx_http_process_host。

        当nginx解析到两个回车换行符时，就表示请求头的结束，此时就会调用ngx_http_process_request来处理请求了。ngx_http_process_request会设置当前的连接的读写事件处理函数为ngx_http_request_handler，然后再调用ngx_http_handler来真正开始处理一个完整的http请求。这里可能比较奇怪，读写事件处理函数都是ngx_http_request_handler，其实在这个函数中，会根据当前事件是读事件还是写事件，分别调用ngx_http_request_t中的read_event_handler或者是write_event_handler。由于此时，我们的请求头已经读取完成了，之前有说过，nginx的做法是先不读取请求body，所以这里面我们设置read_event_handler为ngx_http_block_reading，即不读取数据了。刚才说到，真正开始处理数据，是在ngx_http_handler这个函数里面，这个函数会设置write_event_handler为ngx_http_core_run_phases，并执行ngx_http_core_run_phases函数。ngx_http_core_run_phases这个函数将执行多阶段请求处理，nginx将一个http请求的处理分为多个阶段，那么这个函数就是执行这些阶段来产生数据。因为ngx_http_core_run_phases最后会产生数据，所以我们就很容易理解，为什么设置写事件的处理函数为ngx_http_core_run_phases了。在这里，我简要说明了一下函数的调用逻辑，我们需要明白最终是调用ngx_http_core_run_phases来处理请求，产生的响应头会放在ngx_http_request_t的headers_out中，这一部分内容，我会放在请求处理流程里面去讲。nginx的各种阶段会对请求进行处理，最后会调用filter来过滤数据，对数据进行加工，如truncked传输、gzip压缩等。这里的filter包括header filter与body filter，即对响应头或响应体进行处理。filter是一个链表结构，分别有header filter与body filter，先执行header filter中的所有filter，然后再执行body filter中的所有filter。在header filter中的最后一个filter，即ngx_http_header_filter，这个filter将会遍历所有的响应头，最后需要输出的响应头在一个连续的内存，然后调用ngx_http_write_filter进行输出。ngx_http_write_filter是body filter中的最后一个，所以nginx首先的body信息，在经过一系列的body filter之后，最后也会调用ngx_http_write_filter来进行输出(有图来说明)。

        这里要注意的是，nginx会将整个请求头都放在一个buffer里面，这个buffer的大小通过配置项client_header_buffer_size来设置，如果用户的请求头太大，这个buffer装不下，那nginx就会重新分配一个新的更大的buffer来装请求头，这个大buffer可以通过large_client_header_buffers来设置，这个large_buffer这一组buffer，比如配置4 8k，就是表示有四个8k大小的buffer可以用。注意，为了保存请求行或请求头的完整性，一个完整的请求行或请求头，需要放在一个连续的内存里面，所以，一个完整的请求行或请求头，只会保存在一个buffer里面。这样，如果请求行大于一个buffer的大小，就会返回414错误，如果一个请求头大小大于一个buffer大小，就会返回400错误。在了解了这些参数的值，以及nginx实际的做法之后，在应用场景，我们就需要根据实际的需求来调整这些参数，来优化我们的程序了。

 

1.3.3  keepalive

        http请求是请求应答式的，如果我们能知道每个请求头与响应体的长度，那么我们是可以在一个连接上面执行多个请求的，这就是所谓的长连接，但前提条件是我们先得确定请求头与响应体的长度。对于请求来说，如果当前请求需要有body，如POST请求，那么nginx就需要客户端在请求头中指定content-length来表明body的大小，否则返回400错误。也就是说，请求体的长度是确定的，那么响应体的长度呢？先来看看http协议中关于响应body长度的确定：

• 对于http1.0协议来说，如果响应头中有content-length头，则以content-length的长度就可以知道body的长度了，客户端在接收body时，就可以依照这个长度来接收数据，接收完后，就表示这个请求完成了。而如果没有content-length头，则客户端会一直接收数据，直到服务端主动断开连接，才表示body接收完了。
•  而对于http1.1协议来说，如果响应头中的Transfer-encoding为chunked传输，则表示body是流式输出，body会被分成多个块，每块的开始会标识出当前块的长度，此时，body不需要通过长度来指定。如果是非chunked传输，而且有content-length，则按照content-length来接收数据。否则，如果是非chunked，并且没有content-length，则客户端接收数据，直到服务端主动断开连接。

        从上面，我们可以看到，除了http1.0不带content-length以及http1.1非chunked不带content-length外，body的长度是可知的。此时，当服务端在输出完body之后，会可以考虑使用长连接。能否使用长连接，也是有条件限制的。如果客户端的请求头中的connection为close，则表示客户端需要关掉长连接，如果为keep-alive，则客户端需要打开长连接，如果客户端的请求中没有connection这个头，那么根据协议，如果是http1.0，则默认为close，如果是http1.1，则默认为keep-alive。如果结果为keepalive，那么，nginx在输出完响应体后，会设置当前连接的keepalive属性，然后等待客户端下一次请求。当然，nginx不可能一直等待下去，如果客户端一直不发数据过来，岂不是一直占用这个连接？所以当nginx设置了keepalive等待下一次的请求时，同时也会设置一个最大等待时间，这个时间是通过选项keepalive_timeout来配置的，如果配置为0，则表示关掉keepalive，此时，http版本无论是1.1还是1.0，客户端的connection不管是close还是keepalive，都会强制为close。

        如果服务端最后的决定是keepalive打开，那么在响应的http头里面，也会包含有connection头域，其值是”Keep-Alive”，否则就是”Close”。如果connection值为close，那么在nginx响应完数据后，会主动关掉连接。所以，对于请求量比较大的nginx来说，关掉keepalive最后会产生比较多的time-wait状态的socket。一般来说，当客户端的一次访问，需要多次访问同一个server时，打开keepalive的优势非常大，比如图片服务器，通常一个网页会包含很多个图片。打开keepalive也会大量减少time-wait的数量。

1.3.4  pipe

        如果客户端要提交多个请求，对于keepalive来说，那么第二个请求，必须要等到第一个请求的响应接收完全后，才能发起，这和TCP的停止等待协议是一样的，得到两个响应的时间至少为2*RTT。而对pipeline来说，客户端不必等到第一个请求处理完后，就可以马上发起第二个请求。得到两个响应的时间可能能够达到1*RTT。nginx是直接支持pipeline的，但是，nginx对pipeline中的多个请求的处理却不是并行的，依然是一个请求接一个请求的处理，只是在处理第一个请求的时候，客户端就可以发起第二个请求。这样，nginx利用pipeline减少了处理完一个请求后，等待第二个请求的请求头数据的时间。其实nginx的做法很简单，前面说到，nginx在读取数据时，会将读取的数据放到一个buffer里面，所以，如果nginx在处理完前一个请求后，如果发现buffer里面还有数据，就认为剩下的数据是下一个请求的开始，然后就接下来处理下一个请求，否则就设置keepalive。

1.3.5  lingering_close

        lingering_close，字面意思就是延迟关闭，也就是说，当nginx要关闭连接时，并非立即关闭连接，而是先关闭tcp连接的写，再等待一段时间后再关掉连接的读。为什么要这样呢？我们先来看看这样一个场景。nginx在接收客户端的请求时，可能由于客户端或服务端出错了，要立即响应错误信息给客户端，而nginx在响应错误信息后，大分部情况下是需要关闭当前连接。nginx执行完write()系统调用把错误信息发送给客户端，write()系统调用返回成功并不表示数据已经发送到客户端，有可能还在tcp连接的write buffer里。接着如果直接执行close()系统调用关闭tcp连接，内核会首先检查tcp的read buffer里有没有客户端发送过来的数据留在内核态没有被用户态进程读取，如果有则发送给客户端RST报文来关闭tcp连接丢弃write buffer里的数据，如果没有则等待write buffer里的数据发送完毕，然后再经过正常的4次分手报文断开连接。所以,当在某些场景下出现tcp write buffer里的数据在write()系统调用之后到close()系统调用执行之前没有发送完毕，且tcp read buffer里面还有数据没有读，close()系统调用会导致客户端收到RST报文且不会拿到服务端发送过来的错误信息数据。那客户端肯定会想，这服务器好霸道，动不动就reset我的连接，连个错误信息都没有。

        在上面这个场景中，我们可以看到，关键点是服务端给客户端发送了RST包，导致自己发送的数据在客户端忽略掉了。所以，解决问题的重点是，让服务端别发RST包。再想想，我们发送RST是因为我们关掉了连接，关掉连接是因为我们不想再处理此连接了，也不会有任何数据产生了。对于全双工的TCP连接来说，我们只需要关掉写就行了，读可以继续进行，我们只需要丢掉读到的任何数据就行了，这样的话，当我们关掉连接后，客户端再发过来的数据，就不会再收到RST了。当然最终我们还是需要关掉这个读端的，所以我们会设置一个超时时间，在这个时间过后，就关掉读，客户端再发送数据来就不管了，作为服务端我会认为，都这么长时间了，发给你的错误信息也应该读到了，再慢就不关我事了，要怪就怪你RP不好了。当然，正常的客户端，在读取到数据后，会关掉连接，此时服务端就会在超时时间内关掉读端。这些正是lingering_close所做的事情。协议栈提供 SO_LINGER 这个选项，它的一种配置情况就是来处理lingering_close的情况的，不过nginx是自己实现的lingering_close。lingering_close存在的意义就是来读取剩下的客户端发来的数据，所以nginx会有一个读超时时间，通过lingering_timeout选项来设置，如果在lingering_timeout时间内还没有收到数据，则直接关掉连接。nginx还支持设置一个总的读取时间，通过lingering_time来设置，这个时间也就是nginx在关闭写之后，保留socket的时间，客户端需要在这个时间内发送完所有的数据，否则nginx在这个时间过后，会直接关掉连接。当然，nginx是支持配置是否打开lingering_close选项的，通过lingering_close选项来配置。 那么，我们在实际应用中，是否应该打开lingering_close呢？这个就没有固定的推荐值了，如Maxim Dounin所说，lingering_close的主要作用是保持更好的客户端兼容性，但是却需要消耗更多的额外资源（比如连接会一直占着）。

2.  nginx启动，重启以及关闭命令

2.1 停止操作

1. 从容停止nginx：kill –QUIT 主进程号
2. 快速停止nginx：kill –TERM 主进程号
3. 强制停止pkill -9 nginx

         另外，若在nginx.conf配置了pid文件存放路径，则该文件存放的就是Nginx​​

       2.2 平滑重启

            1. kill –HUP 主进程号或进程号文件路径, 或者/usr/local/nginx/sbin/nginx -s reload
            2. 检查修改过的nginx.conf配置文件是否正确，命令如下：nginx -t -c /usr/local/nginx/conf/nginx.conf
                或者/usr/local/nginx/sbin/nginx -t

3. Nginx变量

1. 在 Nginx 配置中，变量只能存放一种类型的值，因为也只存在一种类型的值，那就是字符串。
2. 并非所有的配置指令都支持”变量插值”。事实上，指令参数是否允许变量插值，取决于该指令的实现模块。
3.  Nginx变量的创建和赋值操作发生在全然不同的时间阶段。Nginx变量的创建只能发生在Nginx配置加载或Nginx启动的时候；而赋值操作则只会发生在请求实际处理的时候。
4. Nginx变量名的可见范围虽然是整个配置，但是每个请求都有所有变量的独立副本。
5.  不是所有的Nginx变量都拥有存放值的容器。拥有存放值容器的变量在Nginx和心中被称为”被索引的”（indexed）；反之，则被称为”未索引的”（non-indexed）。
6. 只在实际使用对象时才计算对象值的技术，在计算领域被称为”惰性求值”.
7. 一些变量操作

• 变量赋值：set $a hello;
• 变量插值：set $b “$a, $a;” #利用已有的nginx变量来构造新的nginx变量;
• 将变量的值作为当前请求的相应体输出: echo “foo: $foo”;

    8. Nginx常用的内建变量

• $uri   获取当前请求的URI（经过解码，并且不含请求参数）
• $request_uri    获取请求最原始的URI（未经解码，并且包含请求参数）
• $arg_XXX    变量群，匹配当前请求名为XXX的URI参数的值（未经解码，大小写不敏感，例如arg_name可以匹配name,NAME,Name等参数
• 更多变量群cookie_XXX，$http_XXX，$sent_http_XXX详见ngx_http_core模块官方文档。
• 许多内建变量都是只读的，对只读变量进行赋值是应当绝对避免的。 

   9. Nginx常用指令（包括标准nginx指令和第三方模块提供的配置指令)

• 想对URI参数值中的%XX这样的编码序列进行解码，可以使用第三方ngx_set_misc模块提供的set__uri配置指令，示例如下：

location /test {
        set__uri $name $arg_name; #两个参数，只会对第二个参数的编码序列进行解码
        set__uri $class $arg_class;


        echo "name: $name";
        echo "class: $class";
}

   10. 几个重要实例：

• 实例1：Nginx变量的一个常见误区是认为变量容器的生命期是与location配置块绑定的。

server {
        listen 8080;
        location /foo {
            set $a hello;
            echo_exec /bar;  #也可用rewrite ^ /bar;进行内部跳转
        }

        location /bar {
            echo "a = [$a]";
        }
}
​

$ curl localhost:8080/foo
a = [hello]
        分析：这里我们在 location /foo 中，使用第三方模块 ngx_echo 提供的 echo_exec 配置指令，发起到 location /bar 的“内部跳转”。所谓“内部跳转”，就是在处理请求的过程中，于服务器内部，从一个 location 跳转到另一个 location 的过程。这不同于利用 HTTP 状态码301 和 302 所进行的“外部跳转”，因为后者是由 HTTP 客户端配合进行跳转的，而且在客户端，用户可以通过浏览器地址栏这样的界面，看到请求的 URL 地址发生了变化。内部跳转和Bourne Shell（或 Bash）中的 exec 命令很像，都是“有去无回”。另一个相近的例子是 C 语言中的 goto 语句。
        既然是内部跳转，当前正在处理的请求就还是原来那个，只是当前的 location 发生了变化，所以还是原来的那一套 Nginx 变量的容器副本。对应到上例，如果我们请求的是 /foo 这个接口，那么整个工作流程是这样的：先在 location /foo 中通过 set 指令将 $a 变量的值赋为字符串 hello，然后通过 echo_exec 指令发起内部跳转，又进入到 location /bar 中，再输出 $a 变量的值。因为 $a 还是原来的 $a，所以我们可以期望得到 hello 这行输出。测试证实了这一点：
结论：Nginx变量值容器的生命期是与当前正在处理的请求绑定的，而与location无关。

• 实例2：每个请求都有所有变量容器的独立副本，只不过当前请求既可以是”主请求”，也可以是”子请求”。即便是子请求之间，同名变量一般也不会互相干扰。

location /main {

        set $var main;

        echo_location /foo;    #发起子请求

        echo_location /bar;        #发起子请求

        echo "main: $var";

}

location /foo {

        set $var foo;

        echo "foo: $var";

}

location /bar {

        set $var bar;

        echo "bar: $var";

}

$ curl 'http://localhost:8080/main'
    foo: foo
    bar: bar
   main: main
分析：在这个例子中，我们分别在 /main，/foo 和 /bar 这三个 location 配置块中为同一名字的变量，$var，分别设置了不同的值并予以输出。特别地，我们在 /main 接口中，故意在调用过 /foo 和 /bar 这两个“子请求”之后，再输出它自己的 $var 变量的值。请求 /main 接口的结果是这样的：
备注：但是有一些Nginx模块发起的“子请求”却会自动共享其“父请求”的变量值容器，比如第三方模块ngx_auth_request(auth_request指令)

4. Nginx配置指令的执行顺序

        Nginx 处理请求的过程一共划分为 11 个阶段，按照执行顺序依次是 post-read、server-rewrite、find-config、rewrite、post-rewrite、preaccess、access、post-access、try-files、content 以及 log.

• post-read（读取内容请求阶段）

        接收完请求头之后的第一个阶段，它位于uri重写之前，实际上很少有模块会注册在该阶段，默认的情况下，该阶段被跳过；Nginx读取并解析完请求头之后就立即开始运行。例如ngx_realip就在post-read阶段注册了处理程序，它的功能是迫使Nginx认为当前请求的来源地址是指定的某一个请求头的值。

• server-rewrite（Server请求地址重写阶段）

        server级别的uri重写阶段，也就是该阶段执行处于server块内，location块外的重写指令，前面的章节已经说明在读取请求头的过程中nginx会根据host及端口找到对应的虚拟主机配置；当ngx_rewrite模块的set配置指令直接书写在server配置块中时，基本上都是运行在server-rewrite阶段。

•  find-config（配置查找阶段）

        寻找location配置阶段，该阶段使用重写之后的uri来查找对应的location，值得注意的是该阶段可能会被执行多次，因为也可能有location级别的重写指令；这个阶段并不支持Nginx模块注册处理程序，而是由Nginx核心来完成当前请求与location配置块之间的配对工作。

• rewrite（Location请求地址重写阶段)

        location级别的uri重写阶段，该阶段执行location基本的重写指令，也可能会被执行多次；当ngx_rewrite模块的指令用于location块时，便是运行在这个rewrite阶段。另外，ngx_set_misc（设置md5、encode_base64）模块的指令，还有ngx_lua模块的set_by_lua指令和rewrite_by_lua指令也在此阶段。

• post_rewrite（请求地址重写提交阶段）

        location级别重写的后一阶段，用来检查上阶段是否有uri重写，并根据结果跳转到合适的阶段；

• preaccess（访问权限检查准备阶段)

        标准模块ngx_limit_req和ngx_limit_zone就运行在此阶段，前者可以控制请求的访问频度，而后者可以限制访问的并发度。

• access（访问权限检查阶段）

        标准模块ngx_access、第三方模块ngx_auth_request以及第三方模块ngx_lua的access_by_lua指令就运行在这个阶段，配置指令多是执行访问控制性质的任务，比如检查用户的访问权限，检查用户的来源IP是否合法。

        访问权限控制阶段，比如基于ip黑白名单的权限控制，基于用户名密码的权限控制等。

•  post-access（访问权限检查提交阶段）

        主要用于配合access阶段实现标准ngx_http_core模块提供的配置指令satisfy的功能。

        satisfy all（与关系）

        satisfy any（或关系） 

• try-files（配置项try_files处理阶段）

        专门用于实现标准配置指令try_files的功能。如果前N-1个参数所对应的文件系统对象都不存在，try-files阶段就会立即发起“内部跳转”到最后一个参数（即第N个参数）所指定的URI。

• content（内容产生阶段）

        Nginx的content阶段是所有请求处理阶段中最为重要的一个，因为运行在这个阶段的配置指令都肩负着生成内容并输出HTTP响应的使命。

•  log（日志模块处理阶段）

        记录日志。

5. Nginx处理用户请求时的不同阶段示例：（按先后顺序）

5.1 post-read阶段

•  最先执行的post-read阶段在Nginx读取并解析完请求头之后就立即开始运行。这个阶段像前面介绍过的rewrite阶段那样支持Nginx模块注册处理程序。比如标准模块ngx_realip就在post-read阶段注册了处理程序，它的功能是迫使Nginx认为当前请求的来源地址是指定的某一个请求头的值。下面的这例子就是用了ngx_realip模块提供的set_real_ip_from和real_ip_header这两条配置指令：

server {
        listen 8080;
        set_real_ip_from 127.0.0.1; #set_real_ip_from指令规定了来源地址的改写操作只对那些来自127.0.0.1的请求生效
        real_ip_header   X-My-IP;

        location /test {
            set $addr $remote_addr;
            echo "from: $addr";
        }
}

        这里的配置是让Nginx把那些来自127.0.0.1的所有请求的来源地址，都改写为请求头X-My-IP所指定的值。同时该例使用了标准内建变量$remote_addr来输出当前请求的来源地址，以确认是否被成功改写。

        首先在本地请求一下这个/test接口：

$ curl -H 'X-My-IP: 1.2.3.4' localhost:8080/test

        from: 1.2.3.4

        这里使用了 curl 工具的 -H 选项指定了额外的 HTTP 请求头 X-My-IP: 1.2.3.4. 从输出可以看到， $remote_addr 变量的值确实在 rewrite 阶段就已经成为了 X-My-IP 请求头中指定的值，即 1.2.3.4. 那么 Nginx 究竟是在什么时候改写了当前请求的来源地址呢？答案是：在 post-read 阶段。由于 rewrite 阶段的运行远在 post-read 阶段之后，所以当在 location 配置块中通过 set 配置指令读取 $remote_addr 内建变量时，读出的来源地址已经是经过 post-read 阶段篡改过的。

        如果在请求上例中的 /test 接口时没有指定 X-My-IP 请求头，或者提供的 X-My-IP 请求头的值不是合法的 IP 地址，那么 Nginx 就不会对来源地址进行改写，例如：（此外，如果从另外一台机器访问了这个/test接口，那么即使指定了合法的X-My-IP请求头，也不会触发Nginx对来源地址进行改写）

$ curl localhost:8080/test

    from: 127.0.0.1

 $ curl -H 'X-My-IP: abc' localhost:8080/test

    from: 127.0.0.1

•  server-rewrite阶段

     当ngx_rewrite模块的配置指令直接书写在server配置块中时，基本上都是运行在server-rewrite阶段。例子如下：

server {
        listen 8080;
         location /test {
             set $b "$a, world";
             echo $b;
        }
        set $a hello;
}

      这里，配置语句 set $a hello 直接写在了 server 配置块中，因此它就运行在 server-rewrite 阶段。而 server-rewrite 阶段要早于 rewrite 阶段运行，因此写在 location 配置块中的语句 set $b "$a, world" 便晚于外面的 set $a hello 语句运行。该例的测试结果证明了这一点：

$ curl localhost:8080/test

    hello, world

    由于 server-rewrite 阶段位于 post-read 阶段之后，所以 server 配置块中的 set 指令也就总是运行在 ngx_realip 模块改写请求的来源地址之后。来看下面这个例子：

server {
         listen 8080;
         set $addr $remote_addr;
         set_real_ip_from 127.0.0.1;
         real_ip_header   X-Real-IP;
         location /test {
            echo "from: $addr";
        }
}

请求 /test 接口的结果如下：

$ curl -H 'X-Real-IP: 1.2.3.4' localhost:8080/test

    from: 1.2.3.4

    在这个例子中，虽然 set 指令写在了 ngx_realip 的配置指令之前，但仍然晚于 ngx_realip 模块执行。所以 $addr 变量在 server-rewrite 阶段被 set 指令赋值时，从 $remote_addr 变量读出的来源地址已经是经过改写过的了。

• find-config阶段

    这个阶段并不支持Nginx模块注册处理程序，而是由核心来完成当前请求与location配置块之间的配对工作。因此，对于运行在find-config阶段之前的post-read和server-rewrite阶段来说，只有server配置块以及更外层作用域中的配置指令才会起作用。这就是为什么只有写在server 配置块中的 ngx_rewrite 模块的指令才会运行在 server-rewrite 阶段，这也是为什么前面所有例子中的 ngx_realip 模块的指令也都特意写在了 server 配置块中，以确保其注册在post-read 阶段的处理程序能够生效。

• rewrite阶段

    由于Nginx已经在find-config阶段完成了当前请求与location的配对，所以从rewrite阶段开始，location配置块中的指令便可以产生作用。当ngx_rewrite模块的指令用于location块中时，便是运行在这个rewrite阶段。另外，ngx_set_misc模块的指令也是如此，还有ngx_lua模块的set_by_lua指令和rewrite_by_lua指令也不例外。

• post-rewrite阶段

    post-rewrite阶段也不支持Nginx模块注册处理程序，而是由Nginx核心完成rewrite阶段所要求的内部跳转操作。示例如下：

server {
        listen 8080;
        location /foo {
            set $a hello;
            rewrite ^ /bar;
        }

        location /bar {
            echo "a = [$a]";
        }
}

        这里在 location /foo 中通过 rewrite 指令把当前请求的 URI 无条件地改写为 /bar，同时发起一个“内部跳转”，最终跳进了 location /bar 中。这里比较有趣的地方是“内部跳转”的工作原理。“内部跳转”本质上其实就是把当前的请求处理阶段强行倒退到 find-config 阶段，以便重新进行请求 URI 与 location 配置块的配对。比如上例中，运行在 rewrite 阶段的 rewrite 指令就让当前请求的处理阶段倒退回了 find-config 阶段。由于此时当前请求的 URI 已经被rewrite 指令修改为了 /bar，所以这一次换成了 location /bar 与当前请求相关联，然后再接着从 rewrite 阶段往下执行。

        不过这里更有趣的地方是，倒退回 find-config 阶段的动作并不是发生在 rewrite 阶段，而是发生在后面的 post-rewrite 阶段。上例中的 rewrite 指令只是简单地指示 Nginx 有必要在 post-rewrite 阶段发起“内部跳转”。这个设计对于 Nginx 初学者来说，或许显得有些古怪：“为什么不直接在 rewrite 指令执行时立即进行跳转呢？”答案其实很简单，那就是为了在最初匹配的 location 块中支持多次反复地改写 URI，例如：

location /foo {
        rewrite ^ /bar;
        rewrite ^ /baz;
        echo foo;
}

location /bar {
        echo bar;
}

location /baz {
        echo baz;
}

        这里在 location /foo 中连续把当前请求的 URI 改写了两遍：第一遍先无条件地改写为 /bar，第二遍再无条件地改写为 /baz. 而这两条 rewrite 语句只会最终导致 post-rewrite 阶段发生一次“内部跳转”操作，从而不至于在第一次改写 URI 时就直接跳离了当前的 location 而导致后面的 rewrite 语句没有机会执行。请求 /foo 接口的结果证实了这一点：

$ curl localhost:8080/foo

baz

        从输出结果可以看到，上例确实成功地从 /foo 一步跳到了 /baz 中。如果启用 Nginx “调试日志”的话，还可以从 find-config 阶段生成的 location 块的匹配信息中进一步证实这一点：

$ grep 'using config' logs/error.log

[debug] 89449#0: *1 using configuration "/foo"

[debug] 89449#0: *1 using configuration "/baz"

        我们看到，对于该次请求，Nginx 一共只匹配过 /foo 和 /baz 这两个 location，从而只发生过一次“内部跳转”。

当然，如果在 server 配置块中直接使用 rewrite 配置指令对请求 URI 进行改写，则不会涉及“内部跳转”，因为此时 URI 改写发生在 server-rewrite 阶段，早于执行 location 配对的find-config 阶段。比如下面这个例子：

server {
     listen 8080;
     rewrite ^/foo /bar;
     location /foo {
        echo foo;
    }
     location /bar {
        echo bar;
    }
}

        这里，我们在 server-rewrite 阶段就把那些以 /foo 起始的 URI 改写为 /bar，而此时请求并没有和任何 location 相关联，所以 Nginx 正常往下运行 find-config 阶段，完成最终的location 匹配。如果我们请求上例中的 /foo 接口，那么 location /foo 根本就没有机会匹配，因为在第一次（也是唯一的一次）运行 find-config 阶段时，当前请求的 URI 已经被改写为/bar，从而只会匹配 location /bar. 实际请求的输出正是如此：

$ curl localhost:8080/foo

bar

Nginx “调试日志”可以再一次佐证我们的结论：

$ grep 'using config' logs/error.log

[debug] 92693#0: *1 using configuration "/bar"

可以看到，Nginx 总共只进行过一次 location 匹配，并无“内部跳转”发生。

• preaccess阶段

    标准模块ngx_limit_req和ngx_limit_zone运行在此阶段，前者可以控制请求的访问频度，而后者可以限制访问的并发度。

•  access阶段

    标准模块ngx_access、第三方模块ngx_auth_request以及第三方模块ngx_lua的access_by_lua指令运行在这个阶段。

• post-access阶段

        post-access阶段也不支持Nginx模块注册处理程序，主要用于配合access阶段实现标准ngx_http_core模块提供的配置指令satisfy的功能。

        对于多个 Nginx 模块注册在 access 阶段的处理程序， satisfy 配置指令可以用于控制它们彼此之间的协作方式。比如模块 A 和 B 都在 access 阶段注册了与访问控制相关的处理程序，那就有两种协作方式，一是模块 A 和模块 B 都得通过验证才算通过，二是模块 A 和模块 B 只要其中任一个通过验证就算通过。第一种协作方式称为 all 方式（或者说“与关系”），第二种方式则被称为 any 方式（或者说“或关系”）。默认情况下，Nginx 使用的是 all 方式。下面是一个例子：

location /test {
    satisfy all;
    deny all;
    access_by_lua 'ngx.exit(ngx.OK)';
    echo something important;
}

这里，我们在 /test 接口中同时配置了 ngx_access 模块和 ngx_lua 模块，这样 access 阶段就由这两个模块一起来做检验工作。其中，语句 deny all 会让 ngx_access 模块的处理程序总是拒绝当前请求，而语句 access_by_lua 'ngx.exit(ngx.OK)' 则总是允许访问。当我们通过satisfy 指令配置了 all 方式时，就需要 access 阶段的所有模块都通过验证，但不幸的是，这里ngx_access 模块总是会拒绝访问，所以整个请求就会被拒：

$ curl localhost:8080/test

 （报错信息略，浏览器会默认成Forbidden。）

细心的读者会在 Nginx 错误日志文件中看到类似下面这一行的出错信息：

[error] 6549#0: *1 access forbidden by rule

然而，如果我们把上例中的 satisfy all 语句更改为 satisfy any，

location /test {
    satisfy any;
    deny all;
    access_by_lua 'ngx.exit(ngx.OK)';
    echo something important;
}

结果则会完全不同：

$ curl localhost:8080/test

something important

        即请求反而最终通过了验证。这是因为在 any 方式下，access 阶段只要有一个模块通过了验证，就会认为请求整体通过了验证，而在上例中， ngx_lua 模块的 access_by_lua 语句总是会通过验证的。

        在配置了 satisfy any 的情况下，只有当 access 阶段的所有模块的处理程序都拒绝访问时，整个请求才会被拒，例如：

location /test {
    satisfy any;
    deny all;
    access_by_lua 'ngx.exit(ngx.HTTP_FORBIDDEN)';
    echo something important;
 }

        此时访问 /test 接口才会得到 403 Forbidden 错误页。这里，post-access 阶段参与了 access阶段各模块处理程序的“或关系”的实现。

        值得一提的是，上面这几个的例子需要 ngx_lua 0.5.0rc19 或以上版本；之前的版本是不能和satisfy any 配置语句一起工作的。

• try-files阶段

        这个阶段专门用于实现标准配置指令try_files的功能，并不支持Nginx模块注册处理程序。由于try_files 指令在许多 FastCGI 应用的配置中都有用到，所以我们不妨在这里简单介绍一下。

        try_files 指令接受两个以上任意数量的参数，每个参数都指定了一个 URI. 这里假设配置了 N 个参数，则 Nginx 会在 try-files 阶段，依次把前 N-1 个参数映射为文件系统上的对象（文件或者目录），然后检查这些对象是否存在。一旦 Nginx 发现某个文件系统对象存在，就会在 try-files 阶段把当前请求的 URI 改写为该对象所对应的参数 URI（但不会包含末尾的斜杠字符，也不会发生 “内部跳转”）。如果前 N-1 个参数所对应的文件系统对象都不存在，try-files 阶段就会立即发起“内部跳转”到最后一个参数（即第 N 个参数）所指定的 URI.

        前面在 （六） 和 （七） 中已经看到静态资源服务模块会把当前请求的 URI 映射到文件系统，通过 root 配置指令所指定的“文档根目录”进行映射。例如，当“文档根目录”是/var/www/ 的时候，请求 URI /foo/bar 会被映射为文件 /var/www/foo/bar，而请求 URI /foo/baz/ 则会被映射为目录 /var/www/foo/baz/. 注意这里是如何通过 URI 末尾的斜杠字符是否存在来区分“目录”和“文件”的。我们正在讨论的 try_files 配置指令使用同样的规则来完成其各个参数 URI 到文件系统对象的映射。

        不妨来看下面这个例子：

root /var/www/;

location /test {
    try_files /foo /bar/ /baz;
    echo "uri: $uri";
}

location /foo {
    echo foo;
}

location /bar/ {
    echo bar;
}

location /baz {
    echo baz;
}

        这里通过 root 指令把“文档根目录”配置为 /var/www/，如果你系统中的 /var/www/ 路径下存放有重要数据，则可以把它替换为其他任意路径，但此路径对运行 Nginx worker 进程的系统帐号至少有可读权限。我们在 location /test 中使用了 try_files 配置指令，并提供了三个参数，/foo、/bar/ 和 /baz. 根据前面对 try_files 指令的介绍，我们可以知道，它会在 try-files阶段依次检查前两个参数 /foo 和 /bar/ 所对应的文件系统对象是否存在。

        不妨先来做一组实验。假设现在 /var/www/ 路径下是空的，则第一个参数 /foo 映射成的文件/var/www/foo 是不存在的；同样，对于第二个参数 /bar/ 所映射成的目录 /var/www/bar/ 也是不存在的。于是此时 Nginx 会在 try-files 阶段发起到最后一个参数所指定的 URI（即/baz）的“内部跳转”。实际的请求结果证实了这一点：

$ curl localhost:8080/test

baz

        显然，该请求最终和 location /baz 绑定在一起，执行了输出 baz 字符串的工作。上例中定义的 location /foo 和 location /bar/ 完全不会参与这里的运行过程，因为对于 try_files 的前 N-1 个参数，Nginx 只会检查文件系统，而不会去执行 URI 与 location 之间的匹配。

        对于上面这个请求，Nginx 会产生类似下面这样的“调试日志”：

$ grep trying logs/error.log

[debug] 3869#0: *1 trying to use file: "/foo" "/var/www/foo"

[debug] 3869#0: *1 trying to use dir: "/bar" "/var/www/bar"

[debug] 3869#0: *1 trying to use file: "/baz" "/var/www/baz"

        通过这些信息可以清楚地看到 try-files 阶段发生的事情：Nginx 依次检查了文件/var/www/foo 和目录 /var/www/bar，末了又处理了最后一个参数 /baz. 这里最后一条“调试信息”容易产生误解，会让人误以为 Nginx 也把最后一个参数 /baz 给映射成了文件系统对象进行检查，事实并非如此。当 try_files 指令处理到它的最后一个参数时，总是直接执行“内部跳转”，而不论其对应的文件系统对象是否存在。

        接下来再做一组实验：在 /var/www/ 下创建一个名为 foo 的文件，其内容为 hello world（注意你需要有 /var/www/ 目录下的写权限）：

$ echo 'hello world' > /var/www/foo

然后再请求 /test 接口：

$ curl localhost:8080/test

uri: /foo

        这里发生了什么？我们来看， try_files 指令的第一个参数 /foo 可以映射为文件/var/www/foo，而 Nginx 在 try-files 阶段发现此文件确实存在，于是立即把当前请求的 URI改写为这个参数的值，即 /foo，并且不再继续检查后面的参数，而直接运行后面的请求处理阶段。

        上面这个请求在 try-files 阶段所产生的“调试日志”如下：

$ grep trying logs/error.log

[debug] 4132#0: *1 trying to use file: "/foo" "/var/www/foo"

        显然，在 try-files 阶段，Nginx 确实只检查和处理了 /foo 这一个参数，而后面的参数都被“短路”掉了。

类似地，假设我们删除刚才创建的 /var/www/foo 文件，而在 /var/www/ 下创建一个名为 bar的子目录：

$ mkdir /var/www/bar

        则请求 /test 的结果也是类似的：

$ curl localhost:8080/test

uri: /bar

        在这种情况下，Nginx 在 try-files 阶段发现第一个参数 /foo 对应的文件不存在，就会转向检查第二个参数对应的文件系统对象（在这里便是目录 /var/www/bar/）。由于此目录存在，Nginx 就会把当前请求的 URI 改写为第二个参数的值，即 /bar（注意，原始参数值是/bar/，但 try_files 会自动去除末尾的斜杠字符）。

        这一组实验所产生的“调试日志”如下：

$ grep trying logs/error.log

[debug] 4223#0: *1 trying to use file: "/foo" "/var/www/foo"

[debug] 4223#0: *1 trying to use dir: "/bar" "/var/www/bar"

        我们看到， try_files 指令在这里只检查和处理了它的前两个参数。

        通过前面这几组实验不难看到， try_files 指令本质上只是有条件地改写当前请求的 URI，而这里说的“条件”其实就是文件系统上的对象是否存在。当“条件”都不满足时，它就会无条件地发起一个指定的“内部跳转”。当然，除了无条件地发起“内部跳转”之外， try_files 指令还支持直接返回指定状态码的 HTTP 错误页，例如：

try_files /foo /bar/ =404;

        这行配置是说，当 /foo 和 /bar/ 参数所对应的文件系统对象都不存在时，就直接返回 404 Not Found 错误页。注意这里它是如何使用等号字符前缀来标识 HTTP 状态码的。

• content阶段
• log阶段

6. Nginx下Lua处理阶段与使用范围

指令	所处处理阶段	使用范围	解释
init_by_lua init_by_lua_file	Loading-config	http	nginx Master进程加载配置时执行； 通常用于初始化全局配置/预加载Lua模块
init_worker_by_lua init_worker_by_lua_file	starting-worker	http	每个Nginx Worker进程启动时调用的计时器，如果Master进程不允许则只会在init_by_lua之后调用； 通常用于定时拉取配置/数据，或者后端服务的健康检查
set_by_lua set_by_lua_file	rewrite	server, server if, location, location if	设置nginx变量，可以实现复杂的赋值逻辑；此处是阻塞的，Lua代码要做到非常快；
rewrite_by_lua rewrite_by_lua_file	rewrite tail	http, server, location, location if	rewrite阶段处理，可以实现复杂的转发/重定向逻辑；
access_by_lua access_by_lua_file	access tail	http, server, location, location if	请求访问阶段处理，用于访问控制
content_by_lua content_by_lua_file	content	location, location if	内容处理器，接收请求处理并输出响应
header_filter_by_lua header_filter_by_lua_file	output-header-filter	http, server, location, location if	设置header和cookie
body_filter_by_lua bode_filter_by_lua_file	output-body-filter	http, server, location, location if	对响应数据进行过滤，比如截断、替换。
log_by_lua log_by_lua_file	Log	http, server, location, location if	log阶段处理，比如记录访问量/统计平均响应时间
timer

init_by_lua:

        在nginx重新加载配置文件时，运行里面lua脚本，常用于全局变量的申请。例如lua_shared_dict共享内存的申请，只有当nginx重起后，共享内存数据才清空，这常用于统计。

set_by_lua:

        设置一个变量，常用与计算一个逻辑，然后返回结果。该阶段不能运行Output API、Control API、Subrequest API、Cosocket API

rewrite_by_lua:

        在access阶段前运行，主要用于rewrite

access_by_lua:

        主要用于访问控制，能收集到大部分变量，类似status需要在log阶段才有。这条指令运行于nginx access阶段的末尾，因此总是在 allow 和 deny 这样的指令之后运行，虽然它们同属 access 阶段。

content_by_lua:

        阶段是所有请求处理阶段中最为重要的一个，运行在这个阶段的配置指令一般都肩负着生成内容（content）并输出HTTP响应。

header_filter_by_lua:

        一般只用于设置Cookie和Headers等该阶段不能运行Output API、Control API、Subrequest API、Cosocket API

body_filter_by_lua:

        一般会在一次请求中被调用多次, 因为这是实现基于 HTTP 1.1 chunked 编码的所谓“流式输出”的。该阶段不能运行Output API、Control API、Subrequest API、Cosocket API

log_by_lua:

        该阶段总是运行在请求结束的时候，用于请求的后续操作，如在共享内存中进行统计数据,如果要高精确的数据统计，应该使用body_filter_by_lua。该阶段不能运行Output API、Control API、Subrequest API、Cosocket API

timer:

        ngx_http_access_module模块自己的多条配置指令之间是按顺序执行的，直到遇到第一条满足条件的指令就不再执行后续的allow和deny指令。

6.1. 几个重要实例

• 实例1：

location /test {
     echo hello;
     content_by_lua 'ngx.say("world")';
}

$ curl 'http://localhost:8080/test'

World

分析：绝大不多数Nginx模块在向content阶段注册配置指令时，本质上是在当前的location配置块中注册所谓的“内容处理程序”（content handler）。每一个location只能有一个“内容处理程序”，因此，当在location中同时使用多个模块的content阶段指令时，只有其中一个模块能成功注册和运行这个location的“内容处理程序”。

    实际运行结果表明，写在后面的 content_by_lua 指令（属于ngx_lua模块）反而胜出了，而echo 指令（属于ngx_echo模块）则完全没有运行。具体哪一个模块的指令会胜出是不确定的，例如把上例中的 echo 语句和 content_by_lua 语句交换顺序，则输出就会变成 hello，即ngx_echo 模块胜出。所以我们应当避免在同一个 location 中使用多个模块的 content 阶段指令。

7. 重要知识点

• 在 OpenResty 里面选择使用库的时候，有一个基本的原则：尽量使用 OpenResty 的库函数，尽量不用 Lua 的库函数，因为 Lua 的库都是同步阻塞的。
• 在upstream中加入hash语句，server语句中不能写入weight等其他参数，hash_method指令使用的是hash算法。如下例所示：

upstream resinserver{
      server 10.0.0.10:7777;
      server 10.0.0.11:8888;
      hash $request_uri;
      hash_method crc32;
}

• 增加第三方模块时的config脚本的参考资料：

书籍--深入理解nginx：模块开发与架构解析

8.  Nginx参考资料：

• nginx启动、关闭、重启：http://www.cnblogs.com/derekchen/archive/2011/02/17/1957209.html
• agentzh 的 Nginx 教程：http://openresty.org/download/agentzh-nginx-tutorials-zhcn.html
• Nginx+Lua入门：http://17173ops.com/2013/11/01/17173-ngx-lua-manual.shtml
• nginx 配置指令的执行顺序：http://zhongfox.github.io/blog/server/2013/05/15/nginx-exec-order/
• Nginx配置文件nginx.conf中文详解：http://www.ha97.com/5194.html
• Tengine的Nginx开发从入门到精通：http://tengine.taobao.org/book/
• 官方文档：http://wiki.nginx.org/Configuration