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

nginx中文文档-ngx_http_proxy_module(F-N)

本文档包含以下指令:proxy_force_ranges、proxy_headers_hash_bucket_size、proxy_headers_hash_max_size、proxy_hide_header、proxy_http_version、proxy_ignore_client_abort、proxy_ignore_headers、proxy_intercept_errors、proxy_limit_rate、proxy_max_temp_file_size、proxy_method、proxy_next_upstream、proxy_next_upstream_timeout、proxy_next_upstream_tries、proxy_no_cache

proxy_force_ranges

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

为从被代理服务器返回的缓存和非缓存响应开启byte-range支持,不管响应头中的“Accept-Ranges”。

proxy_headers_hash_bucket_size

语法:proxy_headers_hash_bucket_size size
默认:proxy_headers_hash_bucket_size 64
上下文:http, server, location

设置proxy_hide_header和proxy_set_header使用的哈希表大小。

proxy_headers_hash_max_size

语法:proxy_headers_hash_max_size size
默认:proxy_headers_hash_max_size 512
上下文:http, server, location

设置proxy_hide_header和proxy_set_header使用的哈希表最大大小。

proxy_hide_header

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

默认情况下,nginx不会将被代理服务器响应头“Date”、“Server”、“X-Pad”和“X-Accel-…”传给客户端。proxy_hide_header指令设置了其他不会传递的响应头。如果相反需要传某些头域,使用proxy_pass_header指令。

proxy_http_version

语法:proxy_http_version 1.0 | 1.1
默认:proxy_http_version 1.0
上下文:http, server, location
版本:1.1.4+

设置代理的HTTP协议版本,默认是1.0。

proxy_ignore_client_abort

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

决定当客户端没有等待响应就断开连接时,与被代理服务器连接是否需要关闭。

proxy_ignore_headers

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

禁用处理从被代理服务器返回的响应头。下面的头域可以忽略:“X-Accel-Redirect”, “X-Accel-Expires”, “X-Accel-Limit-Rate” (1.1.6), “X-Accel-Buffering” (1.1.6), “X-Accel-Charset” (1.1.6), “Expires”, “Cache-Control”, “Set-Cookie” (0.8.44), 和 “Vary” (1.7.7)。
如果不禁用,处理这些响应头有以下影响:

  • “X-Accel-Expires”, “Expires”, “Cache-Control”, “Set-Cookie”, 和“Vary”设置缓存的相关参数
  • “X-Accel-Redirect”产生指定URI的内部重定向
  • “X-Accel-Limit-Rate”设置传输响应到客户端的限速
  • “X-Accel-Buffering”启用或禁用响应的缓冲区
  • “X-Accel-Charset”设置希望响应的字符编码

proxy_intercept_errors

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

决定被代理服务器返回大于等于300的返回码时,直接传给客户端还是进入nginx的error_page指令进行处理。

proxy_limit_rate

语法:proxy_limit_rate rate
默认:proxy_limit_rate 0
上下文:http, server, location
版本:1.7.7+

限制从被代理服务器读取响应的速率。rate定义为每秒的字节数。零值禁用限速功能。限速针对于每一个请求,如果nginx同时向被代理服务器打开两个链接,整体的速率是设置值的二倍。只有读取响应缓冲区功能开启时限速才可用。

proxy_max_temp_file_size

语法:proxy_max_temp_file_size size
默认:proxy_max_temp_file_size 1024m
上下文:http, server, location

当启用了响应缓冲区功能,并且整个请求不能放到proxy_buffer_size和proxy_buffers指令设置的缓冲区中时,一部分响应会存到临时文件中。这个指令设置了临时文件的最大大小。一次写入到临时文件的数据大小由proxy_temp_file_write_size指令设置。
零值禁用缓冲区写入到临时文件功能。
这个限制对缓存或储存到磁盘上的请求不起作用。

proxy_method

语法:proxy_method method
默认:—
上下文:http, server, location

指定HTTP方法用于向被代理服务器发送请求,而不使用客户端请求的方法。

proxy_next_upstream

语法:proxy_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | non_idempotent | 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_403
服务器返回403错误码

http_404
服务器返回404错误码

non_idempotent
通常,非幂等的请求方法(POST、LOCK、PATCH)如果请求已经发送上游服务器(1.9.13+)将不会再传给下一个服务器。启用这个选项允许重试这些请求。

off
禁用传递请求到下一个服务器的功能。

应该了解的是,只有在没有任何数据发送给客户端时才可以将请求发送到下一个服务器。也就是说,如果在传输响应过程中发生了错误或超时,是不可能修复问题的。
该指令同时定义了与服务器通信时,哪些情况会被视为不成功的尝试。出错、超时以及非法头部总会视为不成功的尝试,即使它们没有定义在指令中。http_500, http_502, http_503 和 http_504只有定义在指令中时才会视为不成功的尝试。http_403 和 http_404从不会被认为是不成功的尝试。

proxy_next_upstream_timeout

语法:proxy_next_upstream_timeout time
默认:proxy_next_upstream_timeout 0
上下文:http, server, location
版本:1.7.5+

限制请求可以传给下一个服务器的时间。零值禁用这个限制。

proxy_next_upstream_tries

语法:proxy_next_upstream_tries number
默认:proxy_next_upstream_tries 0
上下文:http, server, location
版本:1.7.5+

限制尝试传递一个请求到下一个服务器的次数。零值禁用这个限制。

proxy_no_cache

语法:proxy_no_cache string
默认:—
上下文:http, server, location

定义在哪些情况下响应不会被缓存。如果string参数至少有一个不是空且不是“0”,则响应不会保存:

proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma    $http_authorization;

可以与proxy_cache_bypass指令一同使用。