日期: 2016 年 5 月 19 日

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代理。