分类： nginx

proxy_bind

语法：proxy_bind address [transparent] | off
默认：—
上下文：http, server, location
版本：0.8.22+

外部连接到被代理服务器的指定本地IP地址。参数值可以包含变量（1.3.12+），特殊值off（1.3.12+）取消从上级配置中继承的proxy_bind的影响，使系统可以自动分配本地IP地址。
transparent参数（1.11.0+）允许从一个非本地IP地址发起外部连接到代理服务器，例如使用真实的客户端IP：
proxy_bind $remote_addr transparent;
为了使该参数可用，需要将nginx的工作进程以超级用户权限执行并且配置核心路由表阻断从被代理服务器的网络流量。

proxy_buffer_size

语法：proxy_buffer_size size
默认：proxy_buffer_size 4k|8k
上下文：http, server, location

设置用于读取从被代理服务器收到的响应的第一部分的缓冲区大小。该部分通常包含一个小的响应头。默认情况下，缓冲区大小等于一页内存。这个值是4k或8k取决于平台。但是可以变得更小。

proxy_buffering

语法：proxy_buffering on | off
默认：proxy_buffering on
上下文：http, server, location

启用或禁用从被代理服务器返回的响应的缓冲区。
当缓冲区启用，nginx收到请求后尽快的将其保存到proxy_buffer_size和proxy_buffers指令设置的缓冲区中。如果整个响应不能放到内存中，有一部分会存到磁盘上的临时文件中。写入到由proxy_max_temp_file_size和proxy_temp_file_write_size指令控制的临时文件中。
当缓冲区禁用时，响应会在收到后同步的传给客户端。nginx不会尝试从被代理服务器读取完整的响应。nginx一次可以接收的数据最大值由proxy_buffer_size指令设置。
缓冲区也可以分别通过响应头中“X-Accel-Buffering”字段的“yes”和“no”启用及禁用。这个功能可以使用proxy_ignore_headers指令禁用。

proxy_buffers

语法：proxy_buffers number size
默认：proxy_buffers 8 4k|8k
上下文：http, server, location

设置用于读取响应的缓冲区数量和大小。默认，缓冲区大小等于一页内存。该值为4k或8k取决于平台。

proxy_busy_buffers_size

语法：proxy_busy_buffers_size size
默认：proxy_busy_buffers_size 8k|16k
上下文：http, server, location

当读取响应缓冲区开启时，限制缓冲区总大小会在没有完全读取响应时，忙着发送给客户端响应。同时剩余的缓冲区可以用来读取响应，如果需要，缓冲区的部分响应会放入临时文件。默认情况下，大小受proxy_buffer_size和proxy_buffers指令设置的两个缓冲区大小限制。

proxy_cache

语法：proxy_cache zone | off
默认：proxy_cache off
上下文：http, server, location

定义缓存的共享内存区域。相同的区域可以用在不同的位置。参数可以包含变量（1.7.9+）。off参数禁用了从上级配置中继承的缓存。

proxy_cache_bypass

语法：proxy_cache_bypass string …
默认：—
上下文：http, server, location

定义在哪些情况下，响应不会从缓存中取。如果有至少一个字符串参数非空或不等于“0”，则响应不会从缓存中取：

proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;

可以同proxy_no_cache指令一同使用。

proxy_cache_convert_head

语法：proxy_cache_convert_head on | off
默认：proxy_cache_convert_head on
上下文：http, server, location
版本：1.9.7+

启用或禁用为缓存将“HEAD”方法转换为“GET”方法。当转换被禁用时，cache_key应该配置为包含$request_method。

proxy_cache_key

语法：proxy_cache_key string
默认：proxy_cache_key $scheme$proxy_host$request_uri
上下文：http, server, location

为缓存定义一个关键字，例如：
proxy_cache_key "$host$request_uri $cookie_user";
默认情况下，指令的值接近字符串：
proxy_cache_key $scheme$proxy_host$uri$is_args$args;

proxy_cache_lock

语法：proxy_cache_lock on | off
默认：proxy_cache_lock off
上下文：http, server, location
版本：1.1.12+

当启用时，同一时间只有一个请求允许在新的缓存元素中。其他使用相同缓存元素的请求要么等待缓存中出现的响应，要么等待该元素被释放，时间由proxy_cache_lock_timeout指令设置。

proxy_cache_lock_age

语法：proxy_cache_lock_age time
默认：proxy_cache_lock_age 5s
上下文：http, server, location
版本：1.7.8+

如果最后一个发送给被代理服务器的请求占用一个新的缓存元素，并没有在指定时间内完成，其他的请求可以发送到被代理服务器。

proxy_cache_lock_timeout

语法：proxy_cache_lock_timeout time
默认：proxy_cache_lock_timeout 5s
上下文：http, server, location
版本：1.1.12+

为proxy_cache_lock设置超时时间。当时间过期，请求会发送给被代理服务器，但是，响应不会被缓存。
在1.7.8版本以前，缓存会被缓存。

proxy_cache_methods

语法：proxy_cache_methods GET | HEAD | POST …
默认：proxy_cache_methods GET HEAD
上下文：http, server, location
版本：0.7.59+

如果客户端请求方法在这个指令的列表中，响应将被缓存。“GET”和“HEAD”方法总会添加到列表中，不过建议显式的声明。

proxy_cache_min_uses

语法：proxy_cache_min_uses number
默认：proxy_cache_min_uses 1
上下文：http, server, location

设置请求数量，在这之后的响应会被缓存。

proxy_cache_path

语法：proxy_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time]
默认：—
上下文：http

设置缓存的路径以及其他参数。缓存数据存储在文件中。缓存中文件名是cache_key做md5的结果。levels参数定义了缓存的层级。例如，下面的配置
proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
缓存的文件名类似于
/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c
缓存的响应首先写到临时文件中，然后文件重命名。从0.8.9版本开始，临时文件和缓存可以放在不同的文件系统上。但是，需要知道的是，这种情况下，一个文件要在两个文件系统中复制，而不是代价更低的重命名操作。建议将临时文件和缓存放到同一个文件系统上。缓存文件的目录通过use_temp_path参数（1.7.10+）设置。如果参数忽略或设置为on，proxy_temp_path指令给出的位置将被使用。如果值为off，临时文件将直接写到缓存目录中。
所有活动的关键字和关于数据的信息都保存在共享内存区域，它们的名称和大小有keys_zone参数配置。1M的区域大约可以存储8000个关键字。
在inactive参数定义的时间内，缓存数据没有被访问将从缓存中移除，而不管它们的新鲜度。默认情况下，inactive设置为10分钟。
特殊的“cache manager”进程监控max_size参数设置的最大缓存大小。当这个值超了，就会将最近最少使用的数据移除。
启动后一分钟，“cache loader”进程激活。它会加载之前存储在文件系统中的缓存数据到缓存区域中。加载是通过迭代方式进行的，每次迭代不超过loader_files个项目载入（默认是100个）。另外，每个迭代的持续时间有loader_threshold参数限制（默认200毫秒）。在迭代之间，会有由loader_sleep参数（默认50毫秒）配置的暂停。
下面的参数为商业版可用（商业版本不再翻译）：
purger=on|off
Instructs whether cache entries that match a wildcard key will be removed from the disk by the cache purger (1.7.12). Setting the parameter to on (default is off) will activate the “cache purger” process that permanently iterates through all cache entries and deletes the entries that match the wildcard key.

purger_files=number
Sets the number of items that will be scanned during one iteration (1.7.12). By default, purger_files is set to 10.

purger_threshold=number
Sets the duration of one iteration (1.7.12). By default, purger_threshold is set to 50 milliseconds.

purger_sleep=number
Sets a pause between iterations (1.7.12). By default, purger_sleep is set to 50 milliseconds.

proxy_cache_purge

语法：proxy_cache_purge string …
默认：—
上下文：http, server, location
版本：1.5.7+

商业版本中可用。
Defines conditions under which the request will be considered a cache purge request. If at least one value of the string parameters is not empty and is not equal to “0” then the cache entry with a corresponding cache key is removed. The result of successful operation is indicated by returning the 204 (No Content) response.

If the cache key of a purge request ends with an asterisk (“*”), all cache entries matching the wildcard key will be removed from the cache. However, these entries will remain on the disk until they are deleted for either inactivity, or processed by the cache purger (1.7.12), or a client attempts to access them.

示例配置

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;
    }
}

proxy_cache_revalidate

语法：proxy_cache_revalidate on | off
默认：proxy_cache_revalidate off
上下文：http, server, location
版本：1.5.7+

开启过期缓存重验证功能，使用请求头中“If-Modified-Since”和“If-None-Match”字段。

proxy_cache_use_stale

语法：proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | off …
默认：proxy_cache_use_stale off
上下文：http, server, location

决定在与被代理服务器通信期间出现错误时，哪些情况下可以使用老的缓存响应。指令参数匹配proxy_next_upstream指令的参数。
error参数在请求无法选择时，使用老的缓存响应。
updating参数在当前请求更新时，仍使用老缓存响应。这允许在更新缓存数据期间最少的访问服务器。
为了在占用新的缓存元素时，减少访问被代理服务器的次数，可以使用proxy_cache_lock指令。

proxy_cache_valid

语法：proxy_cache_valid [code …] time
默认：—
上下文：http, server, location

为不同的响应码设置缓存时间，例如，下面的指令

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

为200和302响应码设置10分钟的缓存，为404的响应码设置1分钟的缓存
如果只定义了缓存时间
proxy_cache_valid 5m;
只有200、301和302响应会被缓存。
any参数可以指定为任何返回缓存：

proxy_cache_valid 200 302 10m;
proxy_cache_valid 301      1h;
proxy_cache_valid any      1m;

缓存的参数可以直接在响应头中设置。这个比用指令设置优先级更高。

• “X-Accel-Expires”头域设置了响应的缓存时间，以秒为单位。0值禁用响应的缓存。如果值以@开头，表示从纪元（1970-01-01）开始的秒数，响应将会缓存到这个时间。
• 如果投中不包含“X-Accel-Expires”字段，缓存参数可能存在“Expires”或“Cache-Control”中
• 如果头部包含“Set-Cookie”字段，这个响应不会被缓存。
• 如果头部包含带有“*”值的“Vary”字段，这个响应不会被缓存（1.7.7+）。如果头部的“Vary”值是其他的值，这个响应会考虑请求头域的相应字段进行缓存。（1.7.7+）

可以通过proxy_ignore_headers指令禁用处理一个或多个响应头域的功能。

proxy_connect_timeout

语法：proxy_connect_timeout time
默认：proxy_connect_timeout 60s
上下文：http, server, location

定义一个与被代理服务器建立连接的超时时间。这个超时时间通常不超过75秒。

proxy_cookie_domain

语法：proxy_cookie_domain off
proxy_cookie_domain domain replacement
默认：proxy_cookie_domain off
上下文：http, server, location
版本：1.1.15+

设置一个被代理服务器返回的头域“Set-Cookie”中domain属性应更改的文本。假设被代理服务器返回了“Set-Cookie”头域含有“domain=localhost”属性。指令
proxy_cookie_domain localhost example.org;
将会重写这个属性为“domain=example.org”
以点开头的domain、replacement、domain属性会被忽略。匹配是大小写不敏感的。
domain和replacement可以包含变量：
proxy_cookie_domain www.$host $host;
指令可以使用正则表达式，这种情况下，domain需要以“~”开头。正则表达式可以包含和位置捕获，replacement可以引用它们：
proxy_cookie_domain ~\.(?P[-0-9a-z]+\.[a-z]+)$ $sl_domain;
可以有多个proxy_cookie_domain指令：

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

off参数取消了所有当前级别proxy_cookie_domain指令的影响：

proxy_cookie_domain off;
proxy_cookie_domain localhost example.org;
proxy_cookie_domain www.example.org example.org;

proxy_cookie_path

语法：proxy_cookie_path off
proxy_cookie_path path replacement
默认：proxy_cookie_path off
上下文：http, server, location
版本：1.1.15+

设置一个被代理服务器返回的头域“Set-Cookie”中path属性应更改的文本。假设被代理服务器返回了“Set-Cookie”头域含有“path=/two/some/uri/”属性。指令
proxy_cookie_path /two/ /;
将这个属性重写为“path=/some/uri/”。
path和replacement可以包含变量：
proxy_cookie_path $uri /some$uri
指令可以使用正则表达式，这种情况下，path需要以“~”开头大小写敏感，或“~*”开头大小写不敏感。正则表达式可以包含和位置捕获，replacement可以引用它们：
proxy_cookie_path ~*^/user/([^/]+) /u/$1;
可以有多个proxy_cookie_path指令：

proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;

off参数取消了所有当前级别proxy_cookie_path指令的影响：

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

该模块默认不会构建，需要通过–with-http_perl_module参数配置。
该模块需要Perl版本5.6.1或更高。C编译器需要匹配构建Perl。

已知问题
该模块是实验性的。
重新编译Perl时，需要使用-Dusemultiplicity=yes或-Dusethreads=yes参数。同时，为了是Perl运行时占用更少的内存，应该使用-Dusemymalloc=no参数。为检测当前构建的Perl的参数，运行：

$ perl -V:usemultiplicity -V:usemymalloc
usemultiplicity='define';
usemymalloc='n';

注意，通过-Dusemultiplicity=yes或-Dusethreads=yes参数重新构建Perl后，所有二进制Perl模块必须一同重新构建。
在每次重新配置后，主进程和工作进程的大小可能会增长。如果主进程增长到不可接受的大小，live upgrade程序可以不改变可执行文件。
当Perl模块执行长时间的任务，例如解析一个域名、连接其他服务器或查询数据库，分配给当前工作进程的其他请求不会被处理。因此建议只有确定耗时短的操作被执行，例如访问本地文件系统。

示例配置

http {

    perl_modules perl/lib;
    perl_require hello.pm;

    perl_set $msie6 '

        sub {
            my $r = shift;
            my $ua = $r->header_in("User-Agent");

            return "" if $ua =~ /Opera/;
            return "1" if $ua =~ / MSIE [6-9]\.\d+/;
            return "";
        }

    ';

    server {
        location / {
            perl hello::handler;
        }
    }

perl/lib/hello.pm模块：

package hello;

use nginx;

sub handler {
    my $r = shift;

    $r->send_http_header("text/html");
    return OK if $r->header_only;

    $r->print("hello!\n
");

    if (-f $r->filename or -d _) {
        $r->print($r->uri, " exists!\n");
    }

    return OK;
}

1;
__END__

perl

语法：perl module::function|’sub { … }’
默认：—
上下文：location, limit_except

设置给定location的Perl处理器。

perl_modules

语法：perl_modules path
默认：—
上下文：http

为Perl模块添加额外的路径。

perl_require

语法：perl_require module
默认：—
上下文：http

定义模块名，在每次重配置时加载。可以有多个perl_require指令。

perl_set

语法：perl_set $variable module::function|’sub { … }’
默认：—
上下文：http

为指定的变量安装Perl处理器。

从SSI调用Perl
SSI命令调用Perl有下面的格式：

$r请求对象方法

$r->args
返回请求参数

$r->filename
返回请求URI对应的文件名

$r->has_request_body(handler)
如果请求体内容为空，返回0。如果有请求体，指定的handler将设置请求，并返回1。在读取请求体后，nginx将调用指定的handler。注意handler函数应通过引用传递，例如：

package hello;

use nginx;

sub handler {
    my $r = shift;

    if ($r->request_method ne "POST") {
        return DECLINED;
    }

    if ($r->has_request_body(\&post)) {
        return OK;
    }

    return HTTP_BAD_REQUEST;
}

sub post {
    my $r = shift;

    $r->send_http_header;

    $r->print("request_body: \"", $r->request_body, "\"
");
    $r->print("request_body_file: \"", $r->request_body_file, "\"
\n");

    return OK;
}

1;

__END__

$r->allow_ranges
发送响应时启用byte range功能

$r->discard_request_body
让nginx丢弃请求体

$r->header_in(field)
返回请求头中指定的值

$r->header_only
决定发送客户端完整响应还是只发送头

$r->header_out(field, value)
设置指定的响应头域

$r->internal_redirect(uri)
向指定的uri做内部重定向。重定向发送在Perl处理器执行完毕。
重定向到名称location目前不支持。

$r->log_error(errno, message)
写指定的信息到error_log。如果errno非零，错误码和描述信息将被追加到信息中。

$r->print(text, …)
发送数据到客户端。

$r->request_body
如果请求体没有写入临时文件，则返回请求体。确保客户端请求体在内存中，大小需要被client_max_body_size指令限制，并且需要通过client_body_buffer_size指令设置足够大的缓冲区。

$r->request_body_file
返回客户端请求体文件的名称。在处理后，文件会被移除。需要使用client_body_in_file_only指令确保请求体总会写到文件中。

$r->request_method
返回客户端请求的HTTP方法

$r->remote_addr
返回客户端IP地址

$r->flush
立即发送数据到客户端

$r->sendfile(name[, offset[, length]])
发送指定的文件内容到客户端。可选参数定义了初始的偏移和要传输数据的长度。实际的传输发生在Perl处理器完成时。

$r->send_http_header([type])
发送响应头到客户端。可选参数type这只了响应头域“Content-Type”。如果值是一个空字符串，“Content-Type”不会被设置。

$r->status(code)
设置响应码

$r->sleep(milliseconds, handler)
设置滴定的处理器，并暂停处理请求指定的时间。与此同时，nginx处理其他的请求，在指定时间过后，nginx将会调用安装的处理器。注意处理器函数需要通过引用传递。为在处理器之间传递数据，需要使用$r->variable()，例如：

package hello;

use nginx;

sub handler {
    my $r = shift;

    $r->discard_request_body;
    $r->variable("var", "OK");
    $r->sleep(1000, \&next);

    return OK;
}

sub next {
    my $r = shift;

    $r->send_http_header;
    $r->print($r->variable("var"));

    return OK;
}

1;

__END__

$r->unescape(text)
解码一个“%XX”格式的文本

$r->uri
返回请求URI

$r->variable(name[, value])
返回或设置指定变量的值。变量对每一个请求都是本地的。