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 the_size

默认值: proxy_buffer_size 4k/8k

上下文: http, server, location



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


语法: proxy_buffering on|off

默认值: proxy_buffering on

上下文: http, server, location







语法: proxy_buffers the_number is_size;

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

上下文: http, server, location

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


语法: proxy_busy_buffers_size size;

默认值: proxy_busy_buffers_size proxy_buffer_size * 2;

上下文: http, server, location, if

TODO: Description.


语法: 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 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 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 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 [ on|off ]

默认值: proxy_ignore_client_abort off

上下文: http, server, location

Available since: 0.3.36


语法: 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 size;

默认值: proxy_max_temp_file_size 1G;

上下文: http, server, location, if

Available since: 0.1.8
TODO: Description.


语法: 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.


: proxy_method PROPFIND;


语法: 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:

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 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:

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

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:

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;


语法: 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 [ on | off ] ;

默认值: proxy_pass_request_body on;

上下文: http, server, location

Available since: 0.1.29
TODO: Description.


语法: proxy_pass_request_headers [ on | off ] ;

默认值: proxy_pass_request_headers on;

上下文: http, server, location

Available since: 0.1.29
TODO: Description.


语法: 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   /;

The parameter off forbids all proxy_redirect directives at this level:

: proxy_redirect   off;
: proxy_redirect   default;
: proxy_redirect   http://localhost:8000/    /;
: proxy_redirect   /;

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 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.


Deprecated. Use proxy_intercept_errors.


语法: 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 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_set_body [ on | off ]

默认值: proxy_set_body off;

上下文: http, server, location, if

Available since: 0.3.10
TODO: Description.


语法: 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 [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 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 size;

默认值: proxy_temp_file_write_size proxy_buffer_size * 2;

上下文: http, server, location, if

TODO: Description.


语法: 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.


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


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


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.


Original Documentation