Nginx中文文档-ngx_http_core_module(T-V)

本文档包含以下指令:tcp_nodelay、tcp_nopush、try_files、types、types_hash_bucket_size、types_hash_max_size、underscores_in_headers、variables_hash_bucket_size、variables_hash_max_size

tcp_nodelay

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

启用或禁用TCP_NODELAY选项。该功能仅在连接已过渡到keep-alive状态下有效。

tcp_nopush

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

启用或禁用tcp_nopush功能,在FreeBSD系统上通过TCP_NOPUSH socket选项实现,在Linux通过TCP_CORK socket选项实现。只有在sendfile生效状态下才能启用。启用该选项将允许:

  • Linux和FreeBSD 4.*系统下在一个包中发送响应头和文件开头
  • 在满包中发送一个文件

try_files

语法:try_files fileuri;
try_files file … =code;
默认:—
上下文:server, location

按指定顺序检测文件是否存在,并返回第一个找到的文件,该过程在当前上下文中执行。文件的路径是由root和alias指令以及file参数构成。有可能会通过在名字后面添加“/”检测目录是否存在,例如“$uri/”。如果没有找到任何的文件,则会产生一个内部重定向到最后一个参数uri指定的文件:

location /images/ {
    try_files $uri /images/default.gif;
}

location = /images/default.gif {
    expires 30s;
}

最后一个参数可以指向一个location,如下面的例子所示。从0.7.51版本开始,最后一个参数也可以是一个code

location / {
    try_files $uri $uri/index.html $uri.html =404;
}

代理Mongrel的例子:

location / {
    try_files /system/maintenance.html
              $uri $uri/index.html $uri.html
              @mongrel;
}

location @mongrel {
    proxy_pass http://mongrel;
}

Drupal/FastCGI举例:

location / {
    try_files $uri $uri/ @drupal;
}

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    fastcgi_param SCRIPT_NAME     $fastcgi_script_name;
    fastcgi_param QUERY_STRING    $args;

    ... other fastcgi_param's
}

location @drupal {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    fastcgi_param SCRIPT_NAME     /index.php;
    fastcgi_param QUERY_STRING    q=$uri&$args;

    ... other fastcgi_param's
}

下面的例子中,

location / {
    try_files $uri $uri/ @drupal;
}

try_files指令等价于:

location / {
    error_page 404 = @drupal;
    log_not_found off;
}

下面的例子,

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;

    ...
}

try_files指令在将请求发送到FastCGI服务器之前检测文件是否存在。
Wordpress 和 Joomla的例子:

location / {
    try_files $uri $uri/ @wordpress;
}

location ~ \.php$ {
    try_files $uri @wordpress;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    ... other fastcgi_param's
}

location @wordpress {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    ... other fastcgi_param's
}

types

语法:types { … }
默认:types {
text/html html;
image/gif gif;
image/jpeg jpg;
}
上下文:http, server, location

响应的MIME与文件扩展的对照表,大小写不敏感。多个扩展名可以映射为同一个类型:

types {
    application/octet-stream bin exe dll;
    application/octet-stream deb;
    application/octet-stream dmg;
}

在conf/mime.types文件中定义了一个比较完整的映射表。
要定义一个特殊的location,所有的MIME类型都是application/octet-stream,可以用下面的配置:

location /download/ {
    types        { }
    default_type application/octet-stream;
}

types_hash_bucket_size

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

设置一个类型哈希表的大小。1.5.13版本之前,默认值的大小取决于CPU缓存行。

types_hash_max_size

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

设置类型哈希表最大的大小。

underscores_in_headers

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

启用或禁用客户端请求头域中的下划线。如果禁用了此功能,客户端请求头域中的下划线会被认为是无效的。
如果该指令定义在sever块中,只对默认的服务器有效。该值同样作用于监听了同一端口和IP的虚拟主机。

variables_hash_bucket_size

语法:variables_hash_bucket_size size
默认:variables_hash_bucket_size 64
上下文:http

设置一个变量哈希表的大小。

variables_hash_max_size

语法:variables_hash_max_size size
默认:variables_hash_max_size 1024
上下文:http

设置最大的变量哈希表大小。1.5.13版本以前,默认值是512.

Nginx中文文档-ngx_http_core_module(R-S)

本文档包含以下指令:read_ahead、recursive_error_pages、request_pool_size、reset_timedout_connection、resolver、resolver_timeout、root、satisfy、send_lowat、send_timeout、sendfile、sendfile_max_chunk、server、server_name、server_name_in_redirect、server_names_hash_bucket_size、server_names_hash_max_size、server_tokens

read_ahead

语法:read_ahead size
默认:read_ahead 0
上下文:http, server, location

设置内核预读取文件的数量。
在linux系统上,使用posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)系统调用,所以size参数被忽略。
在FreeBSD系统上,使用fcntl(O_READAHEAD, size)系统调用,从FreeBSD9.0开始可用,FreeBSD 7需要安装补丁。

recursive_error_pages

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

启用或禁用使用error_page指令产生的重定向,重定向的次数会有限制。

request_pool_size

语法:request_pool_size size
默认:request_pool_size 4k
上下文: http, server

精确调整每个请求的内存配额,这个指令对性能影响极小,一般不使用。

reset_timedout_connection

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

启用或禁用重置超时连接,重置表现如下。在关闭一个SOCKET前,SO_LINGER选项被设置成超时时间0。当SOCKET已经关闭时,RST标识会发送到客户端,该SOCKET的所有相关内存被释放。这有助于避免一个已经关闭了的SOCKET在FIN_WAIT1状态保持很长时间。
注意,超时的keep-alive连接会正常关闭。

resolver

语法:resolver address… [valid=time] [ipv6=on|off]
默认:—
上下文: http, server, location

配置了上游服务器的域名解析服务器,例如:
resolver 127.0.0.1 [::1]:5353;
address可以定义成域名或IP地址,和可选的端口号(1.3.1, 1.2.2)。
如果端口号没有定义,使用默认的53端口。域名服务器会采用轮询机制。
在1.1.7之前,只能配置一个服务器,服务器名称从1.3.1和1.2.2版本开始支持IPv6。
默认情况下,nginx在解析名称时会同时查找IPv4和IPv6,如果不需要IPv6,可以使用ipv6=off关闭。
解析IPv6的地址从1.5.8版本起开始支持。
默认情况下,nginx使用TTL对结果进行缓存,可以通过可选参数valid改变它:
resolver 127.0.0.1 [::1]:5353 valid=30s;
在1.1.9之前,不能改变缓存时间,nginx总是会缓存5分钟。

resolver_timeout

语法:resolver_timeout time
默认:resolver_timeout 30s
上下文:http, server, location

设置解析的超时时间,例如:
resolver_timeout 5s;

root

语法:root path
默认:root html
上下文:http, server, location, if in location

设置请求的根目录,例如下面的配置:

location /i/ {
    root /data/w3;
}

/data/w3/i/top.gif文件会作为“/i/top.gif”请求的响应发送出去。
path的值可以包含变量,除了$document_root 和 $realpath_root
文件路径只是简单的将URI跟在root指令设置的根目录之后,如果URI需要改变,需要使用alias指令。

satisfy

语法:satisfy all | any
默认:satisfy all
上下文:http, server, location

设置由ngx_http_access_module、ngx_http_auth_basic_module及ngx_http_auth_request_module指令制定的访问规则需要全部匹配(all)还是只要匹配一个(any)即可。
例子:

location / {
    satisfy any;

    allow 192.168.1.0/32;
    deny  all;

    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}

send_lowat

语法:send_lowat size
默认:send_lowat 0
上下文:http, server, location

如果设置非零的值,nginx会尝试通过kqueue方法的NOTE_LOWAT标识或SO_SNDLOWAT socket选项的方式将发送到客户端的socket数降到最低。这两种情况都要用到定义的size
该指令在Linux, Solaris, 和 Windows系统上会被忽略。

send_timeout

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

设置客户端传输超时时间。超时时间只作用于两次成功的写请求之间,并非是整个的响应之间的传输时间。如果客户端在超时时间已到还没有收到任何数据,就会关闭连接。

sendfile

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

开启或禁用sendfile函数的使用。
从0.8.12版本开始在FreeBSD 5.2.1,aio通过sendfile函数预加载数据:

location /video/ {
    sendfile       on;
    tcp_nopush     on;
    aio            on;
}

在这个配置中,sendfile函数如果带着SF_NODISKIO标识会引起磁盘I/O不会阻塞,数据不在内存里,nginx会初始化异步读取一个字节的数据。首次读取时FreeBSD会读取128K字节的数据到内存中,再次读取时会读取16K字节的块。可以在read_ahead指令中改变。
1.7.11版本之前,预加载可以通过aio sendfile开启。

sendfile_max_chunk

语法:sendfile_max_chunk size
默认:sendfile_max_chunk 0
上下文:http, server, location

当设置为一个非零的值,会限制调用一次sendfile函数能够传输的数据量。如果不限制,工作进程会被一个最快的连接完全抢占。

server

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

设置一个虚拟主机。在基于IP和基于主机名的虚拟主机之间划分的界限并不明确。listen指令为服务器描述了所有应该接受请求的地址和端口,server_name指令列出了所有的服务器名称。

server_name

语法:server_name name
默认:server_name “”
上下文:server

设置虚拟主机的名称,例如:

server {
    server_name example.com www.example.com;
}

第一个名称是主要的名称。
服务器名称可以用星号“*”代替名称的一部分或几部分:

server {
    server_name example.com *.example.com www.example.*;
}

这些名称叫做通配符名称。
前两个可以合并成一个:

server {
    server_name .example.com;
}

可以在server_name中使用正则表达式,前面用“~”:

server {
    server_name www.example.com ~^www\d+\.example\.com$;
}

正则表达式从0.7.40版本开始支持捕获,捕获可以在之后用在其他指令中。

server {
    server_name ~^(www\.)?(.+)$;

    location / {
        root /sites/$2;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

名称中的正则表达式捕获创建的变量(0.8.25版本起)可以在之后的其他指令中使用:

server {
    server_name ~^(www\.)?(?.+)$;

    location / {
        root /sites/$domain;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

如果指令的参数设置成“$hostname”(0.9.4),机器的名称会被使用。
也可以定义空的名称(0.7.11):

server {
    server_name www.example.com "";
}

它允许服务器处理请求头不带Host域的请求。
0.8.48之前,默认使用机器的hostname。
在通过名称查找虚拟主机的过程中,如果名称匹配了超过一个变量(如通配符和正则都匹配了),会选择最先匹配的,使用下面的优先级:

  • 具体名称
  • 最长的以*开头的通配符,如“*.example.com”
  • 最长的以*结尾的通配符,如“mail.*”
  • 首先匹配的正则表达式(按在配置文件中出现的顺序)

server_name_in_redirect

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

开启或禁用在server_name指令中定义的主要服务器名称的重定向功能。当主要服务器名称禁用了,请求头域中的“Host”将被使用。如果当前没有这个域,会使用服务器的IP。

server_names_hash_bucket_size

语法:server_names_hash_bucket_size size
默认:server_names_hash_bucket_size 32|64|128
上下文: http

设置server_name一个bucket的哈希表的大小,默认值依赖于当前处理器的缓存行大小。

server_names_hash_max_size

语法:server_names_hash_max_size size
默认:server_names_hash_max_size 512
上下文:http

设置server_name哈希表最大的大小。

server_tokens

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

开启或关闭在nginx错误页和http响应头的Server域中的版本号。
从1.9.13开始这个值可以通过string变量进行定义,空字符串将禁用Server域的显示。