nginx模块 ngx_http_proxy_module

2018-07-18 22:46:02

ngx_http_proxy_module 模块可以设置反向代理。

Syntax:	proxy_bind address [transparent] | off;
Default: —
Context: http, server, location

指定发送到代理服务器的本地ip地址。

Syntax:	proxy_buffer_size size;
Default: proxy_buffer_size 4k|8k;
Context: http, server, location

设置从代理服务器读取第一部分数据的缓冲区大小。这个部分一般存代理服务器的响应头。

Syntax:	proxy_buffering on | off;
Default: proxy_buffering on;
Context: http, server, location

是否开启缓冲,如果开启,那么nginx会先从代理服务器下载数据并存入 proxy_buffer_size 和 proxy_buffers 指定大小的缓冲区内,如果大小不够,部分将会存入临时文件。由 proxy_max_temp_file_size 和 proxy_temp_file_write_size 两个指定。

如果关闭,那么nginx会一边接受代理服务器数据,一边向客户端发送数据。从代理服务器一次最大可接收 proxy_buffer_size 指定的大小。

当然也可以在 代理服务器响应头里指定 X-Accel-Buffering: yes/no 来决定是否缓冲。这个功能能被 proxy_ignore_headers 指令禁用。

Syntax:	proxy_buffers number size;
Default: proxy_buffers 8 4k|8k;
Context: http, server, location

指定缓冲区的数量和大小用来存储代理服务器的响应数据。

Syntax:	proxy_busy_buffers_size size;
Default: proxy_busy_buffers_size 8k|16k;
Context: http, server, location

如果开启了缓冲,当响应内容还没有读取完成时,指定缓冲大小可以处于繁忙发送状态发送数据给客户端。在此期间,其余的缓冲区可以继续接收代理服务器响应。


Syntax:	proxy_cache zone | off;
Default: proxy_cache off;
Context: http, server, location

设置共享内存区域来缓存以便后续使用。

Syntax:	proxy_cache_background_update on | off;
Default: proxy_cache_background_update off;
Context: http, server, location

This directive appeared in version 1.11.10.

当需要将过期的数据返给客户端时,允许开启后台子请求更新过期的缓存。

Syntax:	proxy_cache_bypass string ...;
Default: —
Context: http, server, location

只要有一个条件非空或者非0,那么响应就不会从缓存取。

proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;
Syntax:	proxy_no_cache string ...;
Default: —
Context: http, server, location

只要有一个条件非空或者非0,那么就不会将响应内容缓存。

Syntax:	proxy_cache_convert_head on | off;
Default: proxy_cache_convert_head on;
Context: http, server, location

This directive appeared in version 1.9.7.

是否开启将请求方法 HEAD 转成 GET来缓存。如果不开启, cache_key 需要包含 $request_method。

Syntax:	proxy_cache_key string;
Default: proxy_cache_key $scheme$proxy_host$request_uri;
Context: http, server, location

定义缓存 key,默认的key有点类似下面。

proxy_cache_key $scheme$proxy_host$uri$is_args$args;
Syntax:	proxy_cache_lock on | off;
Default: proxy_cache_lock off;
Context: http, server, location

This directive appeared in version 1.1.12.

如果启用,那么同一时间同一个 key 只有一个请求向代理服务器请求以便生成新的缓存。其他的利用到相同缓存的被锁住不向代理服务器发送请求,它们会等待缓存更新完成以便可以直接从缓存里拿数据,或者等待锁释放,或者等到超时时间到。超时时间由 proxy_cache_lock_timeout 指定,一旦超时,那么其他请求会主动向代理服务器取数据。

Syntax:	proxy_cache_lock_age time;
Default: proxy_cache_lock_age 5s;
Context: http, server, location

This directive appeared in version 1.7.8.

如果最后那个到代理服务器的请求在指定时间内没有完成对新缓存的构建。会有额外请求到代理服务器。

Syntax:	proxy_cache_lock_timeout time;
Default: proxy_cache_lock_timeout 5s;
Context: http, server, location

This directive appeared in version 1.1.12.

proxy_cache_lock 的超时时间,如果超时,请求将发往代理服务器,但是响应不缓存。

Syntax:	proxy_cache_max_range_offset number;
Default: —
Context: http, server, location

This directive appeared in version 1.11.6.

为范围请求设置偏移字节数。如果 range 大于此  offset,那么直接向代理服务器发请求,响应内容不缓存。

Syntax:	proxy_cache_methods GET | HEAD | POST ...;
Default: proxy_cache_methods GET HEAD;
Context: http, server, location

This directive appeared in version 0.7.59.

设置需要缓存的请求方法。

Syntax:	proxy_cache_min_uses number;
Default: proxy_cache_min_uses 1;
Context: http, server, location

最少使用多少次才缓存。


Syntax:	proxy_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size 
                        [inactive=time] [max_size=size] [manager_files=number] 
                        [manager_sleep=time] [manager_threshold=time] [loader_files=number] 
                        [loader_sleep=time] [loader_threshold=time];
Context: http

设置缓存路径以及其他参数。

levels  定义了缓存路径的层级 1-3,每层又能接受1-2,比如

proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

文件名类似下面,是对 cache_key 的md5计算。

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

缓存文件会先存在临时文件,然后再移动重命名到缓存目录。临时文件目录基于 use_temp_path,如果设置为 on,或者忽略,那么会用 proxy_temp_path ,如果设置为 off,那么直接存入缓存目录。

另外,所有的活动的 key 会存入共享内存里,1M可以存将近 8000 个key。

inactive 指定的时间内没被访问将会被从缓存移除,默认为 10 分钟。

max_size  指定缓存最大大小,超过了将会移除最旧的数据。


迭代移除的方式将由 manager_files,manager_threshold,manager_sleep指定。

manager_files  一次迭代删除的文件数不会超过此,默认为100。
manager_threshold  限制一次迭代删除的时长,默认为 200ms。
manager_sleep  指定每次迭代间的休眠时间,默认为 50ms。


在启动1分钟后,"cache loader" 程序将启动,用来加载之前缓存在磁盘上的文件信息到内存 zone。一样是以迭代的方式加载。

loader_files 一次迭代加载的文件数不会超过此,默认为100。
loader_threshold 限制一次迭代的时长,默认为 200ms。
loader_sleep 指定每次迭代间的休眠时间,默认为 50ms。


Syntax:	proxy_cache_purge string ...;
Default: —
Context: http, server, location

This directive appeared in version 1.5.7.

指定的参数有一个非空或者非0,那么将对应 cache_key 的缓存删除,返回204(无内容)代表成功。

如果 cache_key 以 * 结尾,那么所有匹配的缓存都将会被移除。然而这些都还在磁盘上,直到有用户访问此内容或者inactivity到期才会真的被删除。

proxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

map $request_method $purge_method {
    PURGE   1;
    default 0;
}

server {
    ...
    location / {
        proxy_pass http://backend;
        proxy_cache cache_zone;
        proxy_cache_key $uri;
        proxy_cache_purge $purge_method;
    }
}

上面只有商业版才支持。


Syntax:	proxy_cache_revalidate on | off;
Default: proxy_cache_revalidate off;
Context: http, server, location

This directive appeared in version 1.5.7.

是否开启使得能通过请求头 If-Modified-Since 和 If-None-Match使缓存重新生效。

Syntax:	proxy_cache_use_stale error | timeout | invalid_header | updating 
                                | http_500 | http_502 | http_503 | http_504 | http_403 
                                | http_404 | http_429 | off ...;
Default: proxy_cache_use_stale off;
Context: http, server, location

决定什么时候会把过期的缓存返回给客户端。

error  不能选择代理服务器时。
timeout  代理服务器请求超时。
updating  正在更新缓存时。

Syntax:	proxy_cache_valid [code ...] time;
Default: —
Context: http, server, location

根据状态码设置缓存时间。

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

省略 time,默认状态码为 200,301,302。

proxy_cache_valid 5m;

any 代表所有状态码。

proxy_cache_valid any 5m;

当然也可以通过响应头来设置,优先级更高。

X-Accel-Expires 设置缓存的秒数。如果没提供,也可以用 Expires 或者 Cache-Control。

如果头包含 Set-Cookie,则不缓存。

响应头有 Vary: * 不缓存。

上述都可以利用 proxy_ignore_headers 指令来禁用。

Syntax:	proxy_connect_timeout time;
Default: proxy_connect_timeout 60s;
Context: http, server, location

建立连接时间,不能超过75秒。

Syntax:	proxy_cookie_domain off;
        proxy_cookie_domain domain replacement;
Default: proxy_cookie_domain off;
Context: http, server, location

This directive appeared in version 1.1.15.

替换 Set-Cookie 响应头里的domain,下面是一些例子。

假设Set-Cookie: domain=localhost。

#将localhost 替换为 example.org
proxy_cookie_domain localhost example.org;

会变成 Set-Cookie: domain=example.org。

proxy_cookie_domain www.$host $host;

proxy_cookie_domain ~\.(?P<sl_domain>[-0-9a-z]+\.[a-z]+)$ $sl_domain;

proxy_cookie_domain localhost example.org;
proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;

proxy_cookie_domain off;
proxy_cookie_domain localhost example.org;
proxy_cookie_domain www.example.org example.org;
Syntax:	proxy_cookie_path off;
        proxy_cookie_path path replacement;
Default: proxy_cookie_path off;
Context: http, server, location

替换cookie路径。

假设 Set-Cookie: path=/two/some/uri/。

proxy_cookie_path /two/ /;

会变成 Set-Cookie: path=/some/uri/。

支持变量。

proxy_cookie_path $uri /some$uri;

支持正则 ~大小写敏感,~*大小写不敏感。

proxy_cookie_path ~*^/user/([^/]+) /u/$1;

多个

proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;
Syntax:	proxy_force_ranges on | off;
Default: proxy_force_ranges off;
Context: http, server, location

This directive appeared in version 1.7.7.

开启范围请求支持对于缓存和非缓存的,忽略 Accept-Ranges 请求头。

Syntax:	proxy_hide_header field;
Default: —
Context: http, server, location

隐藏响应头,默认隐藏了 “Date”, “Server”, “X-Pad”, and “X-Accel-...”。 

Syntax:	proxy_ignore_client_abort on | off;
Default: proxy_ignore_client_abort off;
Context: http, server, location

是否关闭跟代理服务器的连接,当客户端不等待响应直接关闭了连接。

Syntax:	proxy_ignore_headers field ...;
Default: —
Context: 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), and “Vary” (1.7.7).

Syntax:	proxy_limit_rate rate;
Default: proxy_limit_rate 0;
Context: http, server, location

限制单个连接从代理服务器返回数据的速率,每秒多少字节。0代表不限制。

Syntax:	proxy_max_temp_file_size size;
Default: proxy_max_temp_file_size 1024m;
Context: http, server, location

最大的临时文件大小。

Syntax:	proxy_next_upstream error | timeout | invalid_header | http_500 | http_502 
                                | http_503 | http_504 | http_403 | http_404 | http_429 
                                | non_idempotent | off ...;
Default: proxy_next_upstream error timeout;
Context: http, server, location

满足什么情况时,请求会发往下一个服务器。前提条件必须是还没有发送任何响应到客户端。

Syntax:	proxy_next_upstream_timeout time;
Default: proxy_next_upstream_timeout 0;
Context: http, server, location

限制多少时间内将请求发往下一个服务器。0不限制。

Syntax:	proxy_next_upstream_tries number;
Default: proxy_next_upstream_tries 0;
Context: http, server, location

限制可能的尝试次数。


Syntax:	proxy_pass URL;
Default: —
Context: location, if in location, limit_except

设置代理服务器的地址。

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

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

同时也支持服务器群组。

如果地址不包含 uri那么,将原样地址发送。

#http://127.0.0.1/some/path/

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


Syntax:	proxy_pass_header field;
Default: —
Context: http, server, location

可以指定默认不传递给客户端的响应头(proxy_hide_header)。


Syntax:	proxy_pass_request_body on | off;
Default: proxy_pass_request_body on;
Context: http, server, location

指定是否传递请求体给代理服务器。

location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";

    proxy_pass ...
}


Syntax:	proxy_pass_request_headers on | off;
Default: proxy_pass_request_headers on;
Context: http, server, location

指定是否传递请求头

location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_headers off;
    proxy_pass_request_body off;

    proxy_pass ...
}


Syntax:	proxy_read_timeout time;
Default: proxy_read_timeout 60s;
Context: http, server, location

读取代理服务器响应的超时时间,超时则关闭连接。


Syntax:	proxy_redirect default;
        proxy_redirect off;
        proxy_redirect redirect replacement;
Default: proxy_redirect default;
Context: 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/

default 参数指定使用 location 指定的参数,比如下面两个等价。但是如果 proxy_pass 有变量,则不允许出现 default。

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_redirect http://localhost:8000/ http://$host:$server_port/;

proxy_redirect http://$proxy_host:8000/ /;

支持正则,~大小写敏感,~*大小写不敏感。

proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
proxy_redirect ~*/user/([^/]+)/(.+)$      http://$1.example.com/$2;

可以有多个。

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

相对于跳转添加hostname。

proxy_redirect / /;


Syntax:	proxy_request_buffering on | off;
Default: proxy_request_buffering on;
Context: http, server, location

This directive appeared in version 1.7.11.

如果开启,那么会把客户端的请求全部缓冲起来再发送给代理服务器。

不开启则会边接收客户端边发送给代理。这种情况下,如果想传递给下一个服务器就不可能了。

如果客户端使用 http/1.1 chunked 传输,那么肯定会先缓存,除非代理设置了 proxy_http_version 1.1。

Syntax:	proxy_http_version 1.0 | 1.1;
Default: proxy_http_version 1.0;
Context: http, server, location

This directive appeared in version 1.1.4.

如果需要跟后端 keepalive 或者NTLM 认证,那么最好使用 1.1。


Syntax:	proxy_send_timeout time;
Default: proxy_send_timeout 60s;
Context: http, server, location

发送超时时间,超时就关闭连接。

Syntax:	proxy_set_body value;
Default: —
Context: http, server, location

重新定义请求体,可以是文本,变量,它们的组合。

Syntax:	proxy_set_header field value;
Default: proxy_set_header Host $proxy_host;
         proxy_set_header Connection close;
Context: http, server, location

定义向代理服务器的请求头。

proxy_set_header Accept-Encoding "";

删除请求头。


Syntax:	proxy_ssl_certificate file;
Default: —
Context: http, server, location

This directive appeared in version 1.7.8.

指定PEM证书。

Syntax:	proxy_ssl_certificate_key file;
Default: —
Context: http, server, location

This directive appeared in version 1.7.8.

指定PEM私钥。

Syntax:	proxy_ssl_crl file;
Default: —
Context: http, server, location

This directive appeared in version 1.7.0.

指定PEM格式的crl。

Syntax:	proxy_ssl_name name;
Default: proxy_ssl_name $proxy_host;
Context: http, server, location

This directive appeared in version 1.7.0.

覆盖 server name来进行代理端的https认证过。

Syntax:	proxy_ssl_password_file file;
Default: —
Context: http, server, location

This directive appeared in version 1.7.8.

指定私钥密码,一行一个。

Syntax:	proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context: http, server, location

This directive appeared in version 1.5.6.

协议。

Syntax:	proxy_ssl_trusted_certificate file;
Default: —
Context: http, server, location

This directive appeared in version 1.7.0.

指定信任的PEM格式的CA。

Syntax:	proxy_ssl_verify on | off;
Default: proxy_ssl_verify off;
Context: http, server, location

This directive appeared in version 1.7.0.

是否开启对代理服务器的证书认证。

Syntax:	proxy_ssl_verify_depth number;
Default: proxy_ssl_verify_depth 1;
Context: http, server, location

This directive appeared in version 1.7.0.

设置认证深度。

Syntax:	proxy_store on | off | string;
Default: proxy_store off;
Context: http, server, location

存储文件到磁盘。on,会根据 alias或root来存文件。当然也可以手动指定路径。

proxy_store /data/www$original_uri;
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/;
}

#也可以是

location /images/ {
    root               /data/www;
    error_page         404 = @fetch;
}

location @fetch {
    internal;

    proxy_pass         http://backend;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    root               /data/www;
}
Syntax:	proxy_store_access users:permissions ...;
Default: proxy_store_access user:rw;
Context: http, server, location

设置文件权限。

proxy_store_access user:rw group:rw all:r;

#或者或略user
proxy_store_access group:rw all:r;


Syntax:	proxy_temp_file_write_size size;
Default: proxy_temp_file_write_size 8k|16k;
Context: http, server, location

限制一次能写入临时文件的大小。默认为2个buffer大小根据 proxy_buffer_size 和 proxy_buffers 指令指定。

Syntax:	proxy_temp_path path [level1 [level2 [level3]]];
Default: proxy_temp_path proxy_temp;
Context: http, server, location

定义存储临时文件的路径。

proxy_temp_path /spool/nginx/proxy_temp 1 2;

那么文件看起来像下面。

/spool/nginx/proxy_temp/7/45/00000123457


内置变量

$proxy_host  由 proxy_pass 指定的名称和端口。

$proxy_port  由 proxy_pass 指定的端口。

$proxy_add_x_forwarded_for  如果客户端指定了 X-Forwarded-For ,那么该变量就是该值加上 $remote_addr。如果没指定,直接为 $remote_addr。


 备注

1.测试环境centos7 64位,nginx版本为 1.14.0。
2.读者也可以参考官方文档 nginx documentation
3..原文地址http://www.freecls.com/a/2712/c7


©著作权归作者所有
收藏
推荐阅读
简介
天降大任于斯人也,必先苦其心志。