模組 ngx_http_proxy_module

ngx_http_proxy_module 模組允許將請求傳遞到另一個伺服器。

location / {
    proxy_pass       https://127.0.0.1:8000;
    proxy_set_header Host      $host;
    proxy_set_header X-Real-IP $remote_addr;
}

使傳送至代理伺服器的連線源自指定的本地 IP 位址，並可選擇指定連接埠 (1.11.2)。參數值可以包含變數 (1.3.12)。特殊值 off (1.3.12) 會取消從先前的設定層級繼承的 proxy_bind 指令的效果，這允許系統自動指派本地 IP 位址和連接埠。

transparent 參數 (1.11.0) 允許傳送至代理伺服器的連線源自非本地 IP 位址，例如，用戶端的真實 IP 位址。

proxy_bind $remote_addr transparent;

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

proxy_buffer_size 4k|8k;

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

proxy_buffering on;

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

啟用緩衝時，nginx 會盡快收到來自代理伺服器的回應，並將其儲存到 proxy_buffer_size 和 proxy_buffers 指令設定的緩衝區中。如果整個回應不適合放入記憶體，則可以將一部分儲存到磁碟上的臨時檔案中。寫入臨時檔案由 proxy_max_temp_file_size 和 proxy_temp_file_write_size 指令控制。

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

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

proxy_buffers 8 4k|8k;

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

proxy_busy_buffers_size 8k|16k;

啟用來自代理伺服器的回應緩衝時，限制在回應尚未完全讀取時，可用於向用戶端傳送回應的緩衝區總 size。同時，其餘緩衝區可用於讀取回應，並在需要時將部分回應緩衝到臨時檔案。預設情況下，size 受限於 proxy_buffer_size 和 proxy_buffers 指令設定的兩個緩衝區的大小。

proxy_cache off;

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

proxy_cache_background_update off;

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

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

proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;

可以與 proxy_no_cache 指令一起使用。

proxy_cache_convert_head on;

啟用或停用將「HEAD」方法轉換為「GET」以進行快取。停用轉換時，應將 快取鍵 設定為包含 $request_method。

proxy_cache_key $scheme$proxy_host$request_uri;

定義快取的鍵，例如

proxy_cache_key "$host$request_uri $cookie_user";

預設情況下，指令的值與字串接近

proxy_cache_key $scheme$proxy_host$uri$is_args$args;

proxy_cache_lock off;

啟用後，每次只允許一個請求根據 proxy_cache_key 指令所識別的新快取元素，將請求傳遞到代理伺服器。相同快取元素的其他請求將等待回應出現在快取中，或等待此元素的快取鎖定被釋放，直到 proxy_cache_lock_timeout 指令設定的時間為止。

proxy_cache_lock_age 5s;

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

proxy_cache_lock_timeout 5s;

設定 proxy_cache_lock 的逾時。當 time 到期時，請求將會傳遞到代理伺服器，但是不會快取回應。

在 1.7.8 之前，可以快取回應。

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

proxy_cache_methods GET HEAD;

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

proxy_cache_min_uses 1;

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

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

proxy_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，則會使用給定位置的 proxy_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 (No Content) 響應表示。

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

組態範例

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

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

server {
    ...
    location / {
        proxy_pass http://backend;
        proxy_cache cache_zone;
        proxy_cache_key $uri;
        proxy_cache_purge $purge_method;
    }
}

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

proxy_cache_revalidate off;

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

proxy_cache_use_stale off;

決定在與代理伺服器通訊期間，在哪些情況下可以使用過期的快取響應。此指令的參數與proxy_next_upstream 指令的參數相符。

如果無法選取代理伺服器來處理請求，則 error 參數也允許使用過期的快取響應。

此外，如果快取響應目前正在更新，updating 參數允許使用過期的快取響應。這允許在更新快取資料時，盡可能減少對代理伺服器的存取次數。

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

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

若要在填入新的快取元素時盡可能減少對代理伺服器的存取次數，可以使用proxy_cache_lock 指令。

設定不同響應代碼的快取時間。例如，下列指令

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

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

如果只指定快取 time

proxy_cache_valid 5m;

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

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

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

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

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

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

proxy_connect_timeout 60s;

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

proxy_cookie_domain off;

設定應該在代理伺服器響應的「Set-Cookie」標頭欄位的 domain 屬性中變更的文字。假設代理伺服器返回的「Set-Cookie」標頭欄位具有「domain=localhost」屬性。此指令

proxy_cookie_domain localhost example.org;

會將此屬性重寫為「domain=example.org」。

會忽略 domain 和 replacement 字串開頭以及 domain 屬性中的點。比對不區分大小寫。

domain 和 replacement 字串可以包含變數

proxy_cookie_domain www.$host $host;

也可以使用正規表示式指定此指令。在這種情況下，domain 應以「~」符號開頭。正規表示式可以包含具名和位置擷取，而 replacement 可以參考它們

proxy_cookie_domain ~\.(?P<sl_domain>[-0-9a-z]+\.[a-z]+)$ $sl_domain;

可以在相同層級指定多個 proxy_cookie_domain 指令

proxy_cookie_domain localhost example.org;
proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;

如果多個指令可以應用到 Cookie，則會選擇第一個符合的指令。

off 參數會取消從先前組態層級繼承的 proxy_cookie_domain 指令的效力。

proxy_cookie_flags off;

為 Cookie 設定一個或多個旗標。cookie 可以包含文字、變數及其組合。flag 可以包含文字、變數及其組合 (1.19.8)。secure、httponly、samesite=strict、samesite=lax、samesite=none 參數會新增相應的旗標。nosecure、nohttponly、nosamesite 參數會移除相應的旗標。

也可以使用正規表示式指定 Cookie。在這種情況下，cookie 應以「~」符號開頭。

可以在相同的組態層級指定多個 proxy_cookie_flags 指令

proxy_cookie_flags one httponly;
proxy_cookie_flags ~ nosecure samesite=strict;

如果多個指令可以應用到 Cookie，則會選擇第一個符合的指令。在範例中，會將 httponly 旗標新增至 Cookie one，對於所有其他 Cookie，則新增 samesite=strict 旗標，並刪除 secure 旗標。

off 參數會取消從先前組態層級繼承的 proxy_cookie_flags 指令的效力。

proxy_cookie_path off;

設定應該在代理伺服器響應的「Set-Cookie」標頭欄位的 path 屬性中變更的文字。假設代理伺服器返回的「Set-Cookie」標頭欄位具有「path=/two/some/uri/」屬性。此指令

proxy_cookie_path /two/ /;

會將此屬性重寫為「path=/some/uri/」。

path 和 replacement 字串可以包含變數。

proxy_cookie_path $uri /some$uri;

這個指令也可以使用正規表示式來指定。在這種情況下，path 應該以 "~" 符號開始，表示區分大小寫的匹配，或是以 "~*" 符號開始，表示不區分大小寫的匹配。正規表示式可以包含具名和位置捕獲，而 replacement 可以參考它們。

proxy_cookie_path ~*^/user/([^/]+) /u/$1;

可以在同一層級指定多個 proxy_cookie_path 指令。

proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;

如果多個指令可以應用到 Cookie，則會選擇第一個符合的指令。

off 參數會取消從先前的組態層級繼承的 proxy_cookie_path 指令的效果。

proxy_force_ranges off;

無論被代理伺服器回應中的 “Accept-Ranges” 欄位為何，都啟用來自被代理伺服器的快取和非快取回應的位元組範圍支援。

proxy_headers_hash_bucket_size 64;

設定 proxy_hide_header 和 proxy_set_header 指令所使用的雜湊表儲存桶 size。雜湊表設定的詳細資訊在另一個文件中提供。

proxy_headers_hash_max_size 512;

設定 proxy_hide_header 和 proxy_set_header 指令所使用的雜湊表的最大 size。雜湊表設定的詳細資訊在另一個文件中提供。

預設情況下，nginx 不會將被代理伺服器的回應中的標頭欄位 “Date”、“Server”、“X-Pad” 和 “X-Accel-...” 傳遞給用戶端。proxy_hide_header 指令設定額外的欄位，這些欄位將不會被傳遞。相反地，如果需要允許傳遞欄位，可以使用 proxy_pass_header 指令。

proxy_http_version 1.0;

設定代理的 HTTP 協定版本。預設情況下，使用 1.0 版本。建議將 1.1 版本與 keepalive 連線和 NTLM 驗證一起使用。

proxy_ignore_client_abort off;

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

停用處理來自被代理伺服器的特定回應標頭欄位。可以忽略下列欄位：“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” 設定回應所需的字元集。

proxy_intercept_errors off;

決定是否應該將代碼大於或等於 300 的被代理回應傳遞給用戶端，或是將其攔截並重新導向到 nginx 以使用 error_page 指令進行處理。

proxy_limit_rate 0;

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

proxy_max_temp_file_size 1024m;

當啟用來自被代理伺服器的回應緩衝，且整個回應無法放入由 proxy_buffer_size 和 proxy_buffers 指令設定的緩衝區時，部分回應可能會儲存到暫存檔。這個指令設定暫存檔的最大 size。一次寫入暫存檔的資料大小由 proxy_temp_file_write_size 指令設定。

零值會停用將回應緩衝至暫存檔的功能。

這個限制不適用於將被快取或儲存到磁碟的回應。

指定在轉送到被代理伺服器的請求中使用的 HTTP method，而不是來自用戶端請求的方法。參數值可以包含變數 (1.11.6)。

proxy_next_upstream error timeout;

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

error

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

timeout

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

invalid_header

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

http_500

伺服器傳回代碼 500 的回應；

http_502

伺服器傳回代碼 502 的回應；

http_503

伺服器傳回代碼 503 的回應；

http_504

伺服器傳回代碼 504 的回應；

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_502、http_503、http_504 和 http_429 的情況才被視為不成功的嘗試。http_403 和 http_404 的情況絕不會被視為不成功的嘗試。

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

proxy_next_upstream_timeout 0;

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

proxy_next_upstream_tries 0;

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

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

proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma    $http_authorization;

可以與 proxy_cache_bypass 指令一起使用。

設定被代理伺服器的協定和位址，以及位置應對應的可選 URI。作為協定，可以指定 “http” 或 “https”。位址可以指定為網域名稱或 IP 位址，以及可選的連接埠

proxy_pass https://127.0.0.1:8000/uri/;

或是在 “unix” 字詞後指定，並以冒號括住的 UNIX 網域套接字路徑

proxy_pass http://unix:/tmp/backend.socket:/uri/;

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

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

請求 URI 的傳遞方式如下：

• 如果 proxy_pass 指令是使用 URI 指定的，則當請求傳遞到伺服器時，符合位置的正規化請求 URI 部分會被指令中指定的 URI 取代。

  location /name/ {
      proxy_pass http://127.0.0.1/remote/;
  }
  

• 如果 proxy_pass 是在未指定 URI 的情況下指定，則請求 URI 會以與用戶端傳送的原始請求處理時相同的形式傳遞到伺服器，或者在處理變更的 URI 時傳遞完整的正規化請求 URI。

  location /some/path/ {
      proxy_pass http://127.0.0.1;
  }
  

  在 1.1.12 版本之前，如果在未指定 URI 的情況下指定 proxy_pass，則在某些情況下可能會傳遞原始請求 URI 而不是變更的 URI。

在某些情況下，無法確定要取代的請求 URI 部分。

• 當位置使用正規表示式指定時，以及在具名位置內時。

  在這些情況下，應在未指定 URI 的情況下指定 proxy_pass。

• 當使用 rewrite 指令在代理位置內變更 URI，且此相同組態將用於處理請求 (break) 時。

  location /name/ {
      rewrite    /name/([^/]+) /users?name=$1 break;
      proxy_pass http://127.0.0.1;
  }
  

  在這種情況下，會忽略指令中指定的 URI，並將完整的變更請求 URI 傳遞到伺服器。

• 當在 proxy_pass 中使用變數時。

  location /name/ {
      proxy_pass http://127.0.0.1$request_uri;
  }
  

  在這種情況下，如果指令中指定了 URI，則會將其按原樣傳遞到伺服器，並取代原始請求 URI。

WebSocket 代理需要特殊組態，並且自 1.3.13 版本起支援。

允許將否則已停用的標頭欄位從被代理伺服器傳遞到用戶端。

proxy_pass_request_body on;

指出是否將原始請求主體傳遞到被代理伺服器。

location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";

    proxy_pass ...
}

另請參閱 proxy_set_header 和 proxy_pass_request_headers 指令。

proxy_pass_request_headers on;

指出是否將原始請求的標頭欄位傳遞到被代理伺服器。

location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_headers off;
    proxy_pass_request_body off;

    proxy_pass ...
}

另請參閱 proxy_set_header 和 proxy_pass_request_body 指令。

proxy_pass_trailers off;

允許將尾部欄位從被代理伺服器傳遞到用戶端。

HTTP/1.1 中的尾部區段是明確啟用的。

location / {
    proxy_http_version 1.1;
    proxy_set_header Connection "te";
    proxy_set_header TE "trailers";
    proxy_pass_trailers on;

    proxy_pass ...
}

proxy_read_timeout 60s;

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

proxy_redirect default;

設定在代理伺服器回應的 “Location” 和 “Refresh” 標頭欄位中應該被更改的文字。假設一個代理伺服器返回的標頭欄位為 “Location: https://127.0.0.1:8000/two/some/uri/”。以下指令：

proxy_redirect https://127.0.0.1:8000/two/ http://frontend/one/;

會將此字串重寫為 “Location: http://frontend/one/some/uri/”。

伺服器名稱可以在 replacement 字串中省略

proxy_redirect https://127.0.0.1:8000/two/ /;

然後會插入主要伺服器的名稱和端口，如果端口與 80 不同。

由 default 參數指定的預設取代方式使用 location 和 proxy_pass 指令的參數。因此，以下兩個配置是等效的

location /one/ {
    proxy_pass     http://upstream:port/two/;
    proxy_redirect default;

location /one/ {
    proxy_pass     http://upstream:port/two/;
    proxy_redirect http://upstream:port/two/ /one/;

如果使用變數指定 proxy_pass，則不允許使用 default 參數。

replacement 字串可以包含變數

proxy_redirect https://127.0.0.1:8000/ http://$host:$server_port/;

redirect 也可以包含 (1.1.11) 變數

proxy_redirect http://$proxy_host:8000/ /;

該指令可以 (1.1.11) 使用正規表示式指定。在這種情況下，redirect 應該以 “~” 符號開始表示區分大小寫的匹配，或者以 “~*” 符號開始表示不區分大小寫的匹配。正規表示式可以包含命名和位置捕獲，並且 replacement 可以引用它們

proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
proxy_redirect ~*/user/([^/]+)/(.+)$      http://$1.example.com/$2;

可以在同一層級指定多個 proxy_redirect 指令

proxy_redirect default;
proxy_redirect https://127.0.0.1:8000/  /;
proxy_redirect http://www.example.com/ /;

如果有多個指令可以應用於代理伺服器回應的標頭欄位，則會選擇第一個匹配的指令。

off 參數會取消從先前的配置層級繼承的 proxy_redirect 指令的效果。

使用此指令，也可以將主機名稱新增到代理伺服器發出的相對重新導向中

proxy_redirect / /;

proxy_request_buffering on;

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

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

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

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

proxy_send_lowat 0;

如果將指令設定為非零值，nginx 會嘗試通過使用 kqueue 方法的 NOTE_LOWAT 標誌，或具有指定 size 的 SO_SNDLOWAT socket 選項，來最小化傳送到代理伺服器的外發連線的傳送操作次數。

此指令在 Linux、Solaris 和 Windows 上會被忽略。

proxy_send_timeout 60s;

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

允許重新定義傳遞到代理伺服器的請求主體。value 可以包含文字、變數及其組合。

proxy_set_header Host $proxy_host;

proxy_set_header Connection close;

允許重新定義或附加欄位到傳遞到代理伺服器的請求標頭。。value 可以包含文字、變數及其組合。這些指令僅在目前的層級上沒有定義 proxy_set_header 指令時，才會從先前的配置層級繼承。預設情況下，只有兩個欄位會被重新定義

proxy_set_header Host       $proxy_host;
proxy_set_header Connection close;

如果啟用快取，則原始請求中的標頭欄位 “If-Modified-Since”、“If-Unmodified-Since”、“If-None-Match”、“If-Match”、“Range” 和 “If-Range” 不會傳遞到代理伺服器。

未變更的 “Host” 請求標頭欄位可以像這樣傳遞

proxy_set_header Host       $http_host;

但是，如果用戶端請求標頭中不存在此欄位，則不會傳遞任何內容。在這種情況下，最好使用 $host 變數 - 其值等於 “Host” 請求標頭欄位中的伺服器名稱，如果此欄位不存在，則等於主要伺服器名稱

proxy_set_header Host       $host;

此外，伺服器名稱可以與代理伺服器的端口一起傳遞

proxy_set_header Host       $host:$proxy_port;

如果標頭欄位的值為空字串，則此欄位不會傳遞到代理伺服器

proxy_set_header Accept-Encoding "";

proxy_socket_keepalive off;

設定傳送到代理伺服器的外發連線的 “TCP keepalive” 行為。預設情況下，操作系統的設定對 socket 生效。如果將指令設定為 “on” 值，則會為 socket 開啟 SO_KEEPALIVE socket 選項。

指定一個具有 PEM 格式憑證的 file，用於向代理 HTTPS 伺服器進行驗證。

自 1.21.0 版本起，可以在 file 名稱中使用變數。

指定一個具有 PEM 格式金鑰的 file，用於向代理 HTTPS 伺服器進行驗證。

可以指定值 engine:name:id 來代替 file (1.7.9)，這會從 OpenSSL engine name 載入具有指定 id 的金鑰。

自 1.21.0 版本起，可以在 file 名稱中使用變數。

proxy_ssl_ciphers DEFAULT;

指定對代理 HTTPS 伺服器發出請求時啟用的密碼。密碼以 OpenSSL 函式庫理解的格式指定。

可以使用 “openssl ciphers” 命令檢視完整清單。

在建立與代理 HTTPS 伺服器的連線時，設定任意 OpenSSL 配置 命令。

當使用 OpenSSL 1.0.2 或更高版本時，支援該指令。

可以在同一層級指定多個 proxy_ssl_conf_command 指令。這些指令僅在目前的層級上沒有定義 proxy_ssl_conf_command 指令時，才會從先前的配置層級繼承。

請注意，直接配置 OpenSSL 可能會導致意外行為。

指定一個具有 PEM 格式的撤銷憑證 (CRL) 的 file，用於驗證代理 HTTPS 伺服器的憑證。

啟用記錄代理 HTTPS 伺服器連線 SSL 金鑰，並指定金鑰記錄檔的路徑。金鑰會以與 Wireshark 相容的 SSLKEYLOGFILE 格式記錄。

此指令可作為我們的 商業訂閱的一部分使用。

proxy_ssl_name $proxy_host;

允許覆寫用於驗證代理 HTTPS 伺服器憑證的伺服器名稱，並在與代理 HTTPS 伺服器建立連線時透過 SNI 傳遞。

預設情況下，會使用 proxy_pass URL 的主機部分。

指定一個具有 金鑰的密碼的 file，其中每個密碼都在單獨的行上指定。載入金鑰時會依序嘗試密碼。

proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

為對代理 HTTPS 伺服器的請求啟用指定的協定。

自 1.23.4 起，預設會使用 TLSv1.3 參數。

proxy_ssl_server_name off;

啟用或停用透過 TLS 伺服器名稱指示擴充 (SNI, RFC 6066) 傳遞伺服器名稱，以便在建立與代理 HTTPS 伺服器的連線時使用。

proxy_ssl_session_reuse on;

決定在使用代理伺服器時是否可以重複使用 SSL 會話。如果記錄中出現錯誤 “SSL3_GET_FINISHED:digest check failed”，請嘗試停用會話重複使用。

指定一個具有 PEM 格式的受信任 CA 憑證的 file，用於驗證代理 HTTPS 伺服器的憑證。

proxy_ssl_verify off;

啟用或停用驗證代理 HTTPS 伺服器憑證。

proxy_ssl_verify_depth 1;

設定代理 HTTPS 伺服器憑證鏈中的驗證深度。

proxy_store off;

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

proxy_store /data/www$original_uri;

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

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

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

location /fetch/ {
    internal;

    proxy_pass         http://backend/;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    alias              /data/www/;
}

或像這樣

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

location @fetch {
    internal;

    proxy_pass         http://backend;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    root               /data/www;
}

proxy_store_access user:rw;

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

proxy_store_access user:rw group:rw all:r;

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

proxy_store_access group:rw all:r;

proxy_temp_file_write_size 8k|16k;

限制一次寫入臨時檔案的資料 size，當啟用將來自代理伺服器的回應緩衝到臨時檔案時。預設情況下，size 會受到 proxy_buffer_size 和 proxy_buffers 指令設定的兩個緩衝區的限制。臨時檔案的最大大小由 proxy_max_temp_file_size 指令設定。

proxy_temp_path proxy_temp;

定義用於儲存從代理伺服器收到的資料的臨時檔案的目錄。可以在指定目錄下使用最多三層的子目錄階層。例如，在以下配置中

proxy_temp_path /spool/nginx/proxy_temp 1 2;

臨時檔案可能如下所示

/spool/nginx/proxy_temp/7/45/00000123457

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

ngx_http_proxy_module 模組支援嵌入式變數，這些變數可用於使用 proxy_set_header 指令組成標頭

$proxy_host

在 proxy_pass 指令中指定的代理伺服器的名稱和端口；

$proxy_port

在 proxy_pass 指令中指定的代理伺服器連接埠，或是該協定的預設連接埠；

$proxy_add_x_forwarded_for

「X-Forwarded-For」客戶端請求標頭欄位，並在其後附加 $remote_addr 變數，以逗號分隔。如果客戶端請求標頭中不存在「X-Forwarded-For」欄位，則 $proxy_add_x_forwarded_for 變數的值等於 $remote_addr 變數。