模組 ngx_http_scgi_module

ngx_http_scgi_module 模組允許將請求傳遞到 SCGI 伺服器。

location / {
    include   scgi_params;
    scgi_pass localhost:9000;
}

使傳往 SCGI 伺服器的連線源自指定的本機 IP 位址，並可選擇性地包含埠號 (1.11.2)。參數值可以包含變數 (1.3.12)。特殊值 off (1.3.12) 會取消從先前的組態層級繼承的 scgi_bind 指令的效果，這允許系統自動指派本機 IP 位址和埠號。

transparent 參數 (1.11.0) 允許傳往 SCGI 伺服器的連線源自非本機 IP 位址，例如，來自用戶端的真實 IP 位址。

scgi_bind $remote_addr transparent;

為了使此參數生效，通常需要使用超級使用者權限執行 nginx 工作程序。在 Linux 上則不需要 (1.13.8)，因為如果指定了 transparent 參數，工作程序會從主程序繼承 CAP_NET_RAW 功能。也需要配置核心路由表以攔截來自 SCGI 伺服器的網路流量。

scgi_buffer_size 4k|8k;

設定用於讀取從 SCGI 伺服器收到的回應第一部分的緩衝區的 size。此部分通常包含一個小的回應標頭。預設情況下，緩衝區大小等於一個記憶體頁面。這取決於平台，可能是 4K 或 8K。它可以縮小。

scgi_buffering on;

啟用或停用來自 SCGI 伺服器的回應緩衝處理。

啟用緩衝處理時，nginx 會盡快從 SCGI 伺服器接收回應，並將其儲存到由 scgi_buffer_size 和 scgi_buffers 指令設定的緩衝區中。如果整個回應不適合放入記憶體，則可以將一部分儲存到磁碟上的暫存檔。寫入暫存檔由 scgi_max_temp_file_size 和 scgi_temp_file_write_size 指令控制。

停用緩衝處理時，回應會同步傳遞給用戶端，在收到回應時立即傳遞。nginx 不會嘗試從 SCGI 伺服器讀取整個回應。nginx 一次可以從伺服器接收的最大資料大小由 scgi_buffer_size 指令設定。

也可以透過在「X-Accel-Buffering」回應標頭欄位中傳遞「yes」或「no」來啟用或停用緩衝處理。可以使用 scgi_ignore_headers 指令停用此功能。

scgi_buffers 8 4k|8k;

設定用於讀取來自 SCGI 伺服器的回應的緩衝區的 number 和 size，用於單一連線。預設情況下，緩衝區大小等於一個記憶體頁面。這取決於平台，可能是 4K 或 8K。

scgi_busy_buffers_size 8k|16k;

當啟用來自 SCGI 伺服器的回應緩衝處理時，限制在回應尚未完全讀取時，可以忙於將回應傳送給用戶端的緩衝區的總 size。同時，其餘的緩衝區可以用於讀取回應，並且如果需要，則將部分回應緩衝到暫存檔。預設情況下，size 受限於由 scgi_buffer_size 和 scgi_buffers 指令設定的兩個緩衝區的大小。

scgi_cache off;

定義用於快取的共用記憶體區域。相同的區域可以在多個位置使用。參數值可以包含變數 (1.7.9)。off 參數會停用從先前的組態層級繼承的快取。

scgi_cache_background_update off;

允許啟動背景子請求以更新過期的快取項目，同時將過時的快取回應傳回給用戶端。請注意，必須允許在使用過時的快取回應時進行更新。

定義在哪些條件下不會從快取中取得回應。如果至少一個字串參數的值不為空且不等於「0」，則不會從快取中取得回應。

scgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
scgi_cache_bypass $http_pragma    $http_authorization;

可以與 scgi_no_cache 指令一起使用。

定義快取的金鑰，例如

scgi_cache_key localhost:9000$request_uri;

scgi_cache_lock off;

啟用後，一次只允許一個請求根據 scgi_cache_key 指令識別的新快取元素，將請求傳遞到 SCGI 伺服器。相同快取元素的其他請求將等待回應出現在快取中，或者等待此元素的快取鎖定釋放，最多等待由 scgi_cache_lock_timeout 指令設定的時間。

scgi_cache_lock_age 5s;

如果傳遞到 SCGI 伺服器以填入新快取元素的最後一個請求在指定的 time 內未完成，則可以將另一個請求傳遞到 SCGI 伺服器。

scgi_cache_lock_timeout 5s;

設定 scgi_cache_lock 的逾時時間。當 time 過期時，請求將傳遞到 SCGI 伺服器，但是不會快取回應。

在 1.7.8 之前的版本中，可以快取回應。

設定位元組範圍請求的位元組偏移量。如果範圍超出偏移量，則範圍請求將傳遞到 SCGI 伺服器，並且不會快取回應。

scgi_cache_methods GET HEAD;

如果用戶端請求方法在此指令中列出，則會快取回應。「GET」和「HEAD」方法會始終加入清單，但建議明確指定它們。另請參閱 scgi_no_cache 指令。

scgi_cache_min_uses 1;

設定在快取回應之前請求的 number。

設定快取的路徑和其他參數。快取資料儲存在檔案中。快取中的檔案名稱是將 MD5 函數套用至快取金鑰的結果。levels 參數定義快取的階層層級：從 1 到 3，每個層級接受值 1 或 2。例如，在下列組態中

scgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

快取中的檔案名稱將如下所示

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

快取的回應會先寫入暫存檔，然後重新命名該檔案。從 0.8.9 版開始，暫存檔和快取可以放在不同的檔案系統上。但是，請注意，在這種情況下，檔案是在兩個檔案系統之間複製，而不是便宜的重新命名作業。因此，建議針對任何給定的位置，將快取和保存暫存檔的目錄都放在相同的檔案系統上。用於暫存檔的目錄根據 use_temp_path 參數 (1.7.10) 設定。如果省略此參數或將其設定為值 on，則會使用給定位置的 scgi_temp_path 指令設定的目錄。如果將值設定為 off，則暫存檔將直接放置在快取目錄中。

此外，所有活動金鑰和有關資料的資訊都儲存在共用記憶體區域中，其 name 和 size 由 keys_zone 參數設定。一個兆位元組區域可以儲存大約 8 千個金鑰。

作為 商業訂閱的一部分，共用記憶體區域也儲存擴充的快取資訊，因此，對於相同數量的金鑰，需要指定更大的區域大小。例如，一個兆位元組區域可以儲存大約 4 千個金鑰。

在 inactive 參數指定的時間內未存取的快取資料，無論其新鮮度如何，都會從快取中移除。預設情況下，inactive 設定為 10 分鐘。

特殊的「快取管理員」程序會監控 max_size 參數設定的最大快取大小，以及快取檔案系統上由 min_free (1.19.1) 參數設定的最小可用空間量。當大小超出或沒有足夠的可用空間時，它會移除最近最少使用的資料。資料會在由 manager_files、manager_threshold 和 manager_sleep 參數 (1.11.5) 設定的迭代中移除。在一次迭代中，不會刪除超過 manager_files 個項目（預設為 100 個）。一次迭代的持續時間受限於 manager_threshold 參數（預設為 200 毫秒）。在迭代之間，會暫停由 manager_sleep 參數（預設為 50 毫秒）設定的時間。

在啟動後一分鐘，特殊的「快取載入器」程序會被啟動。它會將檔案系統上先前快取資料的資訊載入到快取區域。載入也是以迭代方式進行。在一次迭代中，載入的項目不會超過 loader_files 個（預設為 100 個）。此外，一次迭代的持續時間受到 loader_threshold 參數的限制（預設為 200 毫秒）。在迭代之間，會暫停一段由 loader_sleep 參數設定的時間（預設為 50 毫秒）。

此外，以下參數可作為我們的 商業訂閱 的一部分。

purger=on|off

指示快取清除器是否應將符合萬用字元金鑰的快取項目從磁碟中移除 (1.7.12)。將參數設定為 on（預設為 off）會啟動「快取清除器」程序，該程序會永久迭代所有快取項目並刪除符合萬用字元金鑰的項目。

purger_files=number

設定一次迭代期間將掃描的項目數 (1.7.12)。預設情況下，purger_files 設定為 10。

purger_threshold=number

設定一次迭代的持續時間 (1.7.12)。預設情況下，purger_threshold 設定為 50 毫秒。

purger_sleep=number

設定迭代之間的暫停時間 (1.7.12)。預設情況下，purger_sleep 設定為 50 毫秒。

在 1.7.3、1.7.7 和 1.11.10 版本中，快取標頭格式已變更。升級到較新的 nginx 版本後，先前快取的響應將被視為無效。

定義將請求視為快取清除請求的條件。如果字串參數中至少有一個值不為空且不等於「0」，則會移除具有相應快取金鑰的快取項目。成功操作的結果會以返回 204 (無內容) 響應表示。

如果清除請求的快取金鑰以星號（「*」）結尾，則會從快取中移除所有符合萬用字元金鑰的快取項目。但是，這些項目將保留在磁碟上，直到它們因不活動而被刪除，或由快取清除器處理 (1.7.12)，或由用戶端嘗試存取它們。

設定範例

scgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

map $request_method $purge_method {
    PURGE   1;
    default 0;
}

server {
    ...
    location / {
        scgi_pass        backend;
        scgi_cache       cache_zone;
        scgi_cache_key   $uri;
        scgi_cache_purge $purge_method;
    }
}

此功能可作為我們的 商業訂閱 的一部分。

scgi_cache_revalidate off;

使用帶有「If-Modified-Since」和「If-None-Match」標頭欄位的條件請求，啟用過期快取項目的重新驗證。

scgi_cache_use_stale off;

決定在與 SCGI 伺服器通訊期間發生錯誤時，可以使用陳舊快取響應的情況。該指令的參數與scgi_next_upstream 指令的參數相符。

如果無法選取處理請求的 SCGI 伺服器，error 參數也允許使用陳舊快取響應。

此外，如果陳舊快取響應目前正在更新，則 updating 參數允許使用陳舊快取響應。這有助於在更新快取資料時，盡量減少對 SCGI 伺服器的存取次數。

在響應過期後，也可以直接在響應標頭中啟用陳舊快取響應的使用，時間為指定的秒數 (1.11.10)。這比使用指令參數的優先順序低。

• 「Cache-Control」標頭欄位的「stale-while-revalidate」擴充功能允許在陳舊快取響應目前正在更新時使用。
• 「Cache-Control」標頭欄位的「stale-if-error」擴充功能允許在發生錯誤時使用陳舊快取響應。

為了在填入新的快取元素時盡量減少對 SCGI 伺服器的存取次數，可以使用 scgi_cache_lock 指令。

設定不同響應程式碼的快取時間。例如，以下指令

scgi_cache_valid 200 302 10m;
scgi_cache_valid 404      1m;

設定程式碼為 200 和 302 的響應快取 10 分鐘，而程式碼為 404 的響應快取 1 分鐘。

如果只指定快取 time

scgi_cache_valid 5m;

則只快取 200、301 和 302 響應。

此外，可以指定 any 參數來快取任何響應

scgi_cache_valid 200 302 10m;
scgi_cache_valid 301      1h;
scgi_cache_valid any      1m;

快取的參數也可以直接在響應標頭中設定。這比使用指令設定快取時間的優先順序高。

• 「X-Accel-Expires」標頭欄位設定響應的快取時間（以秒為單位）。零值會停用響應的快取。如果值以 @ 字首開頭，則會設定絕對時間（以自 Epoch 以來的秒數為單位），響應最多可快取到該時間。
• 如果標頭不包含「X-Accel-Expires」欄位，則可以在「Expires」或「Cache-Control」標頭欄位中設定快取的參數。
• 如果標頭包含「Set-Cookie」欄位，則不會快取此類響應。
• 如果標頭包含帶有特殊值「*」的「Vary」欄位，則不會快取此類響應 (1.7.7)。如果標頭包含帶有另一個值的「Vary」欄位，則會快取此類響應，並考量相應的請求標頭欄位 (1.7.7)。

可以使用 scgi_ignore_headers 指令停用一或多個這些響應標頭欄位的處理。

scgi_connect_timeout 60s;

定義與 SCGI 伺服器建立連線的逾時時間。應注意，此逾時時間通常不能超過 75 秒。

scgi_force_ranges off;

無論這些響應中的「Accept-Ranges」欄位為何，都啟用 SCGI 伺服器中快取和未快取響應的位元組範圍支援。

預設情況下，nginx 不會將 SCGI 伺服器響應中的標頭欄位「Status」和「X-Accel-...」傳遞給用戶端。scgi_hide_header 指令會設定其他不會傳遞的欄位。相反地，如果需要允許傳遞欄位，則可以使用 scgi_pass_header 指令。

scgi_ignore_client_abort off;

決定當用戶端在未等待響應的情況下關閉連線時，是否應關閉與 SCGI 伺服器的連線。

停用來自 SCGI 伺服器的特定響應標頭欄位的處理。可以忽略以下欄位：「X-Accel-Redirect」、「X-Accel-Expires」、「X-Accel-Limit-Rate」(1.1.6)、「X-Accel-Buffering」(1.1.6)、「X-Accel-Charset」(1.1.6)、「Expires」、「Cache-Control」、「Set-Cookie」(0.8.44) 和「Vary」(1.7.7)。

如果未停用，則這些標頭欄位的處理具有以下效果

• 「X-Accel-Expires」、「Expires」、「Cache-Control」、「Set-Cookie」和「Vary」設定響應快取的參數；
• 「X-Accel-Redirect」會執行到指定 URI 的內部重新導向；
• 「X-Accel-Limit-Rate」設定響應傳輸給用戶端的速率限制；
• 「X-Accel-Buffering」啟用或停用響應的緩衝；
• 「X-Accel-Charset」設定響應的所需字元集。

scgi_intercept_errors off;

決定是否應將程式碼大於或等於 300 的 SCGI 伺服器響應傳遞給用戶端，還是應截取並重新導向到 nginx，以便使用 error_page 指令處理。

scgi_limit_rate 0;

限制從 SCGI 伺服器讀取響應的速度。rate 以每秒位元組數指定。零值會停用速率限制。限制是針對每個請求設定的，因此如果 nginx 同時開啟與 SCGI 伺服器的兩個連線，則整體速率將是指定限制的兩倍。只有在啟用來自 SCGI 伺服器的響應緩衝時，限制才會起作用。參數值可以包含變數 (1.27.0)。

scgi_max_temp_file_size 1024m;

啟用來自 SCGI 伺服器的響應緩衝，且整個響應不符合由scgi_buffer_size 和 scgi_buffers 指令設定的緩衝區時，響應的一部分可以儲存到暫存檔案。此指令設定暫存檔案的最大 size。一次寫入暫存檔案的資料大小由 scgi_temp_file_write_size 指令設定。

零值會停用將響應緩衝到暫存檔案。

此限制不適用於將快取或儲存在磁碟上的響應。

scgi_next_upstream error timeout;

指定在哪些情況下應將請求傳遞到下一個伺服器

error

在與伺服器建立連線、將請求傳遞給伺服器或讀取響應標頭時發生錯誤；

timeout

在與伺服器建立連線、將請求傳遞給伺服器或讀取響應標頭時發生逾時；

invalid_header

伺服器傳回空的或無效的響應；

http_500

伺服器傳回程式碼為 500 的響應；

http_503

伺服器傳回程式碼為 503 的響應；

http_403

伺服器傳回程式碼為 403 的響應；

http_404

伺服器傳回程式碼為 404 的響應；

http_429

伺服器傳回程式碼為 429 的響應 (1.11.13)；

non_idempotent

通常，如果已將請求傳送到上游伺服器，則不會將具有非等冪方法（POST、LOCK、PATCH）的請求傳遞到下一個伺服器 (1.9.13)；明確啟用此選項允許重試此類請求；

off

停用將請求傳遞到下一個伺服器。

應記住，只有在尚未將任何內容傳送到用戶端的情況下，才能將請求傳遞到下一個伺服器。也就是說，如果在傳輸響應的過程中發生錯誤或逾時，則無法修正此問題。

此指令還定義了什麼被視為與伺服器通訊的不成功嘗試。error、timeout 和 invalid_header 的情況始終被視為不成功嘗試，即使它們未在指令中指定。只有在指令中指定的情況下，http_500、http_503 和 http_429 的情況才被視為不成功嘗試。http_403 和 http_404 的情況永遠不會被視為不成功嘗試。

可以透過嘗試次數和時間限制將請求傳遞到下一個伺服器。

scgi_next_upstream_timeout 0;

限制將請求傳遞到下一個伺服器的時間。值 0 會關閉此限制。

scgi_next_upstream_tries 0;

限制將請求傳遞到下一個伺服器的可能嘗試次數。值 0 會關閉此限制。

定義在何種條件下，回應不會儲存至快取。如果字串參數中至少有一個值不為空且不等於 “0”，則回應將不會被儲存。

scgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
scgi_no_cache $http_pragma    $http_authorization;

可與 scgi_cache_bypass 指令一起使用。

設定一個應傳遞給 SCGI 伺服器的 參數。值 可以包含文字、變數及其組合。這些指令會從先前的組態層級繼承，當且僅當目前層級沒有定義 scgi_param 指令時。

標準 CGI 環境變數應作為 SCGI 標頭提供，請參閱發行版中提供的 scgi_params 檔案

location / {
    include scgi_params;
    ...
}

如果指令使用 if_not_empty (1.1.11) 指定，則只有在其值不為空時，才會將此參數傳遞給伺服器。

scgi_param HTTPS $https if_not_empty;

設定 SCGI 伺服器的地址。地址可以指定為網域名稱或 IP 位址，以及埠號。

scgi_pass localhost:9000;

或作為 UNIX 網域 socket 路徑。

scgi_pass unix:/tmp/scgi.socket;

如果網域名稱解析為多個位址，則將以循環方式使用所有位址。此外，位址可以指定為 伺服器群組。

參數值可以包含變數。在這種情況下，如果將位址指定為網域名稱，則會在已描述的 伺服器群組中搜尋該名稱，如果找不到，則使用 解析器 來決定。

允許將 原本停用的標頭欄位從 SCGI 伺服器傳遞到用戶端。

scgi_pass_request_body on;

指示是否將原始請求主體傳遞給 SCGI 伺服器。另請參閱 scgi_pass_request_headers 指令。

scgi_pass_request_headers on;

指示是否將原始請求的標頭欄位傳遞給 SCGI 伺服器。另請參閱 scgi_pass_request_body 指令。

scgi_read_timeout 60s;

定義從 SCGI 伺服器讀取回應的逾時時間。逾時時間僅設定在兩個連續讀取操作之間，而不是整個回應的傳輸。如果 SCGI 伺服器在此時間內沒有傳輸任何內容，則連線將會關閉。

scgi_request_buffering on;

啟用或停用用戶端請求主體的緩衝。

啟用緩衝時，會先從用戶端 讀取整個請求主體，然後再將請求傳送至 SCGI 伺服器。

停用緩衝時，請求主體會在其收到後立即傳送至 SCGI 伺服器。在這種情況下，如果 nginx 已經開始傳送請求主體，則無法將請求傳遞給 下一個伺服器。

當使用 HTTP/1.1 分塊傳輸編碼傳送原始請求主體時，無論指令值為何，都會緩衝請求主體。

scgi_send_timeout 60s;

設定將請求傳輸到 SCGI 伺服器的逾時時間。逾時時間僅設定在兩個連續寫入操作之間，而不是整個請求的傳輸。如果 SCGI 伺服器在此時間內沒有收到任何內容，則連線將會關閉。

scgi_socket_keepalive off;

為到 SCGI 伺服器的輸出連線設定 “TCP keepalive” 行為。預設情況下，作業系統的設定對 socket 生效。如果指令設定為值 “on”，則會為 socket 開啟 SO_KEEPALIVE socket 選項。

scgi_store off;

啟用將檔案儲存到磁碟。on 參數使用與 alias 或 root 指令對應的路徑儲存檔案。off 參數停用檔案的儲存。此外，可以使用帶有變數的 字串 明確設定檔案名稱。

scgi_store /data/www$original_uri;

檔案的修改時間會根據收到的 “Last-Modified” 回應標頭欄位設定。回應會先寫入臨時檔案，然後重新命名該檔案。從 0.8.9 版開始，臨時檔案和持久儲存區可以放在不同的檔案系統上。但是，請注意，在這種情況下，檔案是在兩個檔案系統之間複製，而不是簡單的重新命名操作。因此，建議對於任何給定的位置，儲存的檔案和由 scgi_temp_path 指令設定的臨時檔案目錄，都放在同一個檔案系統上。

此指令可用於建立本地靜態不變檔案的副本，例如：

location /images/ {
    root              /data/www;
    error_page        404 = /fetch$uri;
}

location /fetch/ {
    internal;

    scgi_pass         backend:9000;
    ...

    scgi_store        on;
    scgi_store_access user:rw group:rw all:r;
    scgi_temp_path    /data/temp;

    alias             /data/www/;
}

scgi_store_access user:rw;

為新建立的檔案和目錄設定存取權限，例如：

scgi_store_access user:rw group:rw all:r;

如果指定了任何 group 或 all 存取權限，則可以省略 user 權限

scgi_store_access group:rw all:r;

scgi_temp_file_write_size 8k|16k;

限制在啟用將 SCGI 伺服器的回應緩衝到臨時檔案時，一次寫入臨時檔案的資料 大小。預設情況下，大小 受 scgi_buffer_size 和 scgi_buffers 指令設定的兩個緩衝區限制。臨時檔案的最大大小由 scgi_max_temp_file_size 指令設定。

scgi_temp_path scgi_temp;

定義一個目錄，用於儲存從 SCGI 伺服器接收的資料的臨時檔案。可以在指定的目錄下使用最多三層的子目錄層次結構。例如，在下列組態中

scgi_temp_path /spool/nginx/scgi_temp 1 2;

臨時檔案可能看起來像這樣

/spool/nginx/scgi_temp/7/45/00000123457

另請參閱 scgi_cache_path 指令的 use_temp_path 參數。