nginx - 指令执行顺序

WHY the Directive Execution Order

在Nginx的世界里，程序的执行是分为多个阶段（phase）的，不同phase的先后顺序是完全固定的。举个例子，假设两个命令分属于不同的phase，则无论这两条指令在conf file中谁在前面谁在后面，都不影响最终的结果，因为它们的执行顺序是根据phase确定的。

最常见、最common的3类phase是：rewrite, access, content；rewrite最早执行，content最晚执行。

• 如何确定某条指令属于哪个phase：查文档！！！
• 某些指令不属于任何phase：它们仅仅是一个声明式的指令，常见的有geo和map

对于属于同一个module内的指令，其执行顺序就和conf file中对应的顺序一致，这没什么疑问。但如果是属于不同module的指令，而这些module又属于同一个phase的话，则这些指令的执行顺序就变的不可预料了。所以，大部分时候，此类情况的配置是相当危险的，应该禁止。

当然，一些第三方模块本身是支持和一些内置模块进行混合调用且顺序是一致的，比如ngx_lua和ngx_rewrite模块，这两个模块中的某些指令的执行顺序就和它们在conf file中的顺序完全一致（比如set和set_by_lua），这显然是很友好的。

• A module can not mix its commands with ngx_rewrite, and expects the correct execution order.

1. rewrite

最常见的set指令就属于rewrite阶段，rewrite是在正式执行命令之前所进行的一些赋值之类的操作。

rewrite的语义限制了，它肯定会在其他phase之前执行。比如set一定会在echo之前执行。一些第三方模块会声明它们的phase是"rewrite tail"，对于这类模块，它们的指令就一定会在ngx_rewrite执行之后再执行。

2. access

access阶段主要负责一些权限的检查，比如客户端是否拥有权限，IP是否合法等等。access阶段的module肯定是在rewrite阶段之后进行执行。比较常见的模块有ngx_access和第三方模块ngx_auth_request，以及ngx_lua中的access_by_lua等函数。

• 效率：基本上，内置的module会比ngx_lua运行效率更高，因为它们是直接由C语言写成的，ngx_lua模块的优点是能够使用lua去完成更为复杂的业务逻辑。

3. content

content就是nginx进行数据响应的阶段。和前面两个phase不同的地方在于，绝大多数情况下，都需要禁止在同一个location中调用不同的content module！原因在于：

• content handler：可以把一个content当成一个实体，其只能被一个句柄（handler）进行控制。不同的module对应的是不同的handler，因此，当多个module出现在一个location之中，那么到底哪个module会执行则是不可预料的。比较典型的就是echo和content_by_lua，这两个指令属于不同的module，且都属于content阶段，那么到底执行哪一个，就不知道了；

4. ngx_index VS. ngx_autoindex VS. ngx_static

在content小节中，有提到content handler这个概念。如果某个location没有任何module可以作为handler会发生什么呢？在这种情况下，ngx_index，ngx_autoindex，ngx_static这三类module就要开始发挥作用了。

• ngx_index：该模块的index指令只用于以/结尾的URI，用于寻找以root指令指定的文件夹下是否有指定资源，如果有的话，则跳转到跟资源同名的location下；该模块的核心作用是location转发；
• ngx_autoindex：如果ngx_index未寻找到指定资源，该模块的autoindex指令就自动将目标文件夹下的目录树转义为html并返回；该模块也只用于以/结尾的URI；
• ngx_static：负责发送静态资源（包括.js, .html, .css等文件）的module；负责以不是/结尾的URI；
• Module ngx_static execute only when all of them have "gave up"
• 404的真正原因：404的原因不是没有定义对应的location，而是没有找到对应的资源；举例如下：

# 如果发来的请求是http://localhost:8080/
# 此时有对应的location；
# 而location内部指示了，需要到/tmp目录下寻找index.html或者index.htm文件；
# 如果未找到的话，就会报错
server{
    listen 8080;

    location / {
        root /tmp/;
        index index.html index.htm;
    }
}

# /auth中没用content module；
# 所以当发来http://localhost:8080/auth时，ngx_static就会接管content；
# 其在/<prefix-of-nginx>/html/下寻找auth.html，如果没有找到的话也会返回404
server {
    listen 8080;
    location /auth {
        access_by_lua '
            -- so much lua code...
        ';
    }
}

---

在前面的小节中，已经介绍了最为常见的3类phase，接下来是一些其他的phase。

1. post-read

post-read是最先开始执行的phase，其作用是对发送过来的request做出适当的修改。这个phase看似比较鸡肋，但其实用途是很大的。

比较常用的就是ngx_realip模块，其set_real_ip_from和real_ip_header命令用于修改一个request的IP值。该模块在代理服务器中最为有效，因为原始的request经过代理转发之后，其IP就变为本地IP，127.0.0.1了。而有了ngx_realip之后，代理服务器可以新增一个自定义字段用于记录原始IP，随后在最终服务器中利用ngx_realip和那个字段，将IP改回来即可。set_real_ip_from的作用是限定这个功能的使用范围，一般应为127.0.0.1，也就是从127.0.0.1发来的request才能去改变对应的IP，这样才不会遭受恶意的网络攻击。

2. server-rewrite

server-rewrite在post-read之后执行。server-rewrite通俗的来讲，就是写在server block中的set等命令，这个阶段的命令是对虚拟服务器的一些参数进行重写。请注意，之前的例子中，set命令都是写在location block中的，因此这些set命令对应的phase是rewrite，而server block中的set命令则在更早的server-rewrite phase中执行。

值得一提的是，无论是server-rewrite phase还是rewrite phase，它们都是在post-read之后执行，所以可以得出，set命令一定会在real_ip_header命令之后执行。

3. find-config

find-config phase的作用是将发来的request匹配到正确的location。这意味着，属于post-read以及server-rewrite phase的指令都必须写在server block或者更外层的block中，而不能是location block，因为location block中的指令必须等到find-config找到正确的location之后才能执行。

5. post-rewrite

之所以没有写4，是因为4就代表rewrite，即，find-config之后是rewrite，而rewrite之后，就是post-rewrite。post-rewrite比较典型的作用就是“internal redirect”。

所谓internal redirect，其实就是从一个location跳到另一个location，但需要注意的是，这和echo_location这种指令的跳转完全不同，因为echo_location指令是属于content phase的。而属于post-rewrite phase的“internal redirect”指令就是ngx_rewrite模块的rewrite指令，它可以重写URI，并随即跳转到新的location。完全可以把它理解为，从rewrite phase返回到find-config phase再次执行location匹配过程。（当然，不是真正的返回）

server{
    listen 8080;

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

    location /bar {
        echo "bar";
    }
}

$ curl "http://localhost:8080/foo"
$ bar

6. preaccess

别碰！