Nginx 中文官方手册基本模块HttpProxy模块
上一篇：Memcached 下一篇：HttpRewrite模块

HttpProxy模块

This module makes it possible to transfer requests to another server. 此模块专伺将请求导向其它服务.

It is an HTTP/1.0 proxy without the ability for keep-alive requests yet. 这是种 HTTP/1.0 版本的无请求保持代理.

(As a result, backend connections are created and destroyed on every request.) Nginx talks HTTP/1.1 to the browser and HTTP/1.0 to the backend server. As such it handles keep-alive to the browser.

(因为每个请求都是在后台连接中创建和销毁的) Nginx 和浏览器使用 HTTP/1.1 进行对话，而在后台服务中使用 HTTP/1.0;

示例

location / {
: proxy_pass        http://localhost:8000;
: proxy_set_header  X-Real-IP  $remote_addr;
}

注意一点,当使用HTTP PROXY 模块时(或者甚至是使用FastCGI时),用户的整个请求会在nginx中缓冲直至传送给后端被代理的服务器.因此,上传进度的测算就会运作得不正确,如果它们通过测算后端服务器收到的数据来工作的话

定向器. Directives

  • [#proxy_buffer_size proxy_buffer_size]
  • [#proxy_buffering proxy_buffering]
  • [#proxy_buffers proxy_buffers]
  • [#proxy_busy_buffers_size proxy_busy_buffers_size]
  • [#proxy_connect_timeout proxy_connect_timeout]
  • [#proxy_headers_hash_bucket_size proxy_headers_hash_bucket_size]
  • [#proxy_headers_hash_max_size proxy_headers_hash_max_size]
  • [#proxy_hide_header proxy_hide_header]
  • [#proxy_ignore_client_abort proxy_ignore_client_abort]
  • [#proxy_intercept_errors proxy_intercept_errors]
  • [#proxy_max_temp_file_size proxy_max_temp_file_size]
  • [#proxy_method proxy_method]
  • [#proxy_next_upstream proxy_next_upstream]
  • [#proxy_pass proxy_pass]
  • [#proxy_pass_header proxy_pass_header]
  • [#proxy_pass_request_body proxy_pass_request_body]
  • [#proxy_pass_request_headers proxy_pass_request_headers]
  • [#proxy_redirect proxy_redirect]
  • [#proxy_read_timeout proxy_read_timeout]
  • [#proxy_redirect_errors proxy_redirect_errors]
  • [#proxy_send_lowat proxy_send_lowat]
  • [#proxy_send_timeout proxy_send_timeout]
  • [#proxy_set_body proxy_set_body]
  • [#proxy_set_header proxy_set_header]
  • [#proxy_store proxy_store]
  • [#proxy_store_access proxy_store_access]
  • [#proxy_temp_file_write_size proxy_temp_file_write_size]
  • [#proxy_temp_path proxy_temp_path]
  • [#proxy_upstream_fail_timeout proxy_upstream_fail_timeout]
  • [#proxy_upstream_max_fails proxy_upstream_max_fails]

参数.Variables

  • [#var_proxy_host var_proxy_host]
  • [#var_proxy_port var_proxy_port]
  • [#var_proxy_add_x_forwarded_for var_proxy_add_x_forwarded_for]
  • [#var_proxy_remote_addr var_proxy_remote_addr]

proxy_buffer_size

语法:*proxy_buffer_size the_size*

默认值:*proxy_buffer_size 4k/8k*

上下文:*http, server, location*

该指令设置缓冲区大小,从被代理的后端服务器取得的响应内容,会先读取放置到这里.

小的响应header通常位于这部分响应内容里边.

默认来说,该缓冲区大小等于指令 proxy_buffers所设置的;但是,你可以把它设置得更小.

proxy_buffering

语法:*proxy_buffering on|off*

默认值:*proxy_buffering on*

上下文:*http, server, location*

该指令开启从后端被代理服务器的响应内容缓冲.

如果缓冲区开启,nginx假定被代理的后端服务器会以最快速度响应,并把内容保存在由指令proxy_buffer_size 和 proxy_buffers指定的缓冲区里边.

如果响应内容无法放在内存里边,那么部分内容会被写到磁盘上.

如果缓冲区被关闭了,那么响应内容会按照获取内容的多少立刻同步传送到客户端

nginx不尝试计算被代理服务器整个响应内容的大小,nginx能从服务器接受的最大数据,是由指令proxy_buffer_size指定的.

proxy_buffers

语法:*proxy_buffers the_number is_size;*

默认值:*proxy_buffers 8 4k/8k;*

上下文:*http, server, location*

该指令设置缓冲区的大小和数量,从被代理的后端服务器取得的响应内容,会放置到这里. 默认情况下,一个缓冲区的大小等于页面大小,可能是4K也可能是8K,这取决于平台

proxy_busy_buffers_size

语法:*proxy_busy_buffers_size size;*

默认值:*proxy_busy_buffers_size proxy_buffer_size 2;

上下文:*http, server, location, if*

TODO: Description.

proxy_connect_timeout

语法:*proxy_connect_timeout timeout_in_seconds*

上下文:*http, server, location*

This directive assigns a timeout for the connection to the proxyserver. This is not the time until the server returns the pages, this is the [#proxy_read_timeout proxy_read_timeout] statement. If your proxyserver is up, but hanging (e.g. it does not have enough threads to process your request so it puts you in the pool of connections to deal with later), then this statement will not help as the connection to the server has been made. It is necessary to keep in mind that this time out cannot be more than 75 seconds.

proxy_headers_hash_bucket_size

语法:*proxy_headers_hash_bucket_size size;*

默认值:*proxy_headers_hash_bucket_size 64;*

上下文:*http, server, location, if*

This directive sets the bucket size of the hashtable.
TODO: Better description

proxy_headers_hash_max_size

语法:*proxy_headers_hash_max_size size;*

默认值:*proxy_headers_hash_max_size 512;*

上下文:*http, server, location, if*

This directive sets the maximum size of the hashtable.
TODO: Better description

proxy_hide_header

语法:*proxy_hide_header the_header*

上下文:*http, server, location*

nginx does not transfer the "Date", "Server", "X-Pad" and "X-Accel-..." header lines from the proxied server response. The proxy_hide_header directive allows to hide some additional header lines. But if on the contrary the header lines must be passed, then the proxy_pass_header should be used. For example if you want to hide the MS-OfficeWebserver and the AspNet-Version:

location / {
: proxy_hide_header X-AspNet-Version;
: proxy_hide_header MicrosoftOfficeWebServer;
}

This directive can also be very helpful when using X-Accel-Redirect. For example, you may have one set of backend servers which return the headers for a file download, which includes X-Accel-Redirect to the actual file, as well as the correct Content-Type. However, the Redirect URL points to a filleserver which hosts the actual file you wish to serve, and that server sends its own Content-Type header, which might be incorrect, and overrides the header sent by the original backend servers. You can avoid this by adding the proxy_hide_header directive to the fileserver. Example:

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*

Available since: 0.3.36
如果客户端断开请求,也保持后端的下载

proxy_intercept_errors

语法:*proxy_intercept_errors [ on|off ]*

默认值:*proxy_intercept_errors off*

上下文:*http, server, location*

This directive decides if nginx will intercept responses with HTTP status codes of 400 and higher.

By default all responses will be sent as-is from the proxied server.

If you set this to on then nginx will intercept status codes that are explicitly handled by an error_page directive. Responses with status codes that do not match an error_page directive will be sent as-is from the proxied server.

proxy_max_temp_file_size

语法:*proxy_max_temp_file_size size;*

默认值:*proxy_max_temp_file_size 1G;*

上下文:*http, server, location, if*

Available since: 0.1.8
TODO: Description.

proxy_method

语法:*proxy_method [method]*

默认值:*None*

上下文:*http, server, location*

Used to allow the proxying of additional HTTP methods.

Note: at this time, Nginx only appears to allow a single instance of this directive and it only accepts a single argument (method) so it's not clear how useful this might be for proxying to things like Subversion.

Example:

: proxy_method PROPFIND;

proxy_next_upstream

语法:*proxy_next_upstream [error|timeout|invalid_header|http_500|http_503|http_404|off]*

默认值:*proxy_next_upstream error timeout*

上下文:*http, server, location*

Directive determines, in what cases the request will be transmitted to the next server:

  • error — an error has occurred while connecting to the server, sending a request to it, or reading its response;
  • timeout — occurred timeout during the connection with the server, transfer the requst or while reading response from the server;
  • invalid_header — server returned a empty or incorrect answer;
  • http_500 — server returned answer with code 500
  • http_503 — server returned answer with code 503
  • http_404 — server returned answer with code 404
  • off — it forbids the request transfer to the next server

Transferring the request to the next server is only possible when nothing has been transferred to the client -- that is, if an error or timeout arises in the middle of the transfer of the request, then it is not possible to retry the current request on a different server.

proxy_pass

语法:*proxy_pass URL*

默认值:*no*

上下文:*location, if in location*

This directive sets the port or socket, on which listens to the proxied server, and the URI, to which will be reflected location.

Port can be indicated in the form of the name of hostname or address and port, for example,

proxy_pass http://localhost:8000/uri /;

and socket -- in the form of unix of socket:

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

Path is indicated after the word unix and is concluded between two colons.

With the transfer of request to server part URI, which corresponds to location, is substituted to URI, indicated in directive proxy_pass.

But there are two exceptions to this rule, when it is not possible to determine that replaced location:

  • if the location is assigned by regular expression;
  • if inside proxied location with the help of directive rewrite changes URI and with this configuration will be precisely processed request (break):
location  /name/ {
: rewrite      /name/([^/] +)  /users?name=$1  break;
: proxy_pass   http://127.0.0.1;
}

For these cases of URI it is transferred without the mapping.

Furthermore, it is possible to indicate so that URI demand it would be transferred in the same form, as it sent client, but not v in the processed form.

During the working:

  • two or by more slashes are converted into one slash: "//" -- "/";
  • references to the current directory are removed: "/./" -- "/";
  • references to the previous catalog are removed: "/dir /../" -- "/".

If on server it is necessary to transmit URI in the unprocessed form, then for this in directive proxy_pass it is necessary to indicate URL server without URI:

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

proxy_pass_header

语法:*proxy_pass_header the_name*

上下文:*http, server, location*

This directive allows transferring header-lines forbidden for response.

For example:

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*

Available since: 0.1.29
TODO: Description.

proxy_pass_request_headers

语法:*proxy_pass_request_headers [ on | off ] ;*

默认值:*proxy_pass_request_headers on;*

上下文:*http, server, location*

Available since: 0.1.29
TODO: Description.

proxy_redirect

语法:*proxy_redirect [ default|off|redirect replacement ]*

默认值:*proxy_redirect default*

上下文:*http, server, location*

This directive sets the text, which must be changed in response-header "Location" and "Refresh" in the response of the proxied server.

Let us suppose the proxied server returned line Location: http://localhost:8000/two/some/uri/.

The directive


proxy_redirect   http://localhost:8000/two/   http://frontend/one/;

will rewrite this line in the form Location: http://frontend/one/some/uri/.

In the replaceable line it is possible not to indicate the name of the server:


proxy_redirect http://localhost:8000/two/ /;

then the basic name of server and port is set, if it is different from 80.

The change by default, given by the parameter "default", uses the parameters of directives location and proxy_pass.

Therefore two following configurations are equivalent:

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/;
}

In the replace line, it is possible to use some variables:

proxy_redirect   http://localhost:8000/    http://$host:$server_port/;

This directive repeated some times:


: proxy_redirect   default;
: proxy_redirect   http://localhost:8000/    /;
: proxy_redirect   http://www.example.com/   /;

The parameter off forbids all proxy_redirect directives at this level:

: proxy_redirect   off;
: proxy_redirect   default;
: proxy_redirect   http://localhost:8000/    /;
: proxy_redirect   http://www.example.com/   /;

With the help of this directive it is possible to add the name of host for relative redirect, issued by the proxied server:

proxy_redirect   /   /;

proxy_read_timeout

语法:*proxy_read_timeout the_time*

默认值:*proxy_read_timeout 60*

上下文:*http, server, location*

This directive sets the read timeout for the response of the proxied server. It determines how long NGINX will wait to get the response to a request. The timeout is established not for entire response, but only between two operations of reading.

In contrast to [#proxy_connect_timeout proxy_connect_timeout] , this timeout will catch a server that puts you in it's connection pool but does not respond to you with anything beyond that. Be careful though not to set this too low, as your proxyserver might take a longer time to respond to requests on purpose (e.g. when serving you a report page that takes some time to compute). You are able though to have a different setting per location, which enables you to have a higher proxy_read_timeout for the report page's location.

If the proxied server nothing will communicate after this time, then nginx is shut connection.

proxy_redirect_errors

Deprecated. Use proxy_intercept_errors.

proxy_send_lowat

语法:*proxy_send_lowat [ on | off ]*

默认值:*proxy_send_lowat off;*

上下文:*http, server, location, if*

This directive set SO_SNDLOWAT.
This directive is only available on FreeBSD

proxy_send_timeout

语法:*proxy_send_timeout time_in_seconds*

默认值:*proxy_send_timeout 60*

上下文:*http, server, location*

This directive assigns timeout with the transfer of request to the proxy server. Time out is established not on entire transfer of request, but only between two operations of record. If after this time the proxy server will not take new data, then nginx is shut the connection

proxy_send_lowat

语法:*proxy_set_body [ on | off ]*

默认值:*proxy_set_body off;*

上下文:*http, server, location, if*

Available since: 0.3.10
TODO: Description.

proxy_set_header

语法:*proxy_set_header header value*

默认值:*Host and Connection*

上下文:*http, server, location*

This directive allows to redefine and to add some request header lines which will be transferred to the proxied server.

As the value it is possible to use a text, variables and their combination.

This directive is inherited from the previous level when at this level are not described their directives proxy_set_header.

By default only two lines will be redefined:

proxy_set_header Host $proxy_host;
proxy_set_header Connection Close;

The unchanged request-header "Host" can be transmitted like this:


proxy_set_header Host $http_host;

However, if this line is absent from the client request, then nothing will be transferred.

In this case it is better to use variable $host, it's value is equal to the name of server in the request-header "Host" or to the basic name of server, if there is no line:

proxy_set_header Host $host;

Furthermore, it is possible to transmit the name of server together with the port of the proxied server:

proxy_set_header Host $host:$proxy_port;

proxy_store

语法:*proxy_store [on | off | path]*

默认值:*proxy_store off*

上下文:*http, server, location*

This directive sets the path in which upstream files are stored. The parameter "on" preserves files in accordance with path specified in directives alias or root. The parameter "off" forbids storing. Furthermore, the name of the path can be clearly assigned with the aid of the line with the variables:

proxy_store   /data/www$original_uri;

The time of modification for the file will be set to the date of "Last-Modified" header in the response. To be able to safe files in this directory it is necessary that the path is under the directory with temporary files, given by directive proxy_temp_path for the data location.

This directive can be used for creating the local copies for dynamic output of the backend which is not very often changed, for example:

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;
}

To be clear proxy_store is not a cache, it's rather mirror on demand.

proxy_store_access

语法:*proxy_store_access users:permissions [users:permission ...]*

默认值:*proxy_store_access user:rw*

上下文:*http, server, location*

This directive assigns the permissions for the created files and directories, for example:

proxy_store_access  user:rw  group:rw  all:r;

If any rights for groups or all are assigned, then it is not necessary to assign rights for user:

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*

TODO: Description.

proxy_temp_path

语法:*proxy_temp_path dir-path [ level1 [ level2 [ level3 ] ;*

默认值:*$NGX_PREFIX/proxy_temp controlled by --http-proxy-temp-path at ./configure stage*

上下文:*http, server, location*

This directive works like client_body_temp_path to specify a location to buffer large proxied requests to the filesystem.

proxy_upstream_fail_timeout

Changed in 0.5.0 to deprecated.
Please use the fail_timeout parameter of server Directive from the upstream module.

proxy_upstream_max_fails

Changed in 0.5.0 to deprecated.
Please use the max_fails parameter of server Directive from the upstream module.

Variables

In module ngx_http_proxy_module there are some built-in variables, which can be used for the creation of headers with the help of the proxy_set_header directive:

$proxy_host:: the name of proxied host and port;

$proxy_port:: the port of proxied host;

$proxy_add_x_forwarded_for:: equivalent to client request-header "X-Forwarded-For" and to variable added to it through the comma

$remote_addr:: But if there is no line "X-Forwarded-For" in the client request, then variable $proxy_add_x_forwarded_for is equal to variable $remote_addr.

References

Original Documentation

Questions

  • Is it possible to have the proxy use a client SSL certificate to communicate with the server being proxied? I am in the situation where I want to secure the proxy <-> application server connection. Another solution could be to use SSL only with a custom header checked at each connection in the application server, but doing it at the protocol level would be nicer.

  • NginxHttpProxyModule#preview 原文

上一篇：Memcached 下一篇：HttpRewrite模块