标签： 官方文档

Nginx中文文档-ngx_http_core_module(L)

本文档包含以下指令：large_client_header_buffers、limit_except、limit_rate、limit_rate_after、lingering_close、lingering_time、lingering_timeout、listen、location、log_not_found、log_subrequest

large_client_header_buffers

语法：large_client_header_buffers number size;
默认：large_client_header_buffers 4 8k;
上下文：http, server

设置读取大请求头最大的缓存数和缓冲区大小。一个请求不能超过缓冲区，否则会返回414状态码（请求URI过长）。一个请求头域也不能超过一个缓冲区的大小，否则会返回400状态码。缓冲区只有在需要的时候才会被分配。默认情况下，缓冲区大小为8K。如果请求处理完成后进入了keep-alive状态，缓冲区会被释放。

limit_except

语法：limit_except method … { … }
默认：–
上下文：location

限制一个location中允许的HTTP方法。method参数可以是以下之一：GET、HEAD、POST、PUT、DELETE、MKCOL、COPY、MOVE、OPTIONS、PROPFIND、PROPPATCH、LOCK、UNLOCK及PATCH。允许GET方式会同时允许HEAD方法。其他的可以通过ngx_http_acces_module及ngx_http_auth_basic_module指令访问：

limit_except GET {
    allow 192.168.1.0/32;
    deny  all;
}

请注意，这将限制除了GET和HEAD方法之外的所有请求。

limit_rate

语法：limit_rate rate;
默认：limit_rate 0;
上下文：http, server, location, if in location

限制响应数据传输速率。rate定义了每秒的字节数。0值表示不限制速度。限制针对于一个请求，如果客户端同时打开2个连接，整体速度会是设置值的2倍。
速度限制也可以在$limit_rate变量中设置。一般用于在特定情况下进行不同限速：

server {

    if ($slow) {
        set $limit_rate 4k;
    }

    ...
}

限速还可以在代理服务器的响应头的X-Accel-Limit-Rate中设置。该功能可以使用proxy_ignore_headers、fastcig_ignore_headers、uwsgi_ignore_headers和scgi_ignore_headers指令中禁用。

limit_rate_after

语法：limit_rate_after size;
默认：limit_rate_after 0;
上下文：http, server, location, if in location
版本：0.8.0+

设置初始值，响应传输的数据量超过这个初始值后，就会进行限速。
例子：

location /flv/ {
    flv;
    limit_rate_after 500k;
    limit_rate       50k;
}

lingering_close

语法：lingering_close off | on | always;
默认：lingering_close on;
上下文：http, server, location
版本：1.1.0,1.0.6

控制nginx如何关闭客户端连接。
默认值on通知nginx在完全关闭连接前等待并处理额外的数据，如果客户端仍然在传输数据。
always值会使nginx无条件的等待和处理客户端的额外数据。
off值告诉nginx不要等待更多的数据，立即关闭连接。这种行为破坏了协议，不应该在正式的环境中使用。

lingering_time

语法：lingering_time time;
默认：lingering_time 30s;
上下文： http, server, location

当lingering_close生效时，定义了nginx最长处理额外数据的时间。超过这个时间，连接就会被关闭，即使还有更多的数据。

lingering_timeout

语法：lingering_timeout time;
默认：lingering_timeout 5s;
上下文：http, server, location

当lingering_close生效时，该指令定义了等待客户端传输更多数据的最大等待时间。如果这个期间内没有数据接收到，连接将被关闭。否则nginx继续接收处理数据。“等待-读取-忽略”循环将会重复，不会比lingering_time指令中定义的长。

listen

语法：listen address[:port] [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];

listen port [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];

listen unix:path [default_server] [ssl] [http2 | spdy] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
默认：listen *:80 | *:8000;
上下文：server

设置接受请求的IP的地址和端口，或UNIX域的socket路径。可以同时指定address和port也可以只指定port或只指定address。地址可以是一个主机名，举个例子：

listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;

IPv6地址（0.7.36版本起）需要在方括号中指定：

listen [::]:8000;
listen [::1];

UNIX socket（0.8.21版本起）定义以unix:开头：
listen unix:/var/run/nginx.sock;
如果只设置了address，会使用80端口。
如果当前指令不存在，80被占用，nginx使用超级用户权限运行，则使用8000端口。
如果存在default_server参数，这个server会成为默认的server。如果所有的指令中都没有定义default_server参数，则第一个会成为默认的。
在0.8.21之前这个参数叫做default
ssl参数（0.7.14版本起）允许定义所有该端口的连接只会接收SSL模式的。这可以使服务器同时处理HTTP和HTTPS请求的配置更简洁。
http2参数（1.9.5版本起）配置了允许HTTP2连接的端口。一般地，这个参数与ssl一同定义，但nginx可以不配置SSL单独接受HTTP2请求。（译者注：目前所有浏览器只支持SSL的http2协议）
spdy参数（1.3.15版本-1.9.4版本）允许本端口接收SPDY连接。一般会同时定义ssl参数，但nginx支持不使用SSL只开启SPDY。（译者注：建议改用HTTP2）
proxy_protocol参数（1.5.12版本起）允许所有通过到本端口的连接使用PROXY协议。
listen指令可以有很多附加的参数定义socket相关的系统调用。这些参数可以定义在任何一个listen指令中，但只能有一个地址端口对。
0.8.21前，只能在listen指令中有default参数时定义。
setfib=number
该参数（0.8.44版本起）为监听的socket设置了相关的路由表、FIB（SO_SETFIB选项）。目前只在FreeBSD系统中可用。
fastopen=number
为监听的socket开启TCP快速开启功能（1.5.8版本起），并限制了未完成三次握手的连接队列的最大长度。
不要开启这个功能，除非服务器可以处理超过一次收到相同的SYN数据包。
backlog=number
设置等待连接队列的最大长度。默认情况下，该参数在FreeBSD、DragonFly BSD及Mac OS X系统中为-1，其他系统中是511。
rcvbuf=size
设置socket接收缓冲区（SO_RCVBUF选项）大小。
sndbuf=size
设置socket发送缓冲区（SO_SNDBUF选项）大小。
accept_filter=filter
设置socket可接受的过滤器（SO_ACCEPTFILTER选项）名称，过滤器是在连接进入传给accept函数前工作。只有FreeBSD和NetBSD 5.0以上版本系统可以使用。可能的值是dataready和httpready。
deferred
在Linux系统上使用延迟接受函数（TCP_DEFER_ACCEPT选项）。
bind
为地址端口对分开调用bind函数。这个是很有用的，尤其是在多个listen指令用相同的端口但不同的地址，并且有一个listen指令监听所有地址的指定端口，nginx将会绑定*:port。需要注意的是，getsockname函数的系统调用决定了接受连接的地址。如果setfib、backlog、rcvbuf、sndbuf、accept_filter、deferred、ipv6only或so_keepalive参数使用了，则给定的地址端口对总会被分离调用bind函数。
ipv6only=on|off
该参数（0.7.42版本起）定义了（通过IPV6_V6ONLY socket选项）在通配符地址[::]是只接受IPv6连接还是IPv6和IPv4都支持。该参数默认是打开的。只能在启动时设置一次。
在1.3.4之前版本中，如果该参数没有给出，则操作系统的设置将影响socket连接。
reuseport
该参数（1.9.1版本起）指定了为每一个工作进程创建单独的socket监听（通过SO_REUSERPORT选项），允许内核将连接分配到不同的工作进程中。目前只在Linux 3.9以上版本及DragonFly BSD系统上可用。
错误的使用这个选项会有安全问题。
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
该参数（1.1.11版本起）配置了socket的“TCP keepalive”行为。如果该参数没有定义，则操作系统会影响socket的设置。如果开启了此功能，SO_KEEPALIVE选项将开启，否则将关闭。一些系统允许设置每一个socket的TCP的keepalive参数，通过TCP_KEEPIDLE、TCP_KEEPINTVL和TCP_KEEPCNT选项。在这些系统中（目前是Linux2.4以上、NetBSD 5以上以及FreeBSD 9.0稳定版），可以通过keepidle、keepintvl及keepcnt参数设置。如果忽略了1个或2个参数，系统默认值将影响socket的设置。例如，
so_keepalive=30m::10
将会设置空闲超时30分钟，探测间隔由系统默认值指定，探测数设为10。
例子：
listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

location

语法：location [ = | ~ | ~* | ^~ ] uri { … }
location @name { … }
默认：–
上下文：server, location

设置一个请求URI的配置项。
匹配是对一个标准URI经过解码，处理相对路径并且压缩2个或两个以上连续的斜杠为1个斜杠后的URI。
location可以由一个字符串前缀或正则表达式定义。正则表达式由“~*”（不区分大小写），或“~”（区分大小写）定义。为了检查location是否匹配请求，nginx首先检测定义的前缀字符串。其中，前缀字符串匹配最长的前缀会被选中并被记录。然后会检测正则表达式，按照出现在配置文件中的顺序进行检测。正则表达式搜索将会在第一次匹配成功后停止，相应的配置将被使用。如果没有找到正则表达式匹配的，就会在使用之前记录下来的前缀字符串。
location块可以被嵌套，有下面的几个例外。
在大小写不敏感的操作系统（如Mac OS X和Cygwin上），前缀字符串忽略大小写（0.7.7版本起）。匹配限制于一字节场景。
正则表达式可以包含捕获（0.7.40版本起），可以在其他的指令中使用。
如果最长的前缀匹配location，该location有“^~”修饰，正则表达式不会被检查。
同样，使用“=”修饰符，location会精确匹配URI。如果精确匹配到，则匹配将停止。例如，如果“/”频繁的请求，定义“location = /”会加快处理这些请求，因为匹配过程之后进行一次，就会停止。这种location显然不能包含内嵌location。
在0.7.1到0.8.41版本中，如果一个请求匹配的location前缀没有“=”和“^~”修饰符，搜索仍会终止，正则表达式不会被检测。
用几个例子来说明解释下：

location = / {
    [ configuration A ]
}

location / {
    [ configuration B ]
}

location /documents/ {
    [ configuration C ]
}

location ^~ /images/ {
    [ configuration D ]
}

location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

“/”请求将匹配配置A，“/index.html”请求将匹配配置B，“/documents/document.html”将匹配配置C，“/images/1.gif”请求将匹配配置D，“/document/1.jpg”请求将匹配配置E。
“@”前缀定义了一个命名的location。这种location并不会应用于任何请求的处理，而是用于请求的重定向。它们不能被嵌套，也不能包括嵌套的location。
如果location由一个以斜杠结束的前缀字符串定义，请求被proxy_pass、fastcgi_pass、uwsgi_pass、scgi_pass或memcached_pass之一处理，特殊处理程序将运行。在响应URI等于这些字符串但并没有末尾的斜杠时，将会返回301状态码，重定向到带斜线的URI。如果不希望这样，需要定义一个精确匹配的location如下：

location /user/ {
    proxy_pass http://user.example.com;
}
location = /user {
    proxy_pass http://login.example.com;
}

log_not_found

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

启用或禁用记录找不到文件错误到错误日志中的功能。

log_subrequest

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

开启或关闭记录子请求到访问日志的功能。

Nginx中文文档-ngx_http_core_module(I-K)

本文档包含以下指令：if_modified_since、ignore_invalid_headers、internal、keepalive_disable、keepalive_requests、keepalive_timeout

if_modified_since

语法：if_modified_since off | exact | before;
默认：if_modified_since exact;
上下文： http, server, location
版本：0.7.24+

定义如何比较请求头中的“If-Modified-Since”时间：
off
忽略“If-Modified-Since”请求头（0.7.34版本起）
exact
精确匹配
before
响应的修改时间小于或等于请求头中的“If-Modified-Since”值

ignore_invalid_headers

语法：ignore_invalid_headers on | off;
默认：ignore_invalid_headers on;
上下文：http, server

控制头域中无效的名字是否需要被忽略。正确的名字是由英文字母、数字、连字符及可能的下划线（在underscores_in_headers指令中控制）组成。
当这个指令在server的上下文中定义，只有在server是一个默认的设置时才有效。指定的值同样对监听了相同的端口和地址的虚拟主机有效。

internal

语法：internal;
默认：–
上下文：location

定义指定的location只能被用于内部请求。对于外部的请求，会返回404错误码。内部请求有下面的这些:

  • 通过error_page、index、random_index和try_files指令重定向的请求
  • 根据上游服务器响应头中的“X-Accel-Redirect”进行重定向的请求
  • 通过ngx_http_ssi_module模块的“include virtual”命令及ngx_http_addition_module模块指令提交的子请求
  • 通过rewrite指令修改的请求

例子：

error_page 404 /404.html;

location /404.html {
    internal;
}

为了防止错误的配置导致循环重定向，每个请求的内部重定向限制在10次。如果达到了限制，会返回500错误码。这种情况下，可以在错误日志中看到“rewrite or internal redirection cycle”。

keepalive_disable

语法：keepalive_disable none | browser …;
默认：keepalive_disable msie6;
上下文：http, server, location

对非正常行为的浏览器禁用keep-alive连接。browser参数指定了哪些浏览器会被影响。msie6禁用了老版本的IE在收到post请求的keep-alive连接。safari值禁用了在Mac OS X及类Mac OS X操作系统上的Safari和类Safari浏览器的keep-alive连接。none值允许所有浏览器保持连接。
在1.1.18前，safari匹配所有操作系统上的Safari和类Safari浏览器，默认情况下禁用keep-alive。

keepalive_requests

语法：keepalive_requests number;
默认：keepalive_requests 100;
上下文：http, server, location
版本：0.8.0+

设置一个连接中最大的请求数。超过请求数最大值，连接将被关闭。

keepalive_timeout

语法：keepalive_timeout timeout [header_timeout];
默认：keepalive_timeout 75s;
上下文：http, server, location

第一个参数定义了客户端发起连接在服务端保持开启的超时时间。0值表示禁用客户端发起的连接的保持。第二个可选参数设置了响应头中“Keep-Alive: timeout=time” 的值。两个参数可能不同。
“Keep-Alive: timeout=time”头会被Mozilla和Konqueror浏览器识别，IE会在60秒后自动关闭连接。