nginx中文文档-ngx_http_proxy_module(P-R)

本文档包含以下指令:proxy_pass、proxy_pass_header、proxy_pass_request_body、proxy_pass_request_headers、proxy_read_timeout、proxy_redirect、proxy_request_buffering、

proxy_pass

语法:proxy_pass URL
默认:—
上下文:location, if in location, limit_except

设置被代理服务器的协议和地址,以及一个可选URI用于映射到location中。“http”和“https”可以作为协议指定。IP地址可以定义为一个域名或IP地址和一个可选的端口号:
proxy_pass http://localhost:8000/uri/;
或一个UNIX-domain socket路径:
proxy_pass http://unix:/tmp/backend.socket:/uri/;
如果域名解析成多个地址,则会使用轮询的方式使用。地址可以被定义为服务器组。
请求URI传给服务器如下:

  • 如果proxy_pass指令通过URI指定,当请求发送给服务器时,统一化的请求URI匹配location的部分会被指定的URI替换:
  • location /name/ {
        proxy_pass http://127.0.0.1/remote/;
    }
    
  • 如果proxy_pass没有指定URI,请求URI传送给服务器与客户端发送的形式相同,或是完整的统一化的URI:
location /some/path/ {
    proxy_pass http://127.0.0.1;
}

在1.1.12版本之前,如果proxy_pass没有指定URI,某些情况下原始的请求URI会被传递而不是处理过的URI。
有些情况下,请求URI被替换的部分不能够确定:

  • 当location使用正则表达式定义。这种情况下,指令应该不带URI
  • 当URI在代理location中使用rewrite指令改变,并且这个配置同时用于处理请求:
location /name/ {
    rewrite    /name/([^/]+) /users?name=$1 break;
    proxy_pass http://127.0.0.1;
}

这种情况下,定义在指令中的URI被忽略,然后全部被改变后的URI会传给服务器。
服务器的名称端口和URI可以使用变量:
proxy_pass http://$host$uri;
甚至可以这样:
proxy_pass $request;
这种情况下,服务器名称会在服务器组中查找,如果查不到,就会用resolver。
WebSocket代理需要特殊的配置,并从1.3.13版本开始支持。

proxy_pass_header

语法:proxy_pass_header field
默认:—
上下文:http, server, location

允许被禁用的头部从被代理服务器发送到客户端。

proxy_pass_request_body

语法:proxy_pass_request_body on | off
默认:proxy_pass_request_body on
上下文:http, server, location

声明原始请求体是否会被传给被代理服务器。

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

语法:proxy_pass_request_headers on | off
默认:proxy_pass_request_headers on
上下文:http, server, location

声明原始请求头是否会传给被代理服务器。

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_read_timeout

语法:proxy_read_timeout time
默认:proxy_read_timeout 60s
上下文:http, server, location

定义从被代理服务器读取响应的超时时间。超时时间设置为两次成功的读操作之间,不是整个响应的传输。如果被代理服务器在这个时间没有传输任何数据,连接将被关闭。

proxy_redirect

语法:proxy_redirect default
proxy_redirect off
proxy_redirect redirect replacement
默认:proxy_redirect default
上下文:http, server, location

设置被代理服务器响应头中“Location”和“Refresh”头域需要改变的文本。假设被代理服务器返回了一个头域“Location: http://localhost:8000/two/some/uri/”。指令
proxy_redirect http://localhost:8000/two/ http://frontend/one/;
将会重写这个字符串为“Location: http://frontend/one/some/uri/”。
一个服务器名称可以在replacement字符串中省略:
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_pass使用了变量,不能用default参数。
replacement字符串可以包含变量:
proxy_redirect http://localhost: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 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/ /;

使用这个指令,可能会在被代理服务器的相对重定向中添加host名称:
proxy_redirect / /;

proxy_request_buffering

语法:proxy_request_buffering on | off
默认:proxy_request_buffering on
上下文:http, server, location
版本:1.7.11+

启用或禁用客户端请求体的缓冲区。
当缓冲区启用,整个请求体会在发送到被代理服务器之前从客户端完全读取。
当缓冲区禁用,请求体在收到后立即发送给被代理服务器。这种情况下,如果nginx已经开始发送请求体就不能将请求发到下一个服务器上。
当使用HTTP1.1chunked传输编码发送原始请求体时,请求体将会被缓冲不管指令的值,除非启用HTTP1.1代理。