Nginx 配置指令手冊

Upstream directives

upstream

• 定義一組上游服務器;
• name
• 1

定義一組服務器。
服務器可以偵聽不同的端口。
此外，可以混合偵聽TCP和UNIX域套接字的服務器。

server

• 定義服務器的地址和其他參數;
• address [parameters], 示例 10.64.11:8080 weight=1;
• 2

hash

• 指定服務器組的負載平衡方法，其中客戶端 - 服務器映射基於散列鍵值。
• key: $remote_addr|$request_uri
• 1

healthcheck

check

• 添加上游服務器的運行狀況檢查。
• interval=3000 rise=2 fall=2 timeout=1000 type=http;
• 5

check_http_send

• 將發送此http數據包以檢查上游服務器。
• "GET /healthcheck.html HTTP/1.0\r\nHost: 11bee.com\r\nConnection: close\r\n\r\n";
• 3

check_http_expect_alive

• 這些狀態代碼表示上游服務器的http響應沒問題，后端還活着。
• http_2xx|http_3xx

• = 2

Server directives

server_name

• 虛擬服務器的名稱
• [server_name]

• = 1

listen

• 設置IP的地址和端口，或服務器將接受請求的UNIX域套接字的路徑
• PORT (ssl)
• 1-2

location

• 根據請求URI設置配置。
• [expressions] [uri]
• 2

GZIP directives

gzip

• 啟用或禁用gzipping響應;
• on | off;
• 1

gzip_buffers

• 設置用於壓縮響應的緩沖區的數量和大小;
• 32 4k|16 8k;
• 2

設置用於壓縮響應的緩沖區的數量和大小。
默認情況下，緩沖區大小等於一個內存頁面。
這是4K或8K，具體取決於平台。

gzip_comp_level

• 設置響應的gzip壓縮級別;
• level 1-9;
• 1

gzip_disable

• 對具有與任何指定正則表達式匹配的“User-Agent”標頭字段的請求禁用gzipping響應。
• "MSIE 6";
• 1

gzip_http_version

• 設置壓縮響應所需的最低HTTP請求版本。
• 1.1
• 1

gzip_min_length

• 設置將被gzip壓縮的響應的最小長度。
• 1000
• 1

gzip_types

• 對指定的MIME類型進行gzipping響應。
• 默認application/x-javascript text/javascript application/json text/css;
• 大於0

Enables gzipping of responses for the specified MIME types in addition to “text/html”. The special value “*” matches any MIME type (0.8.29). Responses with the “text/html” type are always compressed.

gzip_proxied

• 根據請求和響應啟用或禁用對代理請求的響應的gzipping
• 默認所有 expired no-cache no-store private auth;
• 大於0, 或者不寫

根據請求和響應啟用或禁用對代理請求的響應的gzipping。
請求被代理的事實由“Via”請求頭字段的存在確定。
該指令接受多個參數：

# off
disables compression for all proxied requests, ignoring other parameters;
# expired
enables compression if a response header includes the “Expires” field with a value that disables caching;
# no-cache
enables compression if a response header includes the “Cache-Control” field with the “no-cache” parameter;
# no-store
enables compression if a response header includes the “Cache-Control” field with the “no-store” parameter;
# private
enables compression if a response header includes the “Cache-Control” field with the “private” parameter;
# no_last_modified
enables compression if a response header does not include the “Last-Modified” field;
# no_etag
enables compression if a response header does not include the “ETag” field;
# auth
enables compression if a request header includes the “Authorization” field;
# any
enables compression for all proxied requests.

Proxy directives

proxy_pass

• 設置代理服務器的協議和地址以及應映射位置的可選URI。
• URL|Upstrem_name
• 2

設置代理服務器的協議和地址以及應映射位置的可選URI。作為協議，可以指定“http”或“https”。地址可以指定為域名或IP地址，以及可選端口：

proxy_buffer_size

• 設置用於讀取從代理服務器接收的響應的第一部分的緩沖區的大小。
• 4k|8k;
• 1

設置用於讀取從代理服務器接收的響應的第一部分的緩沖區的大小。這部分通常包含一個小的響應頭。默認情況下，緩沖區大小等於一個內存頁面。這是4K或8K，具體取決於平台。然而，它可以做得更小。

proxy_buffering

• 啟用或禁用來自代理服務器的響應緩沖。
• on | off; default on
• 1

啟用緩沖后，nginx會盡快從代理服務器接收響應，並將其保存到proxy_buffer_size和proxy_buffers指令設置的緩沖區中。 如果整個響應不適合內存，則可以將其中的一部分保存到磁盤上的臨時文件中。 寫入臨時文件由proxy_max_temp_file_size和proxy_temp_file_write_size指令控制。

禁用緩沖時，響應會在收到響應時立即同步傳遞給客戶端。 nginx不會嘗試從代理服務器讀取整個響應。 nginx一次可以從服務器接收的數據的最大大小由proxy_buffer_size指令設置。

也可以通過在“X-Accel-Buffering”響應頭字段中傳遞“是”或“否”來啟用或禁用緩沖。 可以使用proxy_ignore_headers指令禁用此功能。

proxy_buffers

• 用於單個連接。默認情況下，緩沖區大小等於一個內存頁面;
• 8 8k|16k; default 64 4k
• 2

用於單個連接。默認情況下，緩沖區大小等於一個內存頁面。這是4K或8K，具體取決於平台。

proxy_busy_buffers_size

• 當啟用來自代理服務器的響應緩沖時，限制可能忙於向響應客戶端發送響應的緩沖區的總大小，而響應尚未完全讀取;
• 8k|16k;
• 1

當啟用來自代理服務器的響應緩沖時，限制可能忙於向響應客戶端發送響應的緩沖區的總大小，而響應尚未完全讀取。
同時，其余緩沖區可用於讀取響應，如果需要，還可以緩沖部分響應臨時文件。
默認情況下，size由proxy_buffer_size和proxy_buffers指令設置的兩個緩沖區的大小限制。

proxy_cache

• 定義用於緩存的共享內存區域。
• zone | off; default off
• 1

定義用於緩存的共享內存區域。可以在多個地方使用相同的區域。參數值可以包含變量（1.7.9）。off參數禁用從先前配置級別繼承的緩存。

proxy_connect_timeout

• 定義與代理服務器建立連接的超時。
• 60s;
• 1

應該注意，此超時通常不會超過75秒。

proxy_cookie_domain

• 設置應在代理服務器響應的“Set-Cookie”標頭字段的domain屬性中更改的文本;
• off | domain replacement;
• 1-2

proxy_http_version

• 設置代理的HTTP協議版本
• 1.0 | 1.1; default 1.0
• 1

設置代理的HTTP協議版本。默認情況下，使用版本1.0。建議將1.1版用於keepalive連接。

proxy_ignore_client_abort

• 確定在客戶端關閉連接而不等待響應時是否應關閉與代理服務器的連接。
• on | off; default off
• 1

proxy_intercept_errors

• 確定代碼大於或等於300的代理響應是應該傳遞給客戶端還是被攔截並重定向到nginx以便使用error_page指令進行處理。
• on | off; default on
• 1

proxy_next_upstream

• 指定應將請求傳遞到下一個服務器的情況：
• 默認 error timeout invalid_header http_500 http_502 http_503 http_504 http_404;
• 8

error
an error occurred while establishing a connection with the server, passing a request to it, or reading the response header;
timeout
a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header;
invalid_header
a server returned an empty or invalid response;
http_500
a server returned a response with the code 500;
http_502
a server returned a response with the code 502;
http_503
a server returned a response with the code 503;
http_504
a server returned a response with the code 504;
http_403
a server returned a response with the code 403;
http_404
a server returned a response with the code 404;
http_429
a server returned a response with the code 429 (1.11.13);
non_idempotent
normally, requests with a non-idempotent method (POST, LOCK, PATCH) are not passed to the next server if a request has been sent to an upstream server (1.9.13); enabling this option explicitly allows retrying such requests;
off
disables passing a request to the next server.

proxy_pass_request_headers

• 指示是否將原始請求的標頭字段傳遞給代理服務器。
• on | off; default on
• 1

proxy_read_timeout

• 定義從代理服務器讀取響應的超時。
• 60s;
• 1

定義從代理服務器讀取響應的超時。僅在兩個連續的讀操作之間設置超時，而不是為整個響應的傳輸。如果代理服務器在此時間內未傳輸任何內容，則關閉連接。

proxy_send_timeout

• 設置將請求傳輸到代理服務器的超時。
• 60s;
• 1

設置將請求傳輸到代理服務器的超時。僅在兩個連續的寫操作之間設置超時，而不是為整個請求的傳輸。如果代理服務器在此時間內未收到任何內容，則關閉連接。

proxy_set_header

• 允許將字段重新定義或附加到傳遞給代理服務器的請求標頭。
• [field] [value]
• 2

允許將字段重新定義或附加到傳遞給代理服務器的請求標頭。該值可以包含文本，變量及其組合。當且僅當在當前級別上沒有定義proxy_set_header指令時，這些指令才從前一級繼承。默認情況下，只重新定義了兩個字段：

proxy_temp_file_write_size

• 當啟用從代理服務器到臨時文件的響應緩沖時，限制一次寫入臨時文件的數據大小
• 8k|16k;
• 1

當啟用從代理服務器到臨時文件的響應緩沖時，限制一次寫入臨時文件的數據大小。
默認情況下，size由proxy_buffer_size和proxy_buffers指令設置的兩個緩沖區限制。
臨時文件的最大大小由proxy_max_temp_file_size指令設置。

add_header

• 將指定的字段添加到響應標頭。
• name value
• 2

client_body_buffer_size

• 設置讀取客戶端請求主體的緩沖區大小
• size, 8k|16k
• 1

設置讀取客戶端請求主體的緩沖區大小。
如果請求主體大於緩沖區，則整個主體或僅其部分被寫入臨時文件。
默認情況下，緩沖區大小等於兩個內存頁。
這在x86，其他32位平台和x86-64上是8K。
在其他64位平台上通常為16K。

client_header_buffer_size

• 設置讀取客戶端請求標頭的緩沖區大小
• size, 1k;
• 1

設置讀取客戶端請求標頭的緩沖區大小。
對於大多數請求，1K字節的緩沖區就足夠了。
但是，如果請求包含長cookie或來自WAP客戶端，則可能不適合1K。
如果請求行或請求頭字段不適合此緩沖區，則會分配由large_client_header_buffers指令配置的較大緩沖區。

client_max_body_size

• 設置客戶端請求正文的最大允許大小;
• size, 1m;
• 1

設置客戶端請求正文的最大允許大小，在“Content-Length”請求標頭字段中指定。
如果請求中的大小超過配置的值，則會將413（請求實體太大）錯誤返回給客戶端。
請注意，瀏覽器無法正確顯示此錯誤。
將大小設置為0將禁用檢查客戶端請求正文大小。

ignore_invalid_headers

• 控制是否應忽略具有無效名稱的標頭字段。
• on|off
• 1

控制是否應忽略具有無效名稱的標頭字段。有效名稱由英文字母，數字，連字符和可能的下划線組成（由underscores_in_headers指令控制）。

underscores_in_headers

• 啟用或禁用客戶端請求標頭字段中下划線的使用
• on|off
• 1

啟用或禁用客戶端請求標頭字段中下划線的使用。禁用下划線時，名稱包含下划線的請求標頭字段將標記為無效，並受到ignore_invalid_headers指令的約束。

ACL(訪問控制列表) directives

allow

• 允許訪問指定的網絡或地址。
• address | CIDR | all
• 1

deny

• 拒絕訪問指定的網絡或地址。
• address | CIDR | all
• 1

Rewrite directives

more_set_headers

• 替換（如果有）或添加（如果不是）任何指定的輸出頭。
• "header"
• 1

if

• 評估指定的條件。如果為true，則執行在大括號內指定的此模塊指令，並在if指令內為該請求分配配置;
• [condition]
• 1

評估指定的條件。如果為true，則執行在大括號內指定的此模塊指令，並在if指令內為該請求分配配置。
if指令內的配置繼承自先前的配置級別。

rewrite

• 如果指定的正則表達式與請求URI匹配，則URI將根據替換字符串中的指定進行更改。
• [regex] [replacement] [flag]
• 3

如果指定的正則表達式與請求URI匹配，則URI將根據替換字符串中的指定進行更改。重寫指令按照它們在配置文件中的出現順序執行。可以使用標志終止對指令的進一步處理。如果替換字符串以“http：//”，“https：//”或“$ scheme”開頭，則處理停止並將重定向返回給客戶端。

set

• 設置指定變量的值。該值可以包含文本，變量及其組合。
• [$variable] [value]
• 2

return

• 停止處理並將指定的代碼返回給客戶端。
• [code] [URL];
• 2

停止處理並將指定的代碼返回給客戶端。
非標准代碼444在不發送響應頭的情況下關閉連接。
從版本0.8.42開始，可以指定重定向URL（對於代碼301,302,303,307和308）或響應正文文本（對於其他代碼）。
響應正文文本和重定向URL可以包含變量。
作為特殊情況，可以將重定向URL指定為此服務器的本地URI，在這種情況下，根據請求方案（$ scheme）以及server_name_in_redirect和port_in_redirect指令形成完整重定向URL。
另外，可以將用於具有代碼302的臨時重定向的URL指定為唯一參數。
這樣的參數應該以“http：//”，“https：//”或“$ scheme”字符串開頭。
URL可以包含變量。

break

• 停止處理當前的ngx_http_rewrite_module指令集。
• 0

停止處理當前的ngx_http_rewrite_module指令集。
如果在該位置內指定了指令，則在該位置繼續進一步處理該請求。