HTTP代理模組（HTTP Proxy）

HTTP代理模組（HTTP Proxy） 回目錄 ·摘要 這個模組可以轉寄請求到其他的伺服器。 HTTP/1.0無法使用keepalive（後端伺服器將為每個請求建立並且刪除串連）。nginx為瀏覽器發送HTTP/1.1並為後端伺服器發送HTTP/1.0，這樣瀏覽器就可以為瀏覽器處理keepalive。 如下例： location / { proxy_pass http://localhost:8000; proxy_set_header X-Real-IP $remote_addr; }注意當使用http proxy模組（甚至FastCGI），所有的串連請求在發送到後端伺服器之前nginx將緩衝它們，因此，在測量從後端傳送的資料時，它的進度顯示可能不正確。 ·指令 proxy_buffer_size 文法：proxy_buffer_size the_size 預設值：proxy_buffer_size 4k/8k 使用欄位：http, server, location 設定從被Proxy 伺服器讀取的第一部分應答的緩衝區大小。 通常情況下這部分應答中包含一個小的應答頭。 預設情況下這個值的大小為指令proxy_buffers中指定的一個緩衝區的大小，不過可以將其設定為更小。 proxy_buffering 文法：proxy_buffering on|off 預設值：proxy_buffering on 使用欄位：http, server, location 為後端的伺服器啟用應答緩衝。 如果啟用緩衝，nginx假設被Proxy 伺服器能夠非常快的傳遞應答，並將其放入緩衝區，可以使用 proxy_buffer_size和proxy_buffers設定相關參數。 如果響應無法全部放入記憶體，則將其寫入硬碟。 如果禁用緩衝，從後端傳來的應答將立即被傳送到用戶端。 nginx忽略被Proxy 伺服器的應答數目和所有應答的大小，接受proxy_buffer_size所指定的值。 對於基於長輪詢的Comet應用需要關閉這個指令，否則非同步應答將被緩衝並且Comet無法正常工作。 proxy_buffers 文法：proxy_buffers the_number is_size; 預設值：proxy_buffers 8 4k/8k; 使用欄位：http, server, location 設定用於讀取應答（來自被Proxy 伺服器）的緩衝區數目和大小，預設情況也為分頁大小，根據作業系統的不同可能是4k或者8k。 proxy_busy_buffers_size 文法：proxy_busy_buffers_size size; 預設值：proxy_busy_buffers_size ["#proxy buffer size"] * 2; 使用欄位：http, server, location, if 未知。 proxy_cache 文法：proxy_cache zone_name; 預設值：None 使用欄位：http, server, location 設定一個快取區域的名稱，一個相同的地區可以在不同的地方使用。在0.7.48後，緩衝遵循後端的Cache-Control, Expires以及其他等。緩衝依賴代理的緩衝區，如果proxy_buffers設定為off，將不會生效。 proxy_cache_path 文法：proxy_cache_path path [levels=number] keys_zone=zone_name:zone_size [inactive=time] [max_size=size]; 預設值：None 使用欄位：http 指令指定緩衝的路徑和一些其他參數，緩衝的資料存放區在檔案中。緩衝的檔案名稱和key為代理URL的MD5 碼。levels參數指定緩衝的子目錄數，例如： proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;檔案名稱類似於： /data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c 所有活動的key和中繼資料存放區在共用的記憶體地區中，這個地區用keys_zone參數指定，如果在inactive參數指定的時間內緩衝的資料沒有被請求則被刪除，預設inactive為10分鐘。 cache manager進程式控制制磁碟的緩衝大小，在max_size參數中定義，超過其大小後最少使用資料將被刪除。 地區的大小按照快取頁面面數的比例進行設定，一個頁面（檔案）的中繼資料大小按照作業系統來定，FreeBSD/i386下為64位元組，FreeBSD/amd64下為128位元組，當地區滿了以後key將按照LRU（最近最少使用演算法）進行處理。 proxy_cache_path和proxy_temp_path應該使用在相同的檔案系統上。 proxy_cache_methods 文法：proxy_cache_methods [GET HEAD POST]; 預設值：proxy_cache_methods GET HEAD; 使用欄位：http, server, location GET/HEAD用來裝飾語句，即你無法禁用GET/HEAD即使你只使用下列語句設定： proxy_cache_methods POST; proxy_cache_min_uses 文法：proxy_cache_min_uses the_number; 預設值：proxy_cache_min_uses 1; 使用欄位：http, server, location 多少次的查詢後應答將被緩衝，預設1。 proxy_cache_valid 文法：proxy_cache_valid reply_code [reply_code ...] time; 預設值：None 使用欄位：http, server, location 為不同的應答設定不同的緩衝時間，例如： proxy_cache_valid 200 302 10m; proxy_cache_valid 404 1m;為應答代碼為200和302的設定緩衝時間為10分鐘，404代碼緩衝1分鐘。 如果只定義時間： proxy_cache_valid 5m;那麼只對代碼為200, 301和302的應答進行緩衝。 同樣可以使用any參數任何應答。 proxy_cache_valid 200 302 10m; proxy_cache_valid 301 1h; proxy_cache_valid any 1m; proxy_cache_use_stale 文法：proxy_cache_use_stale [error|timeout|updating|invalid_header|http_500|http_502|http_503|http_504|http_404|off] [...]; 預設值：proxy_cache_use_stale off; 使用欄位：http, server, location 未知。 這個指令的參數類似於proxy_next_upstream指令。 proxy_connect_timeout 文法：proxy_connect_timeout timeout_in_seconds 使用欄位：http, server, location 指定一個串連到Proxy 伺服器的逾時時間，這個時間並不是指伺服器傳回頁面的時間，而是proxy_read_timeout的聲明。無論何時你的Proxy 伺服器都是正常啟動並執行，但是如果伺服器遇到一些狀況（例如沒有足夠的線程去處理請求，請求將被放在一個串連池中延遲處理），那麼這個聲明無助於伺服器去建立串連。 proxy_headers_hash_bucket_size 文法：proxy_headers_hash_bucket_size size; 預設值：proxy_headers_hash_bucket_size 64; 使用欄位：http, server, location, if 設定雜湊表中儲存的每個資料大小（參考解釋）。 proxy_headers_hash_max_size 文法：proxy_headers_hash_max_size size; 預設值：proxy_headers_hash_max_size 512; 使用欄位：http, server, location, if 設定雜湊表的最大值（參考解釋）。 proxy_hide_header 文法：proxy_hide_header the_header 使用欄位：http, server, location nginx不對從被Proxy 伺服器傳來的"Date", "Server", "X-Pad"和"X-Accel-..."應答進行轉寄，這個參數允許隱藏一些其他的頭部欄位，但是如果上述提到的頭部欄位必須被轉寄，可以使用proxy_pass_header指令，例如：需要隱藏MS-OfficeWebserver和AspNet-Version可以使用如下配置： location / { proxy_hide_header X-AspNet-Version; proxy_hide_header MicrosoftOfficeWebServer; }當使用X-Accel-Redirect時這個指令非常有用。例如，你可能要在後端應用伺服器對一個需要下載的檔案設定一個返回頭，其中X-Accel-Redirect欄位即為這個檔案，同時要有恰當的Content-Type，但是，重新導向的URL將指向包含這個檔案的檔案伺服器，而這個伺服器傳遞了它自己的Content-Type，可能這並不是正確的，這樣就忽略了後端應用伺服器傳遞的Content-Type。為了避免這種情況你可以使用這個指令： location / { proxy_pass http://backend_servers; } location /files/ { proxy_pass http://fileserver; proxy_hide_header Content-Type; proxy_ignore_client_abort 文法：proxy_ignore_client_abort [ on|off ] 預設值：proxy_ignore_client_abort off 使用欄位：http, server, location 防止在用戶端自己終端請求的情況下中斷代理請求。 proxy_ignore_headers 文法：proxy_ignore_headers name [name ...] 預設值：none 使用欄位：http, server, location 這個指令(0.7.54+) 禁止處理來自Proxy 伺服器的應答。 可以指定的欄位為"X-Accel-Redirect", "X-Accel-Expires", "Expires"或"Cache-Control"。 proxy_intercept_errors 文法：proxy_intercept_errors [ on|off ] 預設值：proxy_intercept_errors off 使用欄位：http, server, location 使nginx阻止HTTP應答代碼為400或者更高的應答。 預設情況下被Proxy 伺服器的所有應答都將被傳遞。 如果將其設定為on則nginx會將阻止的這部分代碼在一個error_page指令處理，如果在這個error_page中沒有匹配的處理方法，則被Proxy 伺服器傳遞的錯誤應答會按原樣傳遞。 proxy_max_temp_file_size 文法：proxy_max_temp_file_size size; 預設值：proxy_max_temp_file_size 1G; 使用欄位：http, server, location, if 當代理緩衝區過大時使用一個臨時檔案的最大值，如果檔案大於這個值，將同步傳遞請求而不寫入磁碟進行緩衝。 如果這個值設定為零，則禁止使用臨時檔案。 proxy_method 文法：proxy_method [method] 預設值：None 使用欄位：http, server, location 允許代理一些其他的HTTP存取方法。 如果指定這個指令，nginx只允許一個請求中含有單個HTTP存取方法的請求（在該指令中指定），所以對於代理Subversion這樣的請求並不是很有用。 樣本配置： proxy_method PROPFIND; proxy_next_upstream 文法： proxy_next_upstream [error|timeout|invalid_header|http_500|http_502|http_503|http_504|http_404|off] 預設值：proxy_next_upstream error timeout 使用欄位：http, server, location 確定在何種情況下請求將轉寄到下一個伺服器： ·error - 在串連到一個伺服器，發送一個請求，或者讀取應答時發生錯誤。 ·timeout - 在串連到伺服器，轉寄請求或者讀取應答時發生逾時。 ·invalid_header - 伺服器返回空的或者錯誤的應答。 ·http_500 - 伺服器返回500代碼。 ·http_502 - 伺服器返回502代碼。 ·http_503 - 伺服器返回503代碼。 ·http_504 - 伺服器返回504代碼。 ·http_404 - 伺服器返回404代碼。 ·off - 禁止轉寄請求到下一台伺服器。 轉寄請求只發生在沒有資料傳遞到用戶端的過程中。 proxy_pass 文法：proxy_pass URL 預設值：no 使用欄位：location, location中的if欄位 確定需要代理的URL，連接埠和socket。 可以使用主機名稱和連接埠，例如： proxy_pass http://localhost:8000/uri;也可以使用unix socket： proxy_pass unix:/path/to/backend.socket請求轉寄到伺服器的URI部分（location欄位的後面部分），將為proxy_pass指定的值的URI。例如你的location欄位為/name/，proxy_pass為http://127.0.0.1，則請求/name/test將被轉寄至http://127.0.0.1/test。 但是對於上述規則有兩個例外，那時將無法確定被替換的location： location使用Regex。 在使用代理的location中利用rewrite指令改變URI，使用這個配置可以更加精確的處理請求（break）: location /name/ { rewrite /name/([^/] +) /users?name=ũ break; proxy_pass http://127.0.0.1; }這些情況下URI並沒有被映射傳遞。 此外，可能需要指明URI將使用同樣的方式轉寄，因為它是來自用戶端，而不是以處理過的形式發送。 在其工作過程中： ·兩個以上的斜杠將被替換為一個： "//" -- "/"; ·刪除引用的目前的目錄："/./" -- "/"; ·刪除引用的先前目錄："/dir /../" -- "/"。如果在伺服器上必須以未經過處理的形式發送URI，那麼在這個指令中必須使用未指定URI的URL： location /some/path/ { proxy_pass http://127.0.0.1; }在指令中使用變數是一種比較特殊的情況：被請求的URL不會使用並且你必須完全手工標記URL。 這意味著下列的配置並不能讓你方便的進入某個你想要的虛擬機器主機目錄，代理總是將它轉寄到相同的URL（在一個server欄位的配置）： location / { proxy_pass http://127.0.0.1:8080/VirtualHostBase/https/$server_name:443/some/path/VirtualHostRoot; }解決方案是使用rewrite和proxy_pass的組合： location / { rewrite ^(.*)$ /VirtualHostBase/https/$server_name:443/some/path/VirtualHostRoot/ũ break; proxy_pass http://127.0.0.1:8080; }這種情況下請求的URL將被重寫， proxy_pass中的拖尾斜杠並沒有實際意義。 proxy_pass_header 文法：proxy_pass_header the_name 使用欄位：http, server, location 這個指令允許轉寄一些被禁止的應答頭。 如： location / { proxy_pass_header Server; proxy_pass_header X-MyHeader; } proxy_pass_request_body 文法：proxy_pass_request_body [ on | off ] ; 預設值：proxy_pass_request_body on; 使用欄位：http, server, location 可用版本：0.1.29 proxy_pass_request_headers 文法：proxy_pass_request_headers [ on | off ] ; 預設值：proxy_pass_request_headers on; 使用欄位：http, server, location 可用版本：0.1.29 proxy_redirect 文法：proxy_redirect [ default|off|redirect replacement ] 預設值：proxy_redirect default 使用欄位：http, server, location 如果需要修改從被Proxy 伺服器傳來的應答頭中的"Location"和"Refresh"欄位，可以用這個指令設定。 假設被Proxy 伺服器返回Location欄位為： http://localhost:8000/two/some/uri/ 這個指令： proxy_redirect http://localhost:8000/two/ http://frontend/one/;將Location欄位重寫為http://frontend/one/some/uri/。 在代替的欄位中可以不寫伺服器名： proxy_redirect http://localhost: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_redirect http://localhost:8000/ http://$host:$server_port/;這個指令有時可以重複： proxy_redirect default; proxy_redirect http://localhost:8000/ /; proxy_redirect http://www.example.com/ /;參數off將在這個欄位中禁止所有的proxy_redirect指令： proxy_redirect off; proxy_redirect default; proxy_redirect http://localhost:8000/ /; proxy_redirect http://www.example.com/ /;利用這個指令可以為被Proxy 伺服器發出的相對重新導向增加主機名稱： proxy_redirect / /; proxy_read_timeout 文法：proxy_read_timeout the_time 預設值：proxy_read_timeout 60 使用欄位：http, server, location 決定讀取後端伺服器應答的超市時間，它決定nginx將等待多久時間來取得一個請求的應答。逾時時間是指完成了兩次握手後並且狀態為established的逾時時間，而不是所有的應答時間。 相對於proxy_connect_timeout，這個時間可以撲捉到一台將你的串連放入串連池延遲處理並且沒有資料傳送的伺服器，注意不要將此值設定太低，某些情況下Proxy 伺服器將花很長的時間來獲得頁面應答（如當接收一個需要很多計算的報表時），當然你可以設定多個不同的location。 如果被Proxy 伺服器在設定的時間內沒有傳遞資料，nginx將關閉串連。 proxy_redirect_errors 不推薦使用，請使用 proxy_intercept_errors。 proxy_send_lowat 文法：proxy_send_lowat [ on | off ] 預設值：proxy_send_lowat off; 使用欄位：http, server, location, if 設定SO_SNDLOWAT，這個指令僅用於FreeBSD。 proxy_send_timeout 文法：proxy_send_timeout time_in_seconds 預設值：proxy_send_timeout 60 使用欄位：http, server, location 設定Proxy 伺服器轉寄請求的逾時時間，同樣指完成兩次握手後的時間，如果超過這個時間Proxy 伺服器沒有資料轉寄到被Proxy 伺服器，nginx將關閉串連。 proxy_set_body 文法：proxy_set_body [ on | off ] 預設值：proxy_set_body off; 使用欄位：http, server, location, if 可用版本：0.3.10。 proxy_set_header 文法：proxy_set_header header value 預設值： Host and Connection 使用欄位：http, server, location 這個指令允許將發送到被Proxy 伺服器的要求標頭重新定義或者增加一些欄位。 這個值可以是一個文本，變數或者它們的組合。 proxy_set_header在指定的欄位中沒有定義時會從它的上級欄位繼承。 預設只有兩個欄位可以重新定義： proxy_set_header Host $proxy_host; proxy_set_header Connection Close;未修改的要求標頭“Host”可以用如下方式傳送： proxy_set_header Host $http_host;但是如果這個欄位在用戶端的要求標頭中不存在，那麼將沒有資料轉寄被Proxy 伺服器。 這種情況下最好使用$Host變數，它的值等於要求標頭中的"Host"欄位或伺服器名： proxy_set_header Host $host;此外，可以將被代理的連接埠與伺服器名稱一起傳遞： proxy_set_header Host $host:$proxy_port;如果設定為空白字串，則不會傳遞標頭部到後端，例如下列設定將禁止後端使用gzip壓縮： proxy_set_header Accept-Encoding ""; proxy_store 文法：proxy_store [on | off | path] 預設值：proxy_store off 使用欄位：http, server, location 這個指令設定哪些傳來的檔案將被儲存，參數"on"保持檔案與alias或root指令指定的目錄一致，參數"off"將關閉儲存，路徑名中可以使用變數： proxy_store /data/www$original_uri;應答頭中的"Last-Modified"欄位設定了檔案最後修改時間，為了檔案的安全，可以使用proxy_temp_path指定一個臨時檔案目錄。 這個指令為那些不是經常使用的檔案做一份本地拷貝。從而減少被Proxy 伺服器負載。 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不是一個緩衝，它更像是一個鏡像。 proxy_store_access 文法：proxy_store_access users:permissions [users:permission ...] 預設值：proxy_store_access user:rw 使用欄位：http, server, location 指定建立檔案和目錄的相關許可權，如： proxy_store_access user:rw group:rw all:r;如果正確指定了組和所有的許可權，則沒有必要去指定使用者的許可權： proxy_store_access group:rw all:r; proxy_temp_file_write_size 文法：proxy_temp_file_write_size size; 預設值：proxy_temp_file_write_size ["#proxy buffer size"] * 2; 使用欄位：http, server, location, if 設定在寫入proxy_temp_path時資料的大小，在預防一個背景工作處理序在傳遞檔案時阻塞太長。 proxy_temp_path 文法：proxy_temp_path dir-path [ level1 [ level2 [ level3 ] ; 預設值：在configure時由--http-proxy-temp-path指定 使用欄位：http, server, location 類似於http核心模組中的client_body_temp_path指令，指定一個地址來緩衝比較大的被代理請求。 proxy_upstream_fail_timeout 0.5.0版本後不推薦使用，請使用http負載平衡模組中server指令的fail_timeout參數。 proxy_upstream_fail_timeout 0.5.0版本後不推薦使用，請使用http負載平衡模組中server指令的max_fails參數。 ·變數 該模組中包含一些內建變數，可以用於proxy_set_header指令中以建立頭部。 $proxy_host 被Proxy 伺服器的主機名稱與連接埠號碼。 $proxy_host 被Proxy 伺服器的連接埠號碼。 $proxy_add_x_forwarded_for 包含用戶端要求標頭中的"X-Forwarded-For"，與$remote_addr用逗號分開，如果沒有"X-Forwarded-For"要求標頭，則$proxy_add_x_forwarded_for等於$remote_addr。 ·參考文檔