nginx核心模块 ngx_http_core_module

2018-07-16 09:04:47

该模块是nginx的最基本的模块,在所有模块里编号为0,至关重要。

listen

Syntax:
    listen address...
    listen port...
    listen unix:path...
Default:	
    listen *:80;    超级用户
    listen *:8000;  普通用户
Context:	server

既可以监听 tcp,也可以监听 unix domain。

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

#ipv6
listen [::]:8000;
listen [::1];

#unix domain
listen unix:/var/run/nginx.sock;

部分参数解释如下

ssl  ssl加密模式。
http2  基于http/2协议,一般配合ssl。
spdy  基于spdy协议,一般配合ssl
proxy_protocol  所有连接必须使用代理,1.13.11开始支持版本2代理

backlog=n  等待被accept的队列
rcvbuf=size  接收缓冲大小
sndbuf=size  发送缓冲大小

reuseport  nginx 1.9.1+,linux 3.9+,该选项可以让多个进程监听同一个端口而不会出现惊群现象,内核帮助我们完成负载均衡。

location

根据请求的uri来匹配,匹配总共分为3种,按照顺序

1.准确匹配(=):如果命中,直接成功,不命中,开始前缀匹配。
2.前缀匹配:匹配到了,会记住最长的那个待后续使用。
3.非正则前缀匹配:^~ 如果匹配到了,而且是最长的,直接成功。
4.正则匹配:~(区分大小写),~*(不区分大小写),如果1,3不命中,到正则匹配,匹配到了直接完成,匹配不到就会去找2里面最长的那个。

#准确匹配
location = / {
    [ configuration A ]
}

#前缀匹配
location / {
    [ configuration B ]
}

#前缀匹配
location /documents/ {
    [ configuration C ]
}

#非正则前缀匹配
location ^~ /images/ {
    [ configuration D ]
}

#不区分大小写
location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

#区分大小写
location ~ \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

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

internal

Syntax:	internal;
Default: —
Context: location

标记location只能被内部访问。

error_page 404 /404.html;

location /404.html {
    internal;
}

root

Syntax:	root path;
Default: root html;
Context: http, server, location, if in location

设置请求的根目录,支持变量

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

如果请求 /i/top.gif,那么会去找 /data/w3/i/top.gif。

alias

Syntax:	alias path;
Default: —
Context: location

设置别名来替换 location 上指定的路径。

#如果请求 /i/top.gif,那么会去找 /data/w3/images/top.gif。
location /i/ {
    alias /data/w3/images/;
}

#如果是正则,则必须要有捕获
location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
    alias /data/w3/images/$1;
}

sendfile

Syntax:	sendfile on | off;
Default: sendfile off;
Context: http, server, location, if in location

直接将磁盘数据拷贝到内核缓冲区而不用经过 内核->用户->内核->socket,中间少了近2层拷贝,提高性能。

aio

Syntax:	aio on | off | threads[=pool];
Default: aio off;
Context: http, server, location

异步io,会经过内核缓冲,一般结合 directio 来避免读取阻塞。当然如果开启线程支持(nginx 1.7.11+,并且编译的时候加上--with-threads),可以不配合 directio也能达到非阻塞。

directio

Syntax:	directio size | off;
Default: directio off;
Context: http, server, location

当文件大于 size 时,将启用directio,directio不会经过内核缓冲区,适合服务大文件,因为大文件不适合缓冲来提高缓存命中。如果不配合 aio,会阻塞。

directio_alignment

Syntax:	directio_alignment size;
Default: directio_alignment 512;
Context: http, server, location

设置 directio 内存对齐大小,大多数情况下,512B 就够了,linux下的xfs文件系统最好 4K。

io总结:

一般,上面3个指令一起出现,如下意思是,如果文件大于等于8m,使用非阻塞异步 directio,不缓存文件。如果文件小于 8m,则使用 sendfile,内核会缓冲文件。

location /video/ {
    sendfile       on;
    aio            on;
    directio       8m;
}

当然如果开启多线程支持,也可以如下配置来避免阻塞。

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


client_body_buffer_size

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

设置存取客户端请求体缓冲大小,如果请求体大于此值,那么整个请求体或部分会存入临时文件。一般默认为 8K(2个内存页大小)。

client_body_in_file_only

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

确定是否总将请求体存入临时文件,设置为 on,临时文件不会移除。clean 请求结束后临时文件移除。一般用来调试利用 $request_body_file 变量来获取临时文件名。

 client_body_in_single_buffer

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

如果开启,nginx会保证请求体在不大于 client_body_buffer_size 设置的值时,被存放在一块连续的内存中,但超过该大小时会将整个写入一个临时文件。

client_body_temp_path

Syntax:	client_body_temp_path path [level1 [level2 [level3]]];
Default: client_body_temp_path client_body_temp;
Context: http, server, location

指定临时文件路径,可以指定3级,数字大小代表层级的数字位数。

client_body_temp_path /spool/nginx/client_temp 1 2;

#临时文件就会类似下面
/spool/nginx/client_temp/7/45/00000123457

client_body_timeout 

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

读取请求体超时时间,非传输时间,是读取成功之间的总时间。

client_header_buffer_size

Syntax:	client_header_buffer_size size;
Default: client_header_buffer_size 1k;
Context: http, server

单个请求头或请求行的缓冲大小,如果超过了,那么会根据 large_client_header_buffers 设置的大小重新分配。

large_client_header_buffers 

Syntax:	large_client_header_buffers number size;
Default: large_client_header_buffers 4 8k;
Context: http, server

设置buffer的个数和大小,请求行不能超过1个buffer,如果超过返回 414。一个请求头也不能超过1个buffer大小,超过返回400.

client_header_timeout 

Syntax:	client_header_timeout time;
Default: client_header_timeout 60s;
Context: http, server

请求头读取超时时间,返回408。

client_max_body_size

Syntax:	client_max_body_size size;
Default: client_max_body_size 1m;
Context: http, server, location

设置请求体上限,超过返回413,设为0代表不限制。

default_type 

Syntax:	default_type mime-type;
Default: default_type text/plain;
Context: http, server, location

设置默认的 MIME 类型。根据 types 指令来映射。

disable_symlinks 

Syntax:	disable_symlinks off;
disable_symlinks on | if_not_owner [from=part];
Default: disable_symlinks off;
Context: http, server, location

禁用符号链接,if_not_owner 代表不禁用符号链接和指向的文件是同一个拥有者。

error_page

Syntax:	error_page code ... [=[response]] uri;
Default: —
Context: http, server, location, if in location

设置出错的时候展示页,uri可以是变量。

error_page 404             /404.html;
error_page 500 502 503 504 /50x.html;

#改变错误码并访问,此时状态码变为200
error_page 404 =200 /empty.gif;

#内部跳转到另一个 location
location / {
    error_page 404 = @fallback;
}

location @fallback {
    proxy_pass http://backend;
}

#也可以给客户端发送跳转指令,默认为302
error_page 403      http://example.com/forbidden.html;

#也可以手动指定,但是只限于301-303,307-308
error_page 404 =301 http://example.com/notfound.html;

etag 

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

访问静态资源时响应头是否开始 etag。

http

Syntax:	http { ... }
Default: —
Context: main

代表 http 服务器配置块。

if_modified_since 

Syntax:	if_modified_since off | exact | before;
Default: if_modified_since exact;
Context: http, server, location

off 忽略 if-Modified-Since 请求头总是发送文件。
exact 精确匹配,只有时间相等才算匹配。
before - 文件修改时间只要小于等于if-Modified-Since 就算匹配。

匹配成功会返回304,告诉浏览器应该使用缓存文件。

ignore_invalid_headers 

Syntax:	ignore_invalid_headers on | off;
Default: ignore_invalid_headers on;
Context: http, server

是否忽略无效请求头,有效请求头名称包括 英文字母,数字,连字符-,下划线。

underscores_in_headers 

Syntax:	underscores_in_headers on | off;
Default: underscores_in_headers off;
Context: http, server

如果设置 on,则允许请求头名出现下划线,如果设置为 off,那么认为出现下划线的请求头名是无效的请求头。如果设置 ignore_invalid_headers on; 那么该请求头将会被忽略。

keepalive_requests 

Syntax:	keepalive_requests number;
Default: keepalive_requests 100;
Context: http, server, location

设置一个 keepalive 连接最多服务的请求数,达到这个请求该连接就会关闭。

keepalive_timeout

Syntax:	keepalive_timeout timeout [header_timeout];
Default: keepalive_timeout 75s;
Context: http, server, location

连接超时时间,设置多久没被访问的连接将关闭。

reset_timedout_connection

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

如果开启,如果一个长连接超时要关闭,则会发送 rst tcp包,释放所有占用的资源。可以避免服务端在一个已经关闭的socket上长时间保持 FIN_WAIT1 状态。

limit_except

Syntax:	limit_except method ... { ... }
Default: —
Context: location

method 可以是如下的一种 GET, HEAD, POST, PUT, DELETE, MKCOL, COPY, MOVE, OPTIONS, PROPFIND, PROPPATCH, LOCK, UNLOCK, or PATCH。

下面的访问限制对 get、head不生效。

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

limit_rate 

Syntax:	limit_rate rate;
Default: limit_rate 0;
Context: http, server, location, if in location

设置响应的流量控制,每秒多少字节。也可以通过设置 $limit_rate 变量。

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

也可以在代理响应头里设置 X-Accel-Limit-Rate。

limit_rate_after 

Syntax:	limit_rate_after size;
Default: limit_rate_after 0;
Context: http, server, location, if in location

设置流量控制的初始值,也就是超过这些值才会启动流量控制。下面表示前500k不启动流量控制。

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

lingering_close 

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

用来控制nginx如何关闭连接。详细解释读者可以参考 lingering_close

on - 如果nginx觉得客户端还有额外数据,那么它不会立即关闭连接,而是只关闭写端。
always - 总是等待客户端的额外数据
off - 直接强制关闭,只当测试用,违反了协议。

lingering_time 

Syntax:	lingering_time time;
Default: lingering_time 30s;
Context: http, server, location

读取总时间,超过则关闭。

lingering_timeout 

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

等待超时时间,超过则关闭。


log_not_found 

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

是否记录 文件未找到 错误到 error_log。

log_subrequest 

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

是否记录子请求到 access_log

max_ranges

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

设置范围请求(就是请求文件的部分内容)的上限,如果超过则发送整个文件。默认不限制,0代表禁用 range 请求。

merge_slashes 

Syntax:	merge_slashes on | off;
Default: merge_slashes on;
Context: http, server

合并相邻的多个 / 为一个。

open_file_cache

Syntax:	open_file_cache off;
        open_file_cache max=N [inactive=time];
Default: open_file_cache off;
Context: http, server, location

打开文件缓存配置,读者可以参考 linux 文件io 该缓存可以存储:

1.打开文件描述符,文件大小和修改时间。
2.目录是否存在信息。
3.文件查找错误信息如 "文件未找到" "没有读取权限"。

max  代表最大文件个数,超出了从最旧的开始移除。
inactive  多少时间没有访问则移除,默认为60s。
off  不缓存打开文件信息。

open_file_cache_errors 

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

是否存储文件查询错误信息。

open_file_cache_min_uses 

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

就算 inactive 指定的时间到了,但是如果次数没达到此值,则不移除缓存。

open_file_cache_valid 

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

指定验证缓存有效性的时间,也就是如果超过这个时间,nginx会主动验证缓存的信息跟磁盘上的文件信息是否还是一样,不一样则更新。

open_file_cache          max=1000 inactive=20s;
open_file_cache_valid    30s;
open_file_cache_min_uses 2;
open_file_cache_errors   on;

output_buffers

Syntax:	output_buffers number size;
Default: output_buffers 2 32k;
Context: http, server, location

设置缓冲区的个数和大小来存储从磁盘读取的响应数据。

postpone_output 

Syntax:	postpone_output size;
Default: postpone_output 1460;
Context: http, server, location

如果可以,发送给客户端的响应数据在达到该大小时才会一次性发送。0代表关闭该功能。

resolver 

Syntax:	resolver address ... [valid=time] [ipv6=on|off];
Default: —
Context: http, server, location

解析反向代理 upstream 服务器域名地址。valid 缓存有效时间,默认为TTL。

resolver 114.114.114.114;

resolver_timeout

Syntax:	resolver_timeout time;
Default: resolver_timeout 30s;
Context: http, server, location

解析的超时时间。

satisfy

Syntax:	satisfy all | any;
Default: satisfy all;
Context: http, server, location

all 代表以下全部满足才能访问,any 代表只满足一种即可访问。

ngx_http_access_module, ngx_http_auth_basic_module, ngx_http_auth_request_module, or ngx_http_auth_jwt_module模块指定的控制。

下面代表只要满足一种即可。

location / {
    satisfy any;

    allow 192.168.1.0/32;
    deny  all;

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

send_timeout 

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

发送给客户端响应的内容的超时时间。超过将关闭连接。

server

Syntax:	server { ... }
Default: —
Context: http

虚拟主机配置块。

server_name

Syntax:	server_name name ...;
Default: server_name "";
Context: server

设置虚拟主机名,可以设置多个。

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

支持通配符。

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

上面的前2个可以简写成如下。

server {
    server_name .freecls.com;
}

支持正则,~开头。

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

如果匹配多个,那么按照如下顺序匹配。

1.精确匹配。
2.最长的前通配符匹配,如*.freecls.com。
3.最长的后通配符匹配,如 www.freecls.*
4.正则的第一次成功匹配匹配。

server_tokens 

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

off 在响应头 Server 里不显示nginx版本信息。
build 显示在编译的时候指定的名称(--build=name)+版本号
string 只有商业版才支持,自定义字符串。

tcp_nodelay

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

增加 TCP_NODELAY 选项,只在长连接里生效。另外在 ssl 链接,非缓冲代理,websocket 代理中也能生效。

tcp_nopush

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

在 linux 上设置 TCP_CORK 选项,只在 sendfile 里起作用。作用如下:

1.将响应头和文件的开头在一个包里发送。
2.以整包的形式发送文件。

备注:上面两个选项的详细解析请参考 tcp_nodelay和tcp_nopush

try_files

Syntax:	try_files file ... uri;
        try_files file ... =code;
Default: —
Context: server, location

依次检查文件或目录,在第一个找到满足时就处理请求,如果都不满足,则按照最后一个参数进行内部跳转。

下面是简单的跳转。

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

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

下面是更复杂点例子,假设我们请求的uri为 /freecls/tmp

1.检查 /system/maintenance.html 文件是否存在,存在直接返回
2.检查 /freecls/tmp 文件是否存在,存在直接返回。
3.检查 /freecls/tmp/index.html 文件是否存在,存在直接返回。
4.检查 /freecls/tmp.html 文件是否存在,存在直接返回。

如果以上都不满足,跳转到 location @mongrel

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

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

也可以利用错误码内部跳转

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

    error_page 404 = @mongrel;
    log_not_found off;
}

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

types

Syntax:	types { ... }
Default:	
    types {
        text/html  html;
        image/gif  gif;
        image/jpeg jpg;
    }
Context: http, server, location

指定 MIME 类型映射比如

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

在文件 conf/mime.types 里面已经定义了全部 mime 类型,直接用 include 包含即可使用。下面是 conf/mime.types 部分展示。

types {
    text/html                                        html htm shtml;
    text/css                                         css;
    text/xml                                         xml;
    image/gif                                        gif;
    image/jpeg                                       jpeg jpg;
    application/javascript                           js;
    application/atom+xml                             atom;
    application/rss+xml                              rss;
    ...
}

如果想让某个 location 只返回特定的 mime type。则可以这样写。下面的意思是当请求/download/目录文件时,只当做 application/octet-stream来处理。

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


变量

$arg_name    请求行里的参数名为 name 的值。

$args $query_string    请求行里的所有。

url 为 /index.html?tag=freecls&age=22

$arg_tag 为 freecls
$arg_age 为 22

$args 为 tag=freecls&age=22

$binary_remote_addr    二进制模式的客户端ip地址,ipv4为4字节,ipv6为16字节。

$body_bytes_sent    响应体大小,不包括响应头。

$bytes_sent    响应头+响应体大小。

$connection    连接序列号。

$connection_requests    一个长连接里的请求总数,断开后重新计算。

$content_length  请求头里的 Content-Length。

$content_type  请求头里的 Content-Type。

$cookie_name  cookie里名为name的值,比如$cookie_tag代表名为tag的cookie值。

$uri $document_uri  请求的uri,如果有内部跳转或者是获取默认文件时会变动。

$host 请求头 Host,如果没有则取请求行的host name。

$hostname 系统主机名。

$http_name 获取请求头,要用下划线来代替连字符来查询

$https  如果基于https,则显示 on,否则为空字符串。

$is_args  是否有请求行参数,有则显示 ?,否则为空字符串。

$limit_rate  是否开启了响应限速,默认为0。

$msec  当前的时间戳(s.ms)比如 1531747931.515。

$nginx_version  nginx版本如 1.14.0。

$pid  worker进程的pid。

$pipe  如果请求是基于管道线技术显示 p,否则显示 . 。

$proxy_protocol_addr  代理协议头的客户端地址。

$proxy_protocol_port  代理协议头的客户端端口。

$realpath_root  根据 root、alias算出当前请求的绝对路径,符号链接会被解析。

$remote_addr  客户端地址。

$remote_port  客户端端口。

$remote_user  基础认真的用户名。

$request  原始请求行如

GET /index.html?name=freecls HTTP/1.1

$request_body  请求体,只有在被 proxy_pass、fastcgi_pass、uwsgi_pass、scgi_pass处理时,请求体将会被读进缓冲区,此时才能在此变量获得。

$request_body_file  存请求体的临时文件名。

$request_completion  请求完成为 OK,否则为空字符串。

$request_filename  文件路径,根据 root或alias,和请求uri。

$request_id  唯一的16字节标识符,16进制形式。如 1c2f0f895dd03db84dacc87128e35a81。

$request_length  请求长度,包括请求行,请求头,请求体。

$request_method  请求方法,一般为 GET 或 POST。

$request_time  请求处理时间(s.ms),从第一个字节被读取到结束,如0.000。

$request_uri  全部请求uri,包括参数。

$scheme  如http、https。

$server_addr  接受请求的服务端地址,计算此值需要一次系统调用,除非在 listen 指定地址并使用 bind参数。

$server_name  接受请求的虚拟主机名(server_name)。

$server_port 服务端端口。

$server_protocol  请求协议,一般为 HTTP/1.0、HTTP/1.1、HTTP/2.0。

$status  响应状态。

$time_iso8601  本地时间以 iso 8601格式如 2018-07-16T22:06:47+08:00。

$time_local  本地时间如 16/Jul/2018:22:07:36 +0800。


 备注

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


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