Nginx-Lua模塊的執行順序

一、nginx執行步驟

nginx在處理每一個用戶請求時，都是按照若干個不同的階段依次處理的，與配置文件上的順序沒有關系，詳細內容可以閱讀《深入理解nginx:模塊開發與架構解析》這本書，這里只做簡單介紹；

1、post-read

　　讀取請求內容階段，nginx 讀取並解析完請求頭之后就立即開始運行；

　　例如模塊 ngx_realip 就在 post-read 階段注冊了處理程序，它的功能是迫使 Nginx 認為當前請求的來源地址是指定的某一個請求頭的值。

2、server-rewrite

　　server 塊中請求地址重寫階段；

　　當 ngx_rewrite 模塊的 rewrite、set 配置指令直接書寫在 server 配置塊中時，基本上都是運行在 server-rewrite 階段

3、find-config

　　配置查找階段，用來完成當前請求與 location 配重塊之間的配對工作；

　　這個階段並不支持 Nginx 模塊注冊處理程序，而是由 Nginx 核心來完成當前請求與 location 配置塊之間的配對工作。

4、rewrite

　　location 塊中請求地址重寫階段，當 ngx_rewrite 模塊的 rewrite 指令用於 location 中，就是再這個階段運行的；

　　另外，ngx_set_misc(設置md5、encode_base64等) 模塊的指令，還有 ngx_lua 模塊的 set_by_lua 指令和 rewrite_by_lua 指令也在此階段。

5、post-rewrite

　　請求地址重寫提交階段，由 Nginx 核心完成 rewrite 階段所要求的“內部跳轉”操作，如果 rewrite 階段有此要求的話。

6、preaccess

　　訪問權限檢查准備階段，標准模塊 ngx_limit_req 和 ngx_limit_zone 就運行在此階段，前者可以控制請求的訪問頻度，而后者可以限制訪問的並發度。

7、access

　　訪問權限檢查階段，標准模塊 ngx_access、第三方模塊 ngx_auth_request 以及第三方模塊 ngx_lua 的 access_by_lua 指令就運行在這個階段。 配置指令多是執行訪問控制性質的任務，比如檢查用戶的訪問權限，檢查用戶的來源 IP 地址是否合法。

8、post-access

　　訪問權限檢查提交階段；

　　主要用於配合 access 階段實現標准 ngx_http_core 模塊提供的配置指令 satisfy 的功能。

　　satisfy all(與關系)

　　satisfy any(或關系)

9、try-files

　　配置項 try_files 處理階段；

　　專門用於實現標准配置指令 try_files 的功能 如果前 N-1 個參數所對應的文件系統對象都不存在，try-files 階段就會立即發起“內部跳轉”到最后一個參數（即第 N 個參數）所指定的 URI。

10、content

　　內容產生階段，是所有請求處理階段中最為重要的階段，因為這個階段的指令通常是用來生成HTTP響應內容的；

　　Nginx 的 content 階段是所有請求處理階段中最為重要的一個，因為運行在這個階段的配置指令一般都肩負着生成“內容” 並輸出 HTTP 響應的使命。

11、log

　　日志模塊處理階段；

　　記錄日志。

 

二、Nginx 下 Lua 處理階段

init_by_lua http

set_by_lua server, server if, location, location if

rewrite_by_lua http, server, location, location if

access_by_lua http, server, location, location if

content_by_lua location, location if

header_filter_by_lua http, server, location, location if

body_filter_by_lua http, server, location, location if

log_by_lua http, server, location, location if

 

三、ngx_lua 運行指令

ngx_lua 屬於 nginx 的一部分，它的執行指令都包含在 nginx 的 11 個步驟之中了，不過 ngx_lua 並不是所有階段都會運行的；

1、init_by_lua、init_by_lua_file

語法：init_by_lua <lua-script-str>

語境：http

階段：loading-config

當 nginx master 進程在加載 nginx 配置文件時運行指定的 lua 腳本，通常用來注冊 lua 的全局變量或在服務器啟動時預加載 lua 模塊。例如 lua_shared_dict 共享內存的申請，只有當 nginx 重起后，共享內存數據才清空，這常用於統計。

init_by_lua 'cjson = require "cjson"';

server {
    location = /api {
        content_by_lua '
            ngx.say(cjson.encode({dog = 5, cat = 6}))
        '
    }
}

或者初始化lua_shared_dict共享數據：

lua_shared_dict dogs 1m;
init_by_lua '
    local dogs = ngx.shared.dogs;
    dogs:set("Tom", 50)
'
server {
    location = /api {
        content_by_lua '
            local dogs = ngx.shared.dogs;
            ngx.say(dogs:get("Tom"))
        '
    }
}

但是，lua_shared_dict 的內容不會在 nginx reload 時被清除。所以如果你不想在你的 init_by_lua 中重新初始化共享數據，那么你需要在你的共享內存中設置一個標志位並在 init_by_lua 中進行檢查。

因為這個階段的lua代碼是在nginx forks出任何worker進程之前運行，數據和代碼的加載將享受由操作系統提供的copy-on-write的特性，從而節約了大量的內存。

不要在這個階段初始化你的私有lua全局變量，因為使用lua全局變量會照成性能損失，並且可能導致全局命名空間被污染。

這個階段只支持一些小的LUA Nginx API設置：ngx.log和print、ngx.shared.DICT；

 

2、init_worker_by_lua、init_worker_by_lua_file

語法：init_worker_by_lua <lua-script-str>

語境：http

階段：starting-worker

在每個nginx worker進程啟動時調用指定的lua代碼。如果master 進程不允許，則只會在init_by_lua之后調用。

這個hook通常用來創建每個工作進程的計時器(通過lua的ngx.timer API)，進行后端健康檢查或者其它日常工作：

init_worker_by_lua:
    local delay = 3  -- in seconds
    local new_timer = ngx.timer.at
    local log = ngx.log
    local ERR = ngx.ERR
    local check
    check = function(premature)
        if not premature then
            -- do the health check other routine work
            local ok, err = new_timer(delay, check)
            if not ok then
                log(ERR, "failed to create timer: ", err)
                return
            end
        end
    end
    local ok, err = new_timer(delay, check)
    if not ok then
        log(ERR, "failed to create timer: ", err)
    end

 

3、set_by_lua、set_by_lua_file

語法：set_by_lua $res <lua-script-str> [$arg1 $arg2 …]

語境：server、server if、location、location if

階段：rewrite

 

設置一個變量，常用與計算一個邏輯，然后返回結果 該階段不能運行Output API、Control API、Subrequest API、Cosocket API。

傳入參數到指定的lua腳本代碼中執行，並得到返回值到res中。<lua-script-str>中的代碼可以使從ngx.arg表中取得輸入參數(順序索引從1開始)。

這個指令是為了執行短期、快速運行的代碼因為運行過程中nginx的事件處理循環是處於阻塞狀態的。耗費時間的代碼應該被避免。

禁止在這個階段使用下面的API：1、output api（ngx.say和ngx.send_headers）；2、control api（ngx.exit）；3、subrequest api（ngx.location.capture和ngx.location.capture_multi）；4、cosocket api（ngx.socket.tcp和ngx.req.socket）；5、sleep api（ngx.sleep）

此外注意，這個指令只能一次寫出一個nginx變量，但是使用ngx.var接口可以解決這個問題：

location /foo {
    set $diff '';
    set_by_lua $num '
        local a = 32
        local b = 56
        ngx.var.diff = a - b; --寫入$diff中
        return a + b;  --返回到$sum中
    '
    echo "sum = $sum, diff = $diff";
}

這個指令可以自由的使用HttpRewriteModule、HttpSetMiscModule和HttpArrayVarModule所有的方法。所有的這些指令都將按他們出現在配置文件中的順序進行執行。

 

4、rewrite_by_lua、rewrite_by_lua_file

語法：rewrite_by_lua <lua-script-str>

語境：http、server、location、location if

階段：rewrite tail

作為rewrite階段的處理，為每個請求執行指定的lua代碼。注意這個處理是在標准HtpRewriteModule之后進行的：

location /foo {
    set $a 12;
    set $b "";
    rewrite_by_lua 'ngx.var.b = tonumber(ngx.var.a) + 1';
    echo "res = $b";
}

如果這樣的話將不會按預期進行工作：

location /foo {
    set $a 12;
    set $b '';
    rewrite_by_lua 'ngx.var.b = tonumber(ngx.var.a) + 1';
    if($b = '13') {
        rewrite ^ /bar redirect;
        break;
    }
    echo "res = $b"
}

因為if會在rewrite_by_lua之前運行，所以判斷將不成立。正確的寫法應該是這樣：

location /foo {
    set $a 12;
    set $b '';
    rewrite_by_lua '
        ngx.var.b = tonumber(ngx.var.a) + 1
        if tonumber(ngx.var.b) == 13 then
            return ngx.redirect("/bar");
        end
    '
    echo "res = $b";
}

注意ngx_eval模塊可以近似於使用rewite_by_lua，例如：

location / {
    eval $res {
        proxy_pass http://foo,com/check-spam;
    }
    if($res = 'spam') {
        rewrite ^ /terms-of-use.html redirect;
    }
    fastcgi_pass .......
}

可以被ngx_lua這樣實現：

location = /check-spam {
    internal;
    proxy_pass http://foo.com/check-spam;
}
location / {
    rewrite_by_lua '
        local res = ngx.location.capture("/check-spam")
        if res.body == "spam" then
            return ngx.redirect("terms-of-use.html")
    '
    fastcgi_pass .......
}

和其它的rewrite階段的處理程序一樣，rewrite_by_lua在subrequests中一樣可以運行。

請注意在rewrite_by_lua內調用ngx.exit(ngx.OK)，nginx的請求處理流程將繼續進行content階段的處理。從rewrite_by_lua終止當前的請求，要調用ngx.exit返回status大於200並小於300的成功狀態或ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)的失敗狀態。

如果HttpRewriteModule的重寫指令被用來改寫URI和重定向，那么任何rewrite_by_lua和rewrite_by_lua_file的代碼將不會執行，例如：

location /foo {
    rewrite ^ /bar;
    rewrite_by_lua 'ngx.exit(503)'
}
location /bar {
    .......
}

在這個例子中ngx.exit(503)將永遠不會被執行，因為rewrite修改了location，請求已經跳入其它location中了。

 

5、access_by_lua，access_by_lua_file

語法：access_by_lua <lua-script-str>

語境：http,server,location,location if

階段：access tail

為每個請求在訪問階段的調用lua腳本進行處理。主要用於訪問控制，能收集到大部分的變量。這條指令運行於nginx access階段的末尾，因此總是在 allow 和 deny 這樣的指令之后運行，雖然它們同屬 access 階段。

注意access_by_lua和rewrite_by_lua類似是在標准HttpAccessModule之后才會運行，看一個例子：

location / {
    deny 192.168.1.1;
    allow 192.168.1.0/24;
    allow 10.1.1.0/16;
    deny all;
    access_by_lua '
        local res = ngx.location.capture("/mysql", {...})
        ....
    '
}

如果client ip在黑名單之內，那么這次連接會在進入access_by_lua調用的mysql之前被丟棄掉。

ngx_auth_request模塊和access_by_lua的用法類似：

location / {
    auth_request /auth;
}

可以用ngx_lua這么實現：

location / {
    access_by_lua '
        local res = ngx.location.capture("/auth")
        if res.status == ngx.HTTP_OK then
            return
        end
        if res.status == ngx.HTTP_FORBIDDEN then
            ngx.exit(res.status)
        end
        ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
    '
}

和其它access階段的模塊一樣，access_by_lua不會在subrequest中運行。

請注意在access_by_lua內調用ngx.exit(ngx.OK)，nginx的請求處理流程將繼續進行后面階段的處理。從rewrite_by_lua終止當前的請求，要調用ngx.exit返回status大於200並小於300的成功狀態或ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)的失敗狀態。

 

6、content_by_lua，content_by_lua_file

語法：content_by_lua <lua-script-str>

語境：location，location if

階段：content

作為“content handler”為每個請求執行lua代碼，為請求者輸出響應內容。此階段是所有請求處理階段中最為重要的一個，運行在這個階段的配置指令一般都肩負着生成內容（content）並輸出HTTP響應。

不要將它和其它的內容處理指令在同一個location內使用如proxy_pass。

 

7、header_filter_by_lua，header_filter_by_lua_file

語法：header_filter_by_lua <lua-script-str>

語境：http，server，location，location if

階段：output-header-filter

一般用來設置cookie和headers，在該階段不能使用如下幾個API：

1、output API（ngx.say和ngx.send_headers）

2、control API（ngx.exit和ngx.exec）

3、subrequest API(ngx.location.capture和ngx.location.capture_multi)

4、cosocket API（ngx.socket.tcp和ngx.req.socket）

有一個例子是 在你的lua header filter里添加一個響應頭標頭：

location / {
    proxy_pass http://mybackend;
    header_filter_by_lua 'ngx.header.Foo = "blah"';
}

 

8、body_filter_by_lua，body_filter_by_lua_file

語法：body_filter_by_lua <lua-script-str>

語境：http，server，location，location if

階段：output-body-filter

 

一般會在一次請求中被調用多次, 因為這是實現基於 HTTP 1.1 chunked 編碼的所謂“流式輸出”的。 該階段不能運行Output API、Control API、Subrequest API、Cosocket API

輸入的數據時通過ngx.arg[1](作為lua的string值)，通過ngx.arg[2]這個bool類型表示響應數據流的結尾。

基於這個原因，‘eof’只是nginx的鏈接緩沖區的last_buf（對主requests）或last_in_chain（對subrequests）的標記。

運行以下命令可以立即終止運行接下來的lua代碼：

return ngx.ERROR

這會將響應體截斷導致無效的響應。lua代碼可以通過修改ngx.arg[1]的內容將數據傳輸到下游的nginx output body filter階段的其它模塊中去。例如，將response body中的小寫字母進行反轉，我們可以這么寫：

location / {
    proxy_pass http://mybackend;
    body_filter_by_lua 'ngx.arg[1] = string.upper(ngx.arg[1])'
}

當將ngx.arg[1]設置為nil或者一個空的lua string時，下游的模塊將不會收到數據了。

同樣可以通過修改ngx.arg[2]來設置新的”eof“標記，例如：

location /t {
    echo hello world;
    echo hiya globe;
    body_filter_by_lua '
        local chunk = ngx.arg[1]
        if string.match(chunk, "hello") then
            ngx.arg[2] = true --new eof
            return
        end
        --just throw away any remaining chunk data
        ngx.arg[1] = nil
    '
}

那么GET /t的請求只會回復：hello world

這是因為，當body filter看到了一塊包含”hello“的字符塊后立即將”eof“標記設置為了true，從而導致響應被截斷了但仍然是有效的回復。

當lua代碼中改變了響應體的長度時，應該要清除content-length響應頭部的值，例如：

location /foo {
    header_filter_by_lua 'ngx.header.content_length = nil'
    body_filter_by_lua 'ngx.arg[1] = string.len(ngx.arg[1]) .. "\\n"'
}

在該階段不能使用如下幾個API：

1、output API（ngx.say和ngx.send_headers）
2、control API（ngx.exit和ngx.exec）
3、subrequest API(ngx.location.capture和ngx.location.capture_multi)
4、cosocket API（ngx.socket.tcp和ngx.req.socket）

nginx output filters可能會在一次請求中被多次調用，因為響應體可能是以chunks方式傳輸的。因此這個指令一般會在一次請求中被調用多次。

 

9、log_by_lua，log_by_lua_file

語法：log_by_lua <lua-script-str>

語境：http，server，location，location if

階段：log

在log階段調用指定的lua腳本，並不會替換access log，而是在那之后進行調用。該階段總是運行在請求結束的時候，用於請求的后續操作，如在共享內存中進行統計數據,如果要高精確的數據統計，應該使用body_filter_by_lua。

在該階段不能使用如下幾個API：

1、output API（ngx.say和ngx.send_headers）
2、control API（ngx.exit和ngx.exec）
3、subrequest API(ngx.location.capture和ngx.location.capture_multi)
4、cosocket API（ngx.socket.tcp和ngx.req.socket）

一個收集upstream_response_time的平均數據的例子：

lua_shared_dict log_dict 5M

server{
    location / {
        proxy_pass http;//mybackend
        log_by_lua '
            local log_dict = ngx.shared.log_dict
            local upstream_time = tonumber(ngx.var.upstream_response_time)
            local sum = log_dict:get("upstream_time-sum") or 0
            sum = sum + upstream_time
            log_dict:set("upsteam_time-sum", sum)
            local newval, err = log_dict:incr("upstream_time-nb", 1)
            if not newval and err == "not found" then
                log_dict:add("upstream_time-nb", 0)
                log_dict:incr("upstream_time-nb", 1)
            end
        '
    }
    location = /status {
        content_by_lua '
            local log_dict = ngx.shared.log_dict
            local sum = log_dict:get("upstream_time-sum")
            local nb = log_dict:get("upstream_time-nb")

            if nb and sum then
                ngx.say("average upstream response time:  ", sum/nb, " (", nb, " reqs)")
            else
                ngx.say("no data yet")
            end
        '
    }
}

轉自:http://www.mrhaoting.com/?p=157