nginx中文文档-ngx_http_uwsgi_module(B-H)

本文档包含以下指令:uwsgi_bind、uwsgi_buffer_size、uwsgi_buffering、uwsgi_buffers、uwsgi_busy_buffers_size、uwsgi_cache、uwsgi_cache_bypass、uwsgi_cache_key、uwsgi_cache_lock、uwsgi_cache_lock_age、uwsgi_cache_lock_timeout、uwsgi_cache_methods、uwsgi_cache_min_uses、uwsgi_cache_path、uwsgi_cache_purge、uwsgi_cache_revalidate、uwsgi_cache_use_stale、uwsgi_cache_valid、uwsgi_connect_timeout、uwsgi_force_ranges、uwsgi_hide_header

ngx_http_uwsgi_module模块允许将请求传递给uwsgi服务器。
示例配置

location / {
    include    uwsgi_params;
    uwsgi_pass localhost:9000;
}

uwsgi_bind

语法:uwsgi_bind address [transparent] | off
默认:—
上下文:http, server, location

从指定本地IP地址向uwsgi建立外部连接。参数值可以包含变量(1.3.12+)。特殊值off(1.3.12+)取消继承自上级配置中uwsgi_bind指令的影响,允许系统自动指派本地IP地址。
transparent参数(1.11.0+)允许从非本地IP地址向uwsgi服务器建立外部连接,例如,从一个客户端的真实IP:
uwsgi_bind $remote_addr transparent;
为了使这个参数生效,需要以超级用户运行nginx工作进程,并配置内核路由表以接货来自uwsgi服务器的网络流量。

uwsgi_buffer_size

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

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

uwsgi_buffering

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

启用或禁用从uwsgi服务器收到响应的缓冲区。
当缓冲区启用时,nginx从uwsgi服务器收到响应后,尽快的将其保存到uwsgi_buffer_size和uwsgi_buffers指令设置的缓冲区中。如果整个响应不能放入内存,一部分可以保存到磁盘上的临时文件中。写入到临时文件由uwsgi_max_temp_file_size和uwsgi_temp_file_write_size指令控制。
当缓冲区禁用时,响应会在收到后同步的传递给客户端。nginx不会尝试从uwsgi服务器读取全部响应。每次nginx可以从服务器获取的数据大小由uwsgi_buffer_size指令设置。
缓冲区也可以通过响应头域中的“X-Accel-Buffering”的“yes”值或“no”值启用或禁用。这个功能可以使用uwsgi_ignore_headers指令禁用。

uwsgi_buffers

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

设置用于从uwsgi服务器读取响应的缓冲区数量和大小。默认情况下,缓冲区大小等于一页内存。这个值是4k或8k,取决于平台。

uwsgi_busy_buffers_size

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

当从uwsgi服务器读取响应的缓存开启,限制当响应没有完全读取时,可以发送给客户端的缓冲区总大小。与此同时,缓冲区的其余部分可以用于读取响应,如果需要,缓冲部分响应到临时文件。默认情况下,大小由uwsgi_buffer_size和uwsgi_buffers指令设置的两个缓冲区大小限制。

uwsgi_cache

语法:uwsgi_cache zone | off
默认:uwsgi_cache off
上下文:http, server, location

定义一个用于缓存的共享内存区域。相同的区域可以用在多个位置。参数值可以包含变量(1.7.9+)。参数off禁用继承自上级配置的缓存。

uwsgi_cache_bypass

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

定义哪些情况下响应不会从缓存中取。如果string参数至少有一个是非“0”的非空字符串,响应不会从缓存中取:

uwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
uwsgi_cache_bypass $http_pragma    $http_authorization;

可以与uwsgi_no_cache指令一同使用。

uwsgi_cache_key

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

定义一个缓存的关键字,例如:
uwsgi_cache_key localhost:9000$request_uri;

uwsgi_cache_lock

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

当启用时,同一时间只有一个请求可以占用一个新的缓存元素。其他的使用相同缓存元素的请求会等待响应出现在缓存中或等到由uwsgi_cache_lock_timeout指令定义的时间达到后释放这个元素的锁定。

uwsgi_cache_lock_age

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

如果最后一个传递给uwsgi服务器的请求占用一个新的缓存元素,并在指定的时间内没有完成,一个或更多的请求可以传递给uwsgi服务器。

uwsgi_cache_lock_timeout

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

为uwsgi_cache_lock设置超时时间。当这个时间过期,请求可以发送到uwsgi服务器,但是响应不会被缓存。
在1.7.8版本之前,响应会被缓存。

uwsgi_cache_methods

语法:uwsgi_cache_methods GET | HEAD | POST …
默认:uwsgi_cache_methods GET HEAD
上下文:http, server, location

如果客户端请求方式列于这个指令中,响应会被缓存。“GET”和“HEAD”方法总会被添加到列表中,推荐显式的定义他们。参见uwsgi_no_cache指令。

uwsgi_cache_min_uses

语法:uwsgi_cache_min_uses number
默认:uwsgi_cache_min_uses 1
上下文:http, server, location

设置请求的数量,超过这个数量后响应会被缓存。

uwsgi_cache_path

语法:uwsgi_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

设置缓存的路径和其他参数。缓存数据保存在文件中。缓存中的文件名是缓存关键字MD5的结果。levels参数定义了缓存的层级。例如下面的配置
uwsgi_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,将会使用uwsgi_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.

uwsgi_cache_purge

语法:uwsgi_cache_purge string
默认:—
上下文:http, server, location
版本:1.5.7+

定义在哪些条件下请求会被视为清除缓存请求。如果string参数只要有一个为非“0”的非空值,则相应的缓存关键字会被删除。成功的操作会返回204响应码。
如果清除缓存的关键字请求以星号(“*”)结尾,所有的缓存匹配关键字的都会移除。但是会在磁盘中保留直到被inactivity删除或cache purger(1.7.12+)处理或客户端尝试访问它们。
示例配置:

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

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

server {
    ...
    location / {
        uwsgi_pass        backend;
        uwsgi_cache       cache_zone;
        uwsgi_cache_key   $uri;
        uwsgi_cache_purge $purge_method;
    }
}

该功能在商业版本中可用。

uwsgi_cache_revalidate

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

启用对过期的缓存通过“If-Modified-Since”和“If-None-Match”条件请求头域进行重验证。

uwsgi_cache_use_stale

语法:uwsgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | off …
默认:uwsgi_cache_use_stale off
上下文:http, server, location

定义在与uwsgi服务器通信发生错误时,哪些情况下陈旧的缓存响应会被使用。这个指令的参数与uwsgi_next_upstream指令匹配。
error参数在不能选择一个uwsgi服务器处理请求时也允许使用陈旧的缓存响应。
updating参数在当前缓存更新时允许使用陈旧的缓存响应。这让当更新缓存数据时,减少访问uwsgi服务器。
为了在占用一个新缓存元素时减少访问uwsgi服务器的次数,可以是用uwsgi_cache_lock指令。

uwsgi_cache_valid

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

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

uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 404      1m;

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

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

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

  • “X-Accel-Expires”头域设置了缓存响应的秒数。零值禁用缓存响应。如果值以“@”前缀开头,则设置了一个从纪元开始的秒数的绝对时间,一直会缓存到这个时间。
  • 如果头中不包含“X-Accel-Expires”字段,缓存参数可能设置在“Expires”或“Cache-Control”字段中。
  • 如果头中包含“Set-Cookie”字段,响应不会被缓存。
  • 如果头中包含“Vary”字段值是 “*”,响应不会被缓存(1.7.7+)。如果头中包含“Vary”字段,值是其他值,是否缓存响应会考虑相应的请求头域(1.7.7+)。

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

uwsgi_connect_timeout

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

为与uwsgi服务器建立连接定义一个超时时间。注意这个超时时间通常不超过75秒。

uwsgi_force_ranges

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

为缓存和不缓存的响应启用byte-range支持,不管响应的“Accept-Ranges”头域。

uwsgi_hide_header

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

默认情况下,nginx不会传递来自于uwsgi服务器的“Status”和“X-Accel-…”响应头域到客户端。uwsgi_hide_header指令设置了其他不会传递的字段。如果相反,需要允许传递字段,可以使用uwsgi_pass_header指令。

nginx中文文档-ngx_http_userid_module

此页面版本:2016-06-08
ngx_http_userid_module模块为客户端身份证明设置cookie。接收设置cookie可以被记录在内嵌变量$uid_got和$uid_set中。该模块与Apache的mod_uid一致。

示例配置

userid         on;
userid_name    uid;
userid_domain  example.com;
userid_path    /;
userid_expires 365d;
userid_p3p     'policyref="/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"';

userid

语法:userid on | v1 | log | off
默认:userid off
上下文:http, server, location

启用或禁用设置cookie并记录收到cookie:
on
启用设置版本2的cookie,并记录收到的cookie。

v1
启用设置版本1的cookie,并记录收到的cookie。

log
禁用设置cookie,但启用记录收到的cookie。

off
禁用设置cookie,和记录收到的cookie。

userid_domain

语法:userid_domain name | none
默认:userid_domain none
上下文:http, server, location

定义cookie设置的域名,none参数禁用设置cookie的域名。

userid_expires

语法:userid_expires time | max | off
默认:userid_expires off
上下文:http, server, location

设置一个时间,在此期间浏览器应该保存cookie。参数max将使cookie的过期时间设置为“31 Dec 2037 23:55:55 GMT”。参数off将设置cookie的有效期到浏览器会话结束。

userid_mark

语法:userid_mark letter | digit | = | off
默认:userid_mark off
上下文:http, server, location

如果参数不是off,启用cookie标识机制,设置用于标识的字符。机制用于添加或改变userid_p3p和/或保留客户端身份信息的cookie的截止时间。标识可以是英文字母表(大小写敏感)中任何一个字母,数字或“=”字符。
如果设置了标识,它会与客户端cookie中base64编码身份标识的第一个填充标识作比较。如果它们不匹配,cookie会以指定的标记、截止时间以及“P3P”头重新发送。

userid_name

语法:userid_name name
默认:userid_name uid
上下文:http, server, location

设置cookie名称。

userid_p3p

语法:userid_p3p string | none
默认:userid_p3p none
上下文:http, server, location

设置将于cookie一同发送的“P3P”头的值。如果该指令设置为特殊值none,“P3P”头将不会在响应中发送。

userid_path

语法:userid_path path
默认:userid_path /
上下文:http, server, location

定义cookie设置的路径。

userid_service

语法:userid_service number
默认:userid_service IP address of the server
上下文:http, server, location

如果标识符被多个服务器(服务)发行,每个服务应该分配自己的数字以确保客户端标识符是唯一的。对版本1的cookie,默认值是0。版本2的cookie,默认值是由服务器IP地址的最后四个八位位组构成。

内嵌变量
ngx_http_userid_module模块支持以下内嵌变量:

$uid_got
cookie名和收到的客户端标识。


$uid_reset
如果变量设置为不是“0”的非空字符串,客户端标识符会充值。特殊值“log”将重置的标识符信息输出到error_log中。


$uid_set
cookie名和发送客户端的标识符。

nginx中文文档-ngx_http_upstream_conf_module

ngx_http_upstream_conf_module模块允许通过一个简单的HTTP接口不需要重启nginx配置上游服务器组。http或stream服务器组必须位于共享内存。

该模块是商业版本的一部分。
示例配置

upstream backend {
    zone upstream_backend 64k;

    ...
}

server {
    location /upstream_conf {
        upstream_conf;
        allow 127.0.0.1;
        deny all;
    }
}

upstream_conf

语法:upstream_conf
默认:—
上下文:location

在指定location中开启upstream的配置HTTP接口。访问这个location应该是受限的。
配置命令可以用于:

  • 查看组配置
  • 查看、修改、移除一个服务器
  • 添加一个服务器

由于组中的地址不需要唯一,指定组中的服务器通过它们的id引用。当添加一个新服务器或查看组配置时,id会自动分配和显示。
配置命令的参数由请求参数构成,例如
http://127.0.0.1/upstream_conf?upstream=backend
支持下面的参数:
stream=
选择一个stream upstream服务器组。没有这个参数,会选择一个http upstream服务器组。

upstream=name
选择工作的组,该参数是强制的。

id=number
选择一个查看、修改或移除的服务器。

remove=
从组中移除一个服务器。

add=
添加服务器到组。

backup=
需要添加的备份服务器。
在1.7.2版本之前,backup=需要查看、修改或移除存在的备份服务器。

server=address
同http或stream上游服务器的“address”参数
当添加一个服务器,可以指定为域名。这种情况下,改变响应域名的IP地址会被监控并自动的应用到upstream配置,不需要重启nginx(1.7.2+)。这需要“resolver”指令在http或stream块中。参见http或stream上游服务器的“resolver”参数。

service=name
同http或stream上游服务器的“service”参数(1.9.13+)

weight=number
同http或stream上游服务器的“weight”参数

max_conns=number
同http或stream上游服务器的“max_conns”参数

max_fails=number
同http或stream上游服务器的“max_fails”参数

fail_timeout=time
同http或stream上游服务器的“fail_timeout”参数

slow_start=time
同http或stream上游服务器的“slow_start”参数

down=
同http或stream上游服务器的“down”参数

drain=
让http上游服务器进入“draining”模式(1.7.5+)。这种模式下,只有上行服务器会被代理。

up=
与http或stream上游服务器的“down”参数相反

route=string
同http或stream上游服务器的“route”参数
前三个参数选择一个对象。可以是整个http或stream上游服务器组,也可以是一个指定的服务器。没有其他参数,选择的组合服务器配置会展示。
例如,查看完整的组配置,发送:
http://127.0.0.1/upstream_conf?upstream=backend

查看指定服务器的配置,同样指定id:
http://127.0.0.1/upstream_conf?upstream=backend&id=42

添加一个新服务器,通过“server=”参数指定地址。没有其他参数指定,服务器将会设置其他参数为默认值(见http或stream的“server”指令)
例如,添加一个主服务器,发送:
http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080

添加一个备份服务器,发送:
http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080

添加一个新的主服务器,设置参数无默认值并标记为down,发送:
http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down=

移除一个指定id的服务器:
http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42

标记一个存在的服务为“down”,发送:
http://127.0.0.1/upstream_conf?upstream=backend&id=42&down=

改变一个存在的服务器的地址,发送:
http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123

改变其他已存在的服务器参数,发送:
http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4

上面的例子是http上游服务器组的。简单的stream上游服务器组的例子需要“stream=”参数。

nginx中文文档-ngx_http_upstream_module

此页面版本:2016-06-08
ngx_http_upstream_module模块用于定义服务器组,可以在proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass以及 memcached_pass指令中引用。

示例配置

upstream backend {
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server unix:/tmp/backend3;

    server backup1.example.com:8080   backup;
    server backup2.example.com:8080   backup;
}

server {
    location / {
        proxy_pass http://backend;
    }
}

动态定义服务器组是商业版的一部分。

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com      weight=5;
    server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
    server 192.0.2.1                 max_fails=3;
    server backend3.example.com      resolve;
    server backend4.example.com      service=http resolve;

    server backup1.example.com:8080  backup;
    server backup2.example.com:8080  backup;
}

server {
    location / {
        proxy_pass http://dynamic;
        health_check;
    }
}

upstream

语法:upstream name { … }
默认:—
上下文:http

定义一个服务器组。服务器可以监听不同的端口。服务器可以混合的监听TCP和UNIX-domain socket。
示例:

upstream backend {
    server backend1.example.com weight=5;
    server 127.0.0.1:8080       max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend3;

    server backup1.example.com  backup;
}

默认情况下,请求在服务器之间的分配使用带权重的轮询负载均衡方式。上面的例子中,每7个请求会按如下方式分配:5个请求分配到backend1.example.com,第二个和第三个服务器分别分配1个请求。如果在与一个服务器通信时发生了错误,请求将会传递给下一个服务器,直到所有的服务器都尝试了。如果从任何一个服务器都得不到成功的响应,客户端将会收到与最后一个服务器通信的结果。

server

语法:server address [parameters]
默认:—
上下文:upstream

定义服务器的地址和其他参数。地址可以指定为一个域名或IP地址与可选的端口号,或UNIX-domain socket路径指定在“unix:”前缀后面。如果没有指定端口,则使用80端口。如果域名解析成多个IP地址,一次定义多个服务器。
以下参数可以被定义:
weight=number
设置权重,默认为1.

max_fails=number
设置与服务器通信不成功的尝试次数,它发生在fail_timeout参数设置时间,服务器被认为是不可用的时间同样由fail_timeout参数设置。默认情况下,不成功的尝试次数为1.零值禁用记录尝试次数。什么被视为不成功的尝试由proxy_next_upstream, fastcgi_next_upstream, uwsgi_next_upstream, scgi_next_upstream 和 memcached_next_upstream指令定义。

fail_timeout=time
设置

  • 一个时间,在此期间指定次数的与服务器通信不成功尝试,将会使服务器被视为不可用状态。
  • 一个时间,这段时间内服务器被视为不可用。

backup
标记服务器是一个备份服务器。当主服务器不可用时,会将请求传给它。

down
标记服务器永久不可用。

以下参数商业版可用(商业版不进行翻译):
max_conns=number
limits the maximum number of simultaneous active connections to the proxied server (1.5.9). Default value is zero, meaning there is no limit.
When keepalive connections and multiple workers are enabled, the total number of connections to the proxied server may exceed the max_conns value.

resolve
monitors changes of the IP addresses that correspond to a domain name of the server, and automatically modifies the upstream configuration without the need of restarting nginx (1.5.12). The server group must reside in the shared memory.
In order for this parameter to work, the resolver directive must be specified in the http block. Example:

http {
    resolver 10.0.0.1;

    upstream u {
        zone ...;
        ...
        server example.com resolve;
    }
}

route=string
sets the server route name.

service=name
enables resolving of DNS SRV records and sets the service name (1.9.13). In order for this parameter to work, it is necessary to specify the resolve parameter for the server and specify a hostname without a port number.
If the service name does not contain a dot (“.”), then the RFC-compliant name is constructed and the TCP protocol is added to the service prefix. For example, to look up the _http._tcp.backend.example.com SRV record, it is necessary to specify the directive:

server backend.example.com service=http resolve;
If the service name contains one or more dots, then the name is constructed by joining the service prefix and the server name. For example, to look up the _http._tcp.backend.example.com and server1.backend.example.com SRV records, it is necessary to specify the directives:

server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;

Highest-priority SRV records (records with the same lowest-number priority value) are resolved as primary servers, the rest of SRV records are resolved as backup servers. If the backup parameter is specified for the server, high-priority SRV records are resolved as backup servers, the rest of SRV records are ignored.

slow_start=time
sets the time during which the server will recover its weight from zero to a nominal value, when unhealthy server becomes healthy, or when the server becomes available after a period of time it was considered unavailable. Default value is zero, i.e. slow start is disabled.

如果一个组里只有一个服务器max_fails, fail_timeout 和slow_start参数会忽略,这个服务器永远不会被视为不可用。

zone

语法:zone name [size]
默认:—
上下文:upstream
版本:1.9.0+

定义共享内存区域名称和大小,用于保存组配置和运行状态共工作进程之间共享。多个组可以共享相同的区域。这种情况下,仅指定一次大小就够了。
另外,在商业版本中,这些组允许在不重启nginx改变组的成员或修改一个服务器的配置。配置通过一个特殊的由upstream_conf处理的location访问。

state

语法:state file
默认:—
上下文:upstream
版本:1.9.7+

指定一个文件,用于保存动态配置组的状态。状态目前受列表中的服务器的参数限制。文件会在解析配置读取,每次upstream配置改变时更新。直接改变文件内容的行为应该避免。这个指令不能与server指令一同使用。
在配置重新加载和二进制升级过程中的改变会丢失。
该指令是商业版本的一部分。

hash

语法:hash key [consistent]
默认:—
上下文:upstream
版本:1.7.2+

为服务器组指定一个负载均衡的方法:客户端-服务器映射基于哈希键值。可以包含文本、变量以及它们的混合。注意,从组中添加或移除服务器可能会导致大部分的关键字都重新映射到不同的服务器。该方法与Cache::Memcached Perl库一致。
如果指定consistent参数,ketama一致性哈希算法将被使用。该方法确保当服务器添加到组或从组中删除时只有一少部分关键字会被映射到不同的服务器。这有助于为缓存服务器获得更高的缓存命中率。该方法与Cache::Memcached::Fast Perl库ketama_points参数设为60一致。

ip_hash

语法:ip_hash
默认:—
上下文:upstream

指定一个组使用负载均衡方法基于客户端IP地址分配服务器。客户端IPv4地址的前三字节或整个IPv6地址作为哈希关键字。该方法确保来自相同的客户端请求将总会被传给同一个服务器,除非服务器不可用。在最后一种情况下,客户端请求将会传给另一个服务器。大部分情况下,总会传给相同的服务器。
IPv6地址从1.3.2和1.2.2版本开始支持。
如果其中一个服务器需要临时的移除,需要标记为down以保留当前的客户端IP地址哈希。
例子:

upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}

直到1.3.1和1.2.2版本,不能为使用ip_hash负载均衡的服务器指定权重。

keepalive

语法:keepalive connections
默认:—
上下文:upstream
版本:1.1.4+

为连接到上游服务器的连接开启缓存。
connections参数设置了每个工作进程保留的缓存连接到上游服务器空闲keepalive连接的最大数量。当这个数量被超过了,最近最少使用的连接将被关闭。
尤其要注意的是,keepalive指令不能限制一个nginx工作进程可以打开到上游服务器的连接总数。connections参数应该设置的足够小,以让上游服务器处理新的连接。

memcached上游服务器使用keepalive连接的示例配置:

upstream memcached_backend {
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;

    keepalive 32;
}

server {
    ...

    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }

}

对于HTTP,proxy_http_version指令应设置为“1.1”,“Connection”头需要清空:

upstream http_backend {
    server 127.0.0.1:8080;

    keepalive 16;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

或者,HTTP/1.0持久连接可以通过传递“Connection: Keep-Alive”头域到上游服务器,但这种方法不推荐。
对FastCGI服务器,为keepalive连接工作需要设置fastcgi_keep_conn:

upstream fastcgi_backend {
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    ...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
        ...
    }
}

当使用除了轮询方式的负载均衡方法,需要在keepalive指令之前激活他们。
SCGI和uwsgi协议没有keepalive连接的概念。

ntlm

语法:ntlm
默认:—
上下文:upstream
版本:1.9.2+

允许代理请求使用NTLM验证。上游连接需要客户端连接发送请求的“Authorization”字段值以“Negotiate”或“NTLM”开头。后面的客户端请求需要通过同一个上游连接进行代理,保持认证上下文。
为了使NTLM验证工作,需要启用与上游服务器的keepalive连接。proxy_http_version指令需要设置为“1.1”,“Connection”头域需要清空:

upstream http_backend {
    server 127.0.0.1:8080;

    ntlm;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

当使用除了轮询方式的负载均衡方法,需要在ntlm指令之前激活他们。
该指令为商业版本的一部分。

least_conn

语法:least_conn
默认:—
上下文:upstream
版本:1.3.1+1.2.2+

指定一个服务器组使用的负载均衡方法:将请求传递给活跃连接最少的服务器,考虑服务器权重。如果有很多这样的服务器,它们会使用带权重的轮询方法轮流尝试。

least_time

语法:least_time header | last_byte
默认:—
上下文:upstream
版本:1.7.10+

指定一个服务器组的负载均衡方法:请求传给最少平均响应时间和最少活动的连接的服务器,考虑权重。如果由多个这样的服务器,他们会使用有权重的轮询法轮流尝试。
如果指定了header参数,会使用收到响应头的时间。如果指定last_byte参数,使用完整响应收到的时间。
该指令为商业版本的一部分。

health_check

语法:health_check [parameters]
默认:—
上下文:location

启用指定location内服务器组的周期性健康检查。
支持下面的可选参数:
interval=time
设置两次连续的健康检查间隔,默认5秒。

fails=number
设置一个服务器的连续健康检查失败次数,超过这个次数,服务器会认为是不健康的,默认是1。

passes=number
设置一个服务器的连续检查通过次数,超过这个次数,服务器会被认为是健康的,默认是1。

uri=uri
定义用于进行健康检查的请求URI,默认是“/”。

match=name
指定match块配置响应需要通过的测试,默认响应应该是2xx或3xx状态码。

port=number
定义用于连接服务器进行健康检查的端口(1.9.7+),默认为服务器端口号。

例如

location / {
    proxy_pass http://backend;
    health_check;
}

将每5秒发送“/”到每个backend组服务器。如果任何通信错误或超时发生,或被代理服务器返回状态码不是2xx或3xx,健康检查失败,服务器会被认为是不健康。客户端请求不会发送到不健康的服务器。
健康检查可以配置为检测响应的状态码,存在指定的头和值,返回正文。测试使用match指令单独配置,通过match参数引用,例如:

http {
    server {
    ...
        location / {
            proxy_pass http://backend;
            health_check match=welcome;
        }
    }

    match welcome {
        status 200;
        header Content-Type = text/html;
        body ~ "Welcome to nginx!";
    }
}

这个配置说明了一个健康检查通过条件,响应一个健康检查请求应该成功,返回200状态码,正文类型为“text/html”并在正文中包含“Welcome to nginx!”。
服务器组必须在共享内存中。
如果同一个服务器组定义了多个健康检查,任何一个健康检查的失败都会使相应的服务器被认为是不健康的。
注意大多数用于健康检查的变量都是空的。
该指令是商业版本的一部分。

match

语法:match name { … }
默认:—
上下文:http

定义命名的测试设置,用于验证健康检查请求的响应。
下面可以在响应中测试:
status 200;
状态码200

status ! 500;
状态码不是500

status 200 204;
状态码200或204

status ! 301 302;
状态码既不是301也不是302

status 200-399;
状态码范围在200到399

status ! 400-599;
状态码范围不在400到599

status 301-303 307;
状态码是301、302、303或307

header Content-Type = text/html;
头包含“Content-Type”值为text/html

header Content-Type != text/html;
头包含“Content-Type”值不是text/html

header Connection ~ close;
头包含“Connection”值匹配正则表达式close

header Connection !~ close;
头包含“Connection”值不匹配正则表达式close

header Host;
头包含“Host”

header ! X-Accel-Redirect;
头缺少 “X-Accel-Redirect”

body ~ “Welcome to nginx!”;
正文匹配正则表达式“Welcome to nginx!”

body !~ “Welcome to nginx!”;
正文不匹配正则表达式“Welcome to nginx!”

如果指定了多个测试,只有所有测试都匹配,响应才匹配。
只有响应体的前256k会被检查。

例子:

# status is 200, content type is "text/html",
# and body contains "Welcome to nginx!"
match welcome {
    status 200;
    header Content-Type = text/html;
    body ~ "Welcome to nginx!";
}
# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
match not_redirect {
    status ! 301-303 307;
    header ! Refresh;
}
# status ok and not in maintenance mode
match server_ok {
    status 200-399;
    body !~ "maintenance mode";
}

该指令为商业版本的一部分。

queue

语法:queue number [timeout=time]
默认:—
上下文:upstream
版本:1.5.12+

如果上游服务器在处理请求时不能立即选择,组中的服务器有些达到了最大连接数限制,请求将被放到队列里。该指令指定了同一时间可以放入队列的最大请求数。如果队列满了,或在timeout参数指定的时间内请求没有被选择,会返给客户端502错误码。
timeout参数默认为60秒。
该指令为商业版本的一部分。

sticky

语法:sticky cookie name [expires=time] [domain=domain] [httponly] [secure] [path=path]
sticky route $variable
sticky learn create=$variable lookup=$variable zone=name:size [timeout=time]
默认:—
上下文:upstream
版本:1.5.7+

开启粘性session,来自同一个客户端的请求将传给组中的同一个服务器。可用三种方式:
cookie
使用cookie方式时,由nginx生成指派服务器信息的HTTP cookie:

upstream backend {
    server backend1.example.com;
    server backend2.example.com;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

来自于一个客户端的请求必定发送到一个负载均衡方式配置的特定服务器。后面的请求带着这个cookie将会发到指派的服务器上。如果指派服务器不能处理请求,会选择新的服务器,就好像客户端没有绑定。
第一个参数设置了cookie的名字。附加的参数可以是下面的:
expires=time
设置浏览器应保持cookie的时间。特殊值max将使cookie在“31 Dec 2037 23:55:55 GMT”时间过期。如果参数没有指定,将会使cookie在浏览器会话结束时过期。

domain=domain
设置cookie的域名。

httponly
添加cookie的HttpOnly属性(1.7.11+)。

secure
添加cookie的secure属性(1.7.11+)。

path=path
定义设置cookie的路径。

如果任何参数省略,相应的cookie域不会设置。

route
当使用route方法时,被代理服务器在收到第一个请求后分配客户端路由。所有来自这个客户端的子请求在cookie或URI中都会携带路由信息。这个信息会与“route”参数比较,决定哪个服务器应该被代理。如果指派的服务器不能处理请求,一个新的服务器会被选中,如同请求中没有路由信息一样。
route方法参数定义变量可以包含路由信息。第一个非空的变量用于查找匹配的服务器。
例子:

map $cookie_jsessionid $route_cookie {
    ~.+\.(?P\w+)$ $route;
}

map $request_uri $route_uri {
    ~jsessionid=.+\.(?P\w+)$ $route;
}

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;

    sticky route $route_cookie $route_uri;
}

这里,路由从请求cookie的“JSESSIONID”中取,如果没有,则从URI中取。

learn
当使用learn方法(1.7.1+),nginx分析上游服务器的响应,并学习通常服务器通过HTTP cookie发送的会话。

upstream backend {
   server backend1.example.com:8080;
   server backend2.example.com:8081;

   sticky learn
          create=$upstream_cookie_examplecookie
          lookup=$cookie_examplecookie
          zone=client_sessions:1m;
}

这个例子中,上游服务器通过响应中的cookie“EXAMPLECOOKIE”创建了一个会话。后续的请求带着这个cookie都会传给同一个服务器。如果服务器不能处理请求,会选择一个新的服务好像客户端没有绑定一样。
参数create和lookup指定了变量,分别表明新的会话如何创建,存在的会话如何查找。两个参数都可以定义超过一次,这时第一个非空变量将被使用。
会话保存在共享内存区域,名称和大小通过zone参数配置。1M的区域可以保存大约8000个会话,在64位系统上。在timeout参数指定的时间内会话没有被访问的将被从区域内删除。默认超时为10分钟。
该指令为商业版本的一部分。

sticky_cookie_insert

语法:sticky_cookie_insert name [expires=time] [domain=domain] [path=path]
默认:—
上下文:upstream

该指令从1.5.7版本开始废弃。等价的sticky指令的新语法为:
sticky cookie name [expires=time] [domain=domain] [path=path]

内嵌变量
ngx_http_upstream_module模块支持以下内嵌变量:


$upstream_addr
保存上游服务器的IP地址和端口号,或UNIX-domain socket路径。如果在处理请求时有多个服务器参与,它们的地址会用逗号分割,例如“192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock”。如果从一个服务器组发生了内部重定向,由“X-Accel-Redirect”发起或error_page,那么服务器地址不同的组会使用冒号分割,例如“192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80”。


$upstream_cache_status
保存访问缓存响应的状态(0.8.3+)。状态可以是“MISS”, “BYPASS”, “EXPIRED”, “STALE”, “UPDATING”, “REVALIDATED”或“HIT”。


$upstream_connect_time
保留与上游服务器建立连接花费的时间(1.9.1+)。时间为秒数精确到毫秒。如果是SSL,包含握手的时间消耗。多个连接的时间通过逗号和冒号分割,就像$upstream_addr变量中的地址一样。


$upstream_cookie_name
指定名称的cookie通过“Set-Cookie”响应头从上游服务器发送(1.7.1+)。只有最后一个服务器响应的cookie会被保存。


$upstream_header_time
保存从上游服务器收到响应头的时间花费(1.7.10+)。时间为秒数精确到毫秒。多个响应的时间以逗号分割,就像$upstream_addr变量中的地址。


$upstream_http_name
保存服务器响应头。例如,“Server”响应头可以通过$upstream_http_server变量使用。转换头域名称到变量名称的规则与“$http_”前缀开头的变量相同。只有最后一个服务器响应头的头域会保存。


$upstream_response_length
保存从上游服务器收到的响应长度(0.7.27+)。长度单位为字节。多个响应的字节以逗号和冒号分割,就像$upstream_addr变量的地址一样。


$upstream_response_time
保存从上游服务器收到请求花费的时间。时间单位为秒,精确到毫秒。多个响应的时间以逗号和冒号分割,就像$upstream_addr变量的地址一样。


$upstream_status
保存从上游服务器收到响应的状态码。多个响应的状态码以逗号和冒号分割,就像$upstream_addr变量的地址一样。

nginx中文文档-ngx_http_sub_module

ngx_http_sub_module是一个过滤器,用于通过替换指定字符串改变响应。

该模块默认不会构建,需要通过–with-http_sub_module参数启用。

示例配置

location / {
    sub_filter '<a href="http://127.0.0.1:8080/'  '<a href="https://$host/';
    sub_filter '<img src="http://127.0.0.1:8080/' '<img src="https://$host/';
    sub_filter_once on;
}

sub_filter

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

设置替换和被替换的字符串。字符串替换忽略大小写。要替换的字符串(1.9.4+)和替换字符串可以包含变量。多个sub_filter指令可以在同一个配置等级中指定(1.9.4+)。

sub_filter_last_modified

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

在替换过程中允许保留原始响应中的“Last-Modified”头域,以助于响应缓存。
默认情况下,头域会被删除因为在处理过程中响应发生了变化。

sub_filter_once

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

指示仅替换字符串一次,还是重复替换每一个字符串。

sub_filter_types

语法:sub_filter_types mime-type
默认:sub_filter_types text/html
上下文:http, server, location

启用除“text/html”外指定的MIME类型处理响应替换。特殊值“*”匹配任何MIME请求(0.8.29+)。

nginx中文文档-ngx_http_stub_status_module

此页面版本:2016-06-08
ngx_http_stub_status_module模块提供访问基本的状态信息。

该模块默认不会构建,需要通过–with-http_stub_status_module配置参数启用。

示例配置

location /basic_status {
    stub_status;
}

该配置创建了一个含有基本状态数据的简单网页,看起来如下:

Active connections: 291 
server accepts handled requests
 16630948 16630948 31070465 
Reading: 6 Writing: 179 Waiting: 106 

stub_status

语法:stub_status
默认:—
上下文:server, location

在location中可以访问基本状态信息。
在1.7.5版本之前,指令语法需要专门的参数,例如“stub_status on”。

数据
提供下面的状态信息:

Active connections
当前活动的客户端连接数包括等待的连接。

accepts
接收的客户端连接总数。

handled
处理连接总数。一般地,参数的值与accepts相同,除非一些资源的限制达到了(比如worker_connections限制)。

requests
客户端请求总数。

Reading
当前nginx正在读取请求头的连接数。

Writing
当前nginx正在写响应的连接数。

Waiting
当前等待请求的空闲客户端连接数。

内嵌变量
ngx_http_stub_status_module模块支持下面的内嵌变量(1.3.14+):

$connections_active
与Active connections值相同


$connections_reading
与Reading值相同


$connections_writing
与Writing值相同


$connections_waiting
与Waiting值相同

nginx中文文档-ngx_http_status_module

ngx_http_status_module模块提供访问多种状态信息。

该版本为商业版本。

示例配置

http {
    upstream backend {
        zone http_backend 64k;

        server backend1.example.com weight=5;
        server backend2.example.com;
    }

    proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m;

    server {
        server_name backend.example.com;

        location / {
            proxy_pass  http://backend;
            proxy_cache cache_backend;

            health_check;
        }

        status_zone server_backend;
    }

    server {
        listen 127.0.0.1;

        location /upstream_conf {
            upstream_conf;
        }

        location /status {
            status;
        }

        location = /status.html {
        }
    }
}

stream {
    upstream backend {
        zone stream_backend 64k;

        server backend1.example.com:12345 weight=5;
        server backend2.example.com:12345;
    }

    server {
        listen      127.0.0.1:12345;
        proxy_pass  backend;
        status_zone server_backend;
        health_check;
    }
}

这个配置的示例状态请求:

http://127.0.0.1/status
http://127.0.0.1/status/nginx_version
http://127.0.0.1/status/caches/cache_backend
http://127.0.0.1/status/upstreams
http://127.0.0.1/status/upstreams/backend
http://127.0.0.1/status/upstreams/backend/peers/1
http://127.0.0.1/status/upstreams/backend/peers/1/weight
http://127.0.0.1/status/stream
http://127.0.0.1/status/stream/upstreams
http://127.0.0.1/status/stream/upstreams/backend
http://127.0.0.1/status/stream/upstreams/backend/peers/1
http://127.0.0.1/status/stream/upstreams/backend/peers/1/weight

默认配置中访问“/status.html”会输出简单的监控页面。需要将location“/status”和“/status.html”按如上方法配置。

status

语法:status
默认:—
上下文:location

从location访问状态信息。访问这个location应该有限制。

status_format

语法:status_format json
status_format jsonp [callback]
默认:status_format json
上下文:http, server, location

默认情况下,状态信息输出为JSON格式。
数据也可以输出为jsonp格式。callback参数指定了回调函数名。值可以包含变量。如果参数省略或是一个空字符串,会使用“ngx_status_jsonp_callback”。

status_zone

语法:status_zone zone
默认:—
上下文:server

启用收集在指定区域虚拟http或stream(1.7.11+)服务器状态信息。多个服务器可以共享相同的区域。

数据
提供下面的状态信息:

version
提供数据集的版本当前版本是6.

nginx_version
nginx版本。

address
接收状态请求的服务器地址。

generation
配置重新加载的总次数。

load_timestamp
最后一次重新加载配置文件的时间,从纪元开始的毫秒数。

timestamp
当前时间从纪元开始的毫秒数。

pid
处理状态请求的工作进程ID

processes
respawned
非正常结束和复位子线程的总数。

connections
accepted
接收客户端连接的总数。
dropped
丢弃客户端连接的总数。
active
当前活跃的客户端连接总数。
idle
当前空闲的客户端连接总数。

ssl
handshakes
成功的SSL握手总数。
handshakes_failed
失败的SSL握手总数。
session_reuses
SSL握手过程中重用的会话总数。

requests
total
客户端请求总数。
current
当前客户端请求数。

server_zones
对于每一个status_zone:
processing
当前处理的客户端请求数。
requests
从客户端收到的请求总数。
responses
total
发送给客户端的响应总数。
1xx, 2xx, 3xx, 4xx, 5xx
状态码1xx, 2xx, 3xx, 4xx和5xx的响应数。
discarded
没有发送响应的完成请求数。
received
从客户端收到的总字节数。
sent
发送到客户端的总字节数。

upstreams
peers
对每一个server,提供下面的数据:
id
服务器ID
server
服务器地址
backup
一个布尔值,表示服务器是否是备份服务器。
weight
服务器权重
state
当前状态,可能是“up”, “draining”, “down”, “unavail”或“unhealthy”
active
当前活动的连接数。
max_conns
服务器最大连接数。
requests
客户端转发到本服务器的总请求数。
responses
total
从服务器收到的响应的总数。
1xx, 2xx, 3xx, 4xx, 5xx
1xx, 2xx, 3xx, 4xx, 5xx状态码的请求数。
sent
发送到该服务器的总字节数。
received
从服务器接收到的总字节数。
fails
与该服务器通信的不成功尝试总数。
unavail
多少次服务器变成不可用状态(“unavail”状态),这是由于不成功的尝试次数达到了max_fails阈值。
health_checks
checks
健康检查请求总数。
fails
失败的健康检查数。
unhealthy
多少次服务器变成不健康状态。
last_passed
布尔值,表示最后一次健康检查请求是否成功且通过测试。
downtime
服务器在“unavail”和“unhealthy”状态的总时间。
downstart
服务器变为“unavail”或“unhealthy”状态的时间(从纪元开始的毫秒数)
selected
服务器最后一次被选中处理请求的时间(从纪元开始的毫秒数)
header_time
从服务器获取响应头的平均时间(1.7.10+)。当使用least_time方式的负载均衡时,该字段可用。
response_time
从服务器获取完整响应的平均时间(1.7.10+)。当使用least_time方式的负载均衡时,该字段可用。
keepalive
当前空闲的keepalive连接数。
queue
对于请求queue,提供下面的数据:
size
当前队列中的请求数。
max_size
同一时间队列中的最大请求数。
overflows
由于队列溢出拒绝的请求总数。

caches
size
当前缓存大小。
max_size
配置文件中指定的缓存大小最大限制。
cold
一个布尔值,表示“cache loader”进程是否仍在从磁盘加载数据到缓存。
hit, stale, updating, revalidated
responses
从缓存读取响应的总数。
bytes
从缓存读取的总字节数。
miss, expired, bypass
responses
没有从缓存取的响应总数。
bytes
从被代理服务器读取的字节总数。
responses_written
写入到缓存的响应总数。
bytes_written
写入到缓存的总字节数。

stream
server_zones
processing
当前处理的客户端连接数。
connections
从客户端接受的连接总数。
received
从客户端收到的字节总数。
sent
发送到客户端的字节总数。
upstreams
peers
id
服务器ID
server
服务器地址
backup
一个布尔值,表示服务器是否是备份服务器。
weight
服务器权重
state
当前状态,可能是“up”, “draining”, “down”, “unavail”或“unhealthy”
active
当前活动的连接数。
connections
转发到本服务器的客户端连接总数。
connect_time
连接上游服务器的平均时间。当使用least_time方式的负载均衡时,该字段可用。
first_byte_time
收到数据首字节平均时间。当使用least_time方式的负载均衡时,该字段可用。
response_time
收到数据最后一个字节平均时间。当使用least_time方式的负载均衡时,该字段可用。
sent
发送到该服务器的总字节数。
received
从服务器接收到的总字节数。
fails
与该服务器通信的不成功尝试总数。
unavail
多少次服务器变成不可用状态(“unavail”状态),这是由于不成功的尝试次数达到了max_fails阈值。
health_checks
checks
健康检查请求总数。
fails
失败的健康检查数。
unhealthy
多少次服务器变成不健康状态。
last_passed
布尔值,表示最后一次健康检查请求是否成功且通过测试。
downtime
服务器在“unavail”和“unhealthy”状态的总时间。
downstart
服务器变为“unavail”或“unhealthy”状态的时间(从纪元开始的毫秒数)
selected
服务器最后一次被选中处理请求的时间(从纪元开始的毫秒数)

兼容性

  • ssl状态在版本6中添加。
  • server_zones中的discarded字段在版本6中添加
  • queue状态数据在版本6中添加。
  • pid字段在版本6中添加。
  • upstreams中的服务器列表在版本6中移动到peers中。
  • 上游服务器的keepalive字段在版本5中移除。
  • stream状态数据在版本5中添加。
  • generation字段在版本5中添加。
  • processes中的respawned字段在版本5中添加。
  • upstreams中的header_time和response_time字段在版本5中添加。
  • upstreams中的selected字段在版本4中添加。
  • upstreams中的draining状态在版本4中添加。
  • upstreams中的id和max_conns字段在版本3中添加。
  • caches中的revalidated字段在版本3中添加。
  • server_zones, caches和load_timestamp状态数据在版本2中添加。

nginx中文文档-ngx_http_ssl_module

此页面版本:2016-06-08
ngx_http_ssl_module模块为HTTPS提供必要的支持,该模块默认不会构建,需要通过–with-http_ssl_module配置参数启用。该模块需要OpenSSL库。

示例配置
为减少处理器加载,建议:

  • 设置工作进程数等于处理器数
  • 启用keep-alive连接
  • 启用共享会话缓存
  • 禁用build-in会话缓存
  • 增加会话的有效期(默认是5分钟)
worker_processes auto;

http {

    ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/nginx/conf/cert.pem;
        ssl_certificate_key /usr/local/nginx/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        ...
    }

ssl

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

为给定的虚拟服务器启用HTTPS协议支持。
建议用listen指令的ssl参数替代这个指令。

ssl_buffer_size

语法:ssl_buffer_size size
默认:ssl_buffer_size 16k
上下文:http, server
版本:1.5.9+

设置发送数据缓冲区的大小。
默认,缓冲区大小为16k,对发送很大的响应消耗很小。为了减少首字节发送时间,可以用更小的值,例如:
ssl_buffer_size 4k;

ssl_certificate

语法:ssl_certificate file
默认:—
上下文:http, server

为给定的虚拟服务器指定一个PEM格式的证书文件。如果除初级证书之外还需要中级证书,它们需要在同一个文件中按如下顺序指定:先指定初级证书,然后是中级证书。PEM格式的密钥也需要放在同一个文件中。
从1.11.0版本开始,该指令可以指定多次加载不同的证书类型,例如RSA和ECDSA:

server {
    listen              443 ssl;
    server_name         example.com;

    ssl_certificate     example.com.rsa.crt;
    ssl_certificate_key example.com.rsa.key;

    ssl_certificate     example.com.ecdsa.crt;
    ssl_certificate_key example.com.ecdsa.key;

    ...
}

只有OpenSSL 1.0.2或更高版本支持为不同的证书分离证书链,老版本只能用一个证书链。
注意,由于HTTPS协议限制,虚拟服务器需要监听不同的IP地址:

server {
    listen          192.168.1.1:443;
    server_name     one.example.com;
    ssl_certificate /usr/local/nginx/conf/one.example.com.cert;
    ...
}

server {
    listen          192.168.1.2:443;
    server_name     two.example.com;
    ssl_certificate /usr/local/nginx/conf/two.example.com.cert;
    ...
}

否则第一个服务器证书将颁发给第二个网站。

ssl_certificate_key

语法:ssl_certificate_key file
默认:—
上下文:http, server

为给定的虚拟服务器指定PEM格式的密钥文件。可以使用engine:name:id值替代file(1.7.9+),从OpenSSL引擎name加载指定id的密钥。

ssl_ciphers

语法:ssl_ciphers ciphers
默认:ssl_ciphers HIGH:!aNULL:!MD5
上下文:http, server

指定可以使用的加密算法。加密算法为OpenSSL库可以理解的格式,例如:
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
完整列表可以通过“openssl ciphers”命令查看。
之前版本的nginx默认使用不同的加密算法。

ssl_client_certificate

语法:ssl_client_certificate file
默认:—
上下文:http, server

指定一个PEM格式的可信CA证书文件,用于验证客户端证书,如果ssl_stapling启用,验证OCSP响应。
证书列表会发给客户端,如果不希望这样做,可以使用ssl_trusted_certificate指令。

ssl_crl

语法:ssl_crl file
默认:—
上下文:http, server
版本:0.8.7+

指定一个PEM格式的吊销证书列表文件,用于验证客户端证书。

ssl_dhparam

语法:ssl_dhparam file
默认:—
上下文:http, server
版本:0.7.2+

指定DHE算法DH参数的文件。

ssl_ecdh_curve

语法:ssl_ecdh_curve curve
默认:ssl_ecdh_curve auto
上下文:http, server
版本:1.1.0+,1.0.6+

为ECDHE算法指定curve。
当使用OpenSSL 1.0.2及更高版本时,可以指定多个curves,例如,
ssl_ecdh_curve prime256v1:secp384r1;
特殊值auto指示nginx在OpenSSL 1.0.2或更高版本时使用一个OpenSSL内建的列表,老版本使用prime256v1
在1.11.0版本以前,默认值是prime256v1。

ssl_password_file

语法:ssl_password_file file
默认:—
上下文:http, server
版本:1.7.3+

指定一个包含密钥密码的文件,每个密码占用一行,当加载密钥时会轮流尝试密码。
例子:

http {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name www1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name www2.example.com;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}

ssl_prefer_server_ciphers

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

当使用SSLv3和TLS协议时,指定服务器首选加密算法。

ssl_protocols

语法:ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]
默认:ssl_protocols TLSv1 TLSv1.1 TLSv1.2
上下文:http, server

启用指定的协议。TLSv1.1和TLSv1.2参数只有在OpenSSL库大于等于1.0.1版本上可用。
TLSv1.1和TLSv1.2参数从1.1.13和1.0.12版本开始支持,所以当在OpenSSL版本大于等于1.0.1的老版本nginx上这些协议工作,但不能禁用。

ssl_session_cache

语法:ssl_session_cache off | none | [builtin[:size]] [shared:name:size]
默认:ssl_session_cache none
上下文:http, server

设置存储session参数的缓存类型和大小。缓存可以是下面任一类型:
off
严格禁止使用会话缓存:nginx明确的告知客户端会话不能重用。

none
使用会话缓存不允许:nginx告诉客户端会话可以重用,但是在缓存中并不存储会话参数。

builtin
缓存建立在OpenSSL中,只被一个工作进程使用。缓存大小在会话中指定。如果大小没有给出,等于20480个session。使用built-in缓存可以导致内存碎片。

shared
缓存在所有工作进程中共享。缓存大小指定为字节数,1M可以存储大约4000个会话。每个共享缓存应该有一个专门的名字。相同名字的缓存可以在多个虚拟服务器之间使用。

所有缓存类型都可以同时使用,例如:
ssl_session_cache builtin:1000 shared:SSL:10m;
不使用built-in缓存只用共享缓存更有效。

ssl_session_ticket_key

语法:ssl_session_ticket_key file
默认:—
上下文:http, server
版本:1.5.7+

设置带有密钥的文件用于加密解密TLS会话凭证。如果相同的密钥在多个服务器之间共享,这个指令是必要的。默认情况下,使用随机生成的密钥。
如果定义了几个秘钥,只有第一个秘钥会用于加密TLS会话凭证。这允许配置密钥轮询,例如:

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

文件必须包含48字节的随机数据,可以用以下命令创建:
openssl rand 48 > ticket.key

ssl_session_tickets

语法:ssl_session_tickets on | off
默认:ssl_session_tickets on
上下文:http, server
版本:1.5.9+

启用或禁用重用会话。

ssl_session_timeout

语法:ssl_session_timeout time
默认:ssl_session_timeout 5m
上下文:http, server

指定一个时间,在这个期间内,客户端可以重用保存在缓存中的会话参数。

ssl_stapling

语法:ssl_stapling on | off
默认:ssl_stapling off
上下文:http, server
版本:1.3.7+

启用或禁用stapling of OCSP responses功能,例如:

ssl_stapling on;
resolver 192.0.2.1;

为了使OCSP stapling工作,服务器证书的颁发者应该熟知的。如果ssl_certificate文件不包含中级证书,服务器证书的颁发者需要出现在ssl_trusted_certificate文件中。
为了解析OCSP的主机名,resolver指令需要指定。

ssl_stapling_file

语法:ssl_stapling_file file
默认:—
上下文:http, server
版本:1.3.7+

当设置了此指令,OCSP响应会从指定的文件中取,而不是查询OCSP响应器指定的服务器证书。
这个文件需要DER格式,由“openssl ocsp”命令提供。

ssl_stapling_responder

语法:ssl_stapling_responder url
默认:—
上下文:http, server
版本:1.3.7+

覆盖OCSP响应器指定在“Authority Information Access”证书扩展项中的URL。
只有“http://”OCSP响应器被支持:
ssl_stapling_responder http://ocsp.example.com/;

ssl_stapling_verify

语法:ssl_stapling_verify on | off
默认:ssl_stapling_verify off
上下文:http, server
版本:1.3.7+

启用或启用服务器验证OCSP响应。
为了使验证工作,服务器证书颁发者,根证书以及所有中级证书需要使用ssl_trusted_certificate指令设置为可信。

ssl_trusted_certificate

语法:ssl_trusted_certificate file
默认:—
上下文:http, server
版本:1.3.7+

指定一个PEM格式的可信CA证书文件,用于验证客户端证书以及在ssl_stapling启用时验证OCSP响应。
与ssl_client_certificate设置的证书相比,这个证书列表不会发给客户端。

ssl_verify_client

语法:ssl_verify_client on | off | optional | optional_no_ca
默认:ssl_verify_client off
上下文:http, server

启用验证客户端证书。验证结果保存在$ssl_client_verify变量中。
optional参数(0.8.7+)请求客户端证书,如果证书存在则会验证它。
optional_no_ca参数(1.3.8+,1.2.5+)请求客户端证书,但是不需要由可信的CA证书签发。这个一般用于nginx外部服务实际去验证证书。证书的内容可以通过$ssl_client_cert变量访问。

ssl_verify_depth

语法:ssl_verify_depth number
默认:ssl_verify_depth 1
上下文:http, server

设置在客户端证书链中验证的深度。

错误处理
ngx_http_ssl_module模块支持一些非标准的错误码,可以用于重定向到error_page指令:
495
当客户端证书验证过程中出现错误。

496
客户端没有给出需要的证书。

497
一个常规的请求被发到了HTTPS端口。

重定向发生在请求完全解析后,变量如$request_uri, $uri, $args和其他的都可以使用。

内嵌变量
ngx_http_ssl_module模块支持一些内嵌变量:


$ssl_cipher
返回建立SSL连接使用的加密算法字符串。


$ssl_client_cert
返回PEM格式的客户端证书,用于建立SSL连接,除第一行外,每一行前面都有tab字符。这个用于proxy_set_header指令使用。


$ssl_client_fingerprint
返回客户端建立SSL连接的证书SHA1指纹(1.7.1+)。


$ssl_client_raw_cert
返回建立SSL连接时PEM格式的客户端证书。


$ssl_client_serial
返回建立SSL连接时PEM格式的客户端证书的序号。


$ssl_client_s_dn
返回建立SSL连接时PEM格式的客户端证书的“subject DN”字符串。


$ssl_client_i_dn
返回建立SSL连接时PEM格式的客户端证书的“issuer DN”字符串。


$ssl_client_verify
返回客户端证书验证结果:“SUCCESS”,“FAILED”以及当证书没有出现时的“NONE”。


$ssl_protocol
返回建立SSL连接时的协议。


$ssl_server_name
返回通过SNI查询的服务器名称(1.7.0+)。


$ssl_session_id
返回建立SSL连接的会话标识符。


$ssl_session_reused
如果SSL会话重用,返回“r”,否则为“.”(1.5.11+)。

nginx中文文档-ngx_http_ssi_module

此页面版本:2016-06-08
ngx_http_ssi_module模块是一个过滤器,用于处理传给它的响应中的SSI(Server Side Includes)命令。目前支持的SSI命令列表还不完全。

示例配置

location / {
    ssi on;
    ...
}

ssi

语法:ssi on | off
默认:ssi off
上下文:http, server, location, if in location

启用或禁用处理响应中的SSI命令。

ssi_last_modified

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

在处理SSI时,允许保存原始响应头中的“Last-Modified”字段,以助于响应缓存。
默认情况下,这个头域会被移除,因为响应的内容在处理过程中会改变,也可能包含动态生成的元素或与原始响应独立改变的部分。

ssi_min_file_chunk

语法:ssi_min_file_chunk size
默认:ssi_min_file_chunk 1k
上下文:http, server, location

设置响应保存到磁盘上最小的部分大小,从这个值开始,会用sendfile发送。

ssi_silent_errors

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

如果启用,在SSI处理过程中发生了错误,会禁止输出“[an error occurred while processing the directive]”字符串。

ssi_types

语法:ssi_types mime-type
默认:ssi_types text/html
上下文:http, server, location

启用指定的除了“text/html”之外的MIME类型响应处理SSI命令。特殊值“*”匹配任何的MIME类型(0.8.29+)。

ssi_value_length

语法:ssi_value_length length
默认:ssi_value_length 256
上下文:http, server, location

设置SSI命令中最大的参数值长度。

SSI 命令
SSI命令有以下一般的格式:

下面的命令也支持:
block
定义一个块,用作include命令的存根。块可以包含其他SSI命令。命令可以由以下参数:
name
块名称
例子:


stub

config
设置在SSI处理过程中的一些参数:
errmsg
如果在SSI处理过程中发生错误,则输出这个字符串。默认情况下,以下字符串会被输出:
[an error occurred while processing the directive]
timefmt
传给strftime()函数的格式字符串用于输出日期和时间。默认情况下,使用下面的格式:
"%A, %d-%b-%Y %H:%M:%S %Z"
“%s”格式匹配输出时间的秒数

echo
输出变量的值,该命令有如下参数:
var
变量名称
encoding
编码方式。可能的值包含none,url和entity。默认情况下使用entity。
default
非标准参数用于设置当变量未定义时输出的字符串。默认情况下,输出“none”。命令

替换下面的命令:
no

if
条件包含。下面的命令受支持:


...

...

...

目前只支持一级嵌套。命令有以下参数:
expr
表达式,可以是:
变量存在性检测:

变量与值对比:



变量与正则表达式对比:



如果text包含变量,它们的值会被替代。正则表达式可以包含位置捕获和名称捕获,可以在后面通过变量使用,例如:


    
    

include
在响应中包含另一个请求的结果。该命令有以下参数:
file
指定一个包含文件,例如:

virtual
指定一个包含的请求,例如:

一个页面指定多个请求并由被代理服务器或FastCGI/uwsgi/SCGI服务器并行处理。如果希望串行处理,使用wait参数。
stub
非标准参数用于命名将被输出的块,这些块在包含的请求结果为空或处理请求过程中出现错误时会被输出,例如:

 

替换块的内容会在包含请求的上下文中处理。
wait
非标准参数,在一个请求完全完成前进行等待,例如:

set
非标准参数,成功的请求处理结果写到指定变量中,例如:

需要注意,只有使用ngx_http_proxy_module, ngx_http_memcached_module, ngx_http_fastcgi_module (1.5.6+), ngx_http_uwsgi_module (1.5.6+)以及 ngx_http_scgi_module (1.5.6+) 模块获得的响应结果可以写进变量。

set
设置变量的值,命令可以包含以下参数:
var
变量名
value
变量值。如果赋值包含变量,它们的值会被替代。

内嵌变量
ngx_http_ssi_module模块支持两个内嵌变量:


$date_local
当前时区下的时间。格式由config命令的timefmt参数指定。


$date_gmt
GMT的当前时间。格式由config命令的timefmt参数指定。

nginx中文文档-ngx_http_split_clients_module

ngx_http_split_clients_module模块创建用于进行A/B测试的变量,也叫做拆分测试。

示例配置

http {
    split_clients "${remote_addr}AAA" $variant {
                   0.5%               .one;
                   2.0%               .two;
                   *                  "";
    }

    server {
        location / {
            index index${variant}.html;

split_clients

语法:split_clients string $variable { … }
默认:—
上下文:http

为A/B测试创建变量,例如:

split_clients "${remote_addr}AAA" $variant {
               0.5%               .one;
               2.0%               .two;
               *                  "";
}

原始字符串通过MurmurHash2算法进行哈希。给出的例子中,哈希值从0到21474835(0.5%)对应的$variant值为“.one”,哈希值从21474836到107374180(2%)对应的$variant值为“.two”,哈希值从107374181到4294967295对应的$variant值为“”(空字符串)。