模块-NGINX学习笔记

基于IP地址的访问控制模块

ngx_http_access_module模块可以限制某些客户端IP地址的访问，针对某些ip的客户端访问进行允许或者禁止。

语法：

    allow address | CIDR | unix: | all;
    deny address | CIDR | unix: | all;
    Default:    —
    Context:    http, server, location, limit_except

示例：

    location / {
        deny  192.168.1.1;
        allow 192.168.1.0/24;
        allow 10.1.1.0/16;
        allow 2001:0db8::/32;
        deny  all;
    }

在上面的例子中,仅允许网段 10.1.1.0/16 和 192.168.1.0/24中除 192.168.1.1之外的ip访问.匹配规则被依次进行检验直到第一个匹配的规则为止，后续匹配规则无效。建议把同类型的规则范围小的放前面，范围大的放后面，不同类型的访问频繁的放在上面。

基于用户的访问控制模块

语法：

    auth_basic string | off; (Default:  auth_basic off;) //指定用户登录提示语，默认关闭
    auth_basic_user_file file; (Default:    —) //指定验证文件路径
    Context:    http, server, location, limit_except

示例：

location / {
    auth_basic           "closed site"; //添加用户登录提示语"close site"
    auth_basic_user_file /etc/conf/htpasswd; //指定验证文件为/etc/conf/htpasswd
    }

输出nginx的基本状态模块

ngx_http_stub_status_module模块提供对基本状态信息的访问。

语法：

Syntax: stub_status;
Default:    —
Context:    server, location

示例：

location /basic_status {
    stub_status;
}

结果：

This configuration creates a simple web page with basic status data which may look like as follows:
Active connections: 291 
server accepts handled requests
 16630948 16630948 31070465 
Reading: 6 Writing: 179 Waiting: 106 

Active connections: 活动状态的连接数；

accepts：已经接受的客户端请求的总数；

handled：已经处理完成的客户端请求的总数；

requests：客户端发来的总的请求数；

Reading：处于读取客户端请求报文首部的连接的连接数；

Writing：处于向客户端发送响应报文过程中的连接数；

Waiting：处于等待客户端发出请求的空闲连接数；

现在使用nginx服务器地址加上basic_status就可以查看nginx的基本状态信息。

nginx记录日志模块

ngx_http_log_module模块中指定的格式写入请求的日志。

语法：

log_format //日志格式

Syntax: log_format name [escape=default|json] string ...;
Default:    
log_format combined "...";
Context:    http
string可以使用nginx核心模块及其它模块内嵌的变量；

access_log //访问日志

Syntax: access_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]];
access_log off;
Default:    access_log logs/access.log combined;
Context:    http, server, location, if in location, limit_except

open_log_file_cache //日志缓存

Syntax: open_log_file_cache max=N [inactive=time] [min_uses=N] [valid=time];
open_log_file_cache off;
Default:    open_log_file_cache off; //默认不缓存，禁用
Context:    http, server, location

缓存各日志文件相关的元数据信息；

max：缓存的最大文件描述符数量；

min_uses：在inactive指定的时长内访问大于等于此值方可被当作活动项；

inactive：非活动时长；

valid：验正缓存中各缓存项是否为活动项的时间间隔；

off：禁用；

nginx压缩模块

该ngx_http_gzip_module模块是使用“gzip”方法压缩响应的过滤器。这通常有助于将传输的数据的大小减少一半甚至更多。

gzip on | off; //gzip开关(on为启用，off为禁用)

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

gzip comp_level (level); //指定gzip的压缩等级(低1-9高，压缩等级越高，压缩率越高)

Syntax: gzip_comp_level level;
Default:    
gzip_comp_level 1;
Context:    http, server, location

gzip_buffers number size; //支持实现压缩功能时为其配置的缓冲区数量及每个缓存区的大小；

Syntax: gzip_buffers number size;
Default:    
gzip_buffers 32 4k|16 8k;
Context:    http, server, location

gzip_disable regex ...; //禁止使用与任何指定的正则表达式匹配的“User-Agent”头字段的请求的响应。

Syntax: gzip_disable regex ...;
Default:    —
Context:    http, server, location

gzip_min_length; //启用压缩功能的响应报文大小阈值；

Syntax: gzip_min_length length;
Default:    
gzip_min_length 20;
Context:    http, server, location

gzip_proxied; //nginx作为代理服务器接收到从被代理服务器发送的响应报文后，在何种条件下启用压缩功能的；

Syntax: gzip_proxied off | expired | no-cache | no-store | private | no_last_modified | no_etag | auth | any ...;
Default:    
gzip_proxied off;
Context:    http, server, location

选项参数：
off：对代理的请求不启用压缩

no-cache, no-store，private：表示从被代理服务器收到的响应报文首部的Cache-Control的值为此三者中任何一个，则启用压缩功能；

no_last_modified：如果响应头不包括“Last-Modified”字段，则启用压缩;

no_etag：如果响应头不包括“ETag”字段，则启用压缩;

auth：如果请求头包含“授权”字段，则启用压缩;

any：启用所有代理请求的压缩。

gzip_types mime-type ...; //压缩过滤器，仅对此处设定的MIME类型的内容启用压缩功能；

Syntax: gzip_types mime-type ...;
Default:    
gzip_types text/html;
Context:    http, server, location

Nginx-SSL模块

语法：
ssl on | off; //启用或者禁用虚拟主机的ssl功能。

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

ssl_certificate file; //指定当前虚拟主机使用PEM格式的证书文件；

ssl_certificate_key file; //指定当前虚拟主机上与其证书匹配的私钥文件；

Syntax: ssl_certificate file;
Default:    —
Context:    http, server

ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]; //支持ssl协议版本

Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:    http, server

ssl_session_cache off | none | [builtin[:size]][shared:name:size];//ssl会话缓存

Syntax: ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default:    ssl_session_cache none;
Context:    http, server
builtin[:size]：使用OpenSSL内建的缓存，此缓存为每worker进程私有；
[shared:name:size]：在各worker之间使用一个共享的缓存；

ssl_session_timeout time; //客户端一侧的连接可以复用ssl session cache中缓存的ssl参数的有效时长；

Syntax: ssl_session_timeout time;
Default:    ssl_session_timeout 5m;
Context:    http, server

示例：

    server {
listen 443 ssl;
server_name www.magedu.com;
root /vhosts/ssl/htdocs;
ssl on;
ssl_certificate /etc/nginx/ssl/nginx.crt;
ssl_certificate_key /etc/nginx/ssl/nginx.key;
ssl_session_cache shared:sslcache:20m;
    }

nginx-uri重写模块

将用户请求的URI基于regex所描述的模式进行检查，而后完成替换；

1、rewrite //将用户请求的URI基于regex所描述的模式进行检查，匹配到时将其替换为replacement指定的新的URI；

Syntax: rewrite regex replacement [flag];
Default:    —
Context:    server, location, if

注意：如果在同一级配置块中存在多个rewrite规则，那么会自下而下逐个检查；被某条件规则替换完成后，会重新一轮的替换检查，因此，隐含有循环机制；[flag]所表示的标志位用于控制此循环机制；

如果replacement是以http://或https://开头，则替换结果会直接以重向返回给客户端；
301：永久重定向；
[flag]：
last：重写完成后停止对当前URI在当前location中后续的其它重写操作，而后对新的URI启动新一轮重写检查；提前重启新一轮循环；

break：重写完成后停止对当前URI在当前location中后续的其它重写操作，而后直接跳转至重写规则配置块之后的其它配置；结束循环；

redirect：重写完成后以临时重定向方式直接返回重写后生成的新URI给客户端，由客户端重新发起请求；不能以http://或https://开头；

permanent:重写完成后以永久重定向方式直接返回重写后生成的新URI给客户端，由客户端重新发起请求；

2、return //停止处理并返回指定code给客户端。非标准代码444则关闭连接而不发送响应头。

Syntax: return code [text]; return code URL; return URL;
Default:    —
Context:    server, location, if

3、 rewrite_log on | off; //是否开启重写日志，默认关闭；

4、 if (condition) { ... } //引入一个新的配置上下文 ；条件满足时，执行配置块中的配置指令；server, location；

Syntax: if (condition) { ... }
Default:    —
Context:    server, location

condition：
比较操作符

==： 等于

!=： 不等于

~： 模式匹配，区分字符大小写；

~*： 模式匹配，不区分字符大小写；

!~： 模式不匹配，区分字符大小写；

!~*： 模式不匹配，不区分字符大小写；

文件及目录存在性判断

用“ -f”和“ !-f”操作符检查文件存在;

使用“ -d”和“ !-d”操作符检查目录存在;

使用“ -e”和“ !-e”操作符检查文件，目录或符号链接存在;

使用“ -x”和“ !-x”运算符检查可执行文件。

5、set $variable value; //用户自定义变量；

Nginx引用控制模块

该ngx_http_referer_module模块用于在“引用者”标题字段中阻止对具有无效值的请求的站点访问。

valid_referers none //定义referer首部的合法可用值

Syntax: valid_referers none | blocked | server_names | string ...;
Default:    —
Context:    server, location

none：请求报文首部没有referer首部；

blocked：请求报文的referer首部没有值；

server_names：参数，其可以有值作为主机名或主机名模式；

arbitrary_string：直接字符串，但可使用*作通配符；

regular expression：被指定的正则表达式模式匹配到的字符串；要使用~打头，例如 ~.*.magedu.com；

配置示例：

valid_referers none blocked server_names
    *.example.com example.* www.example.org/galleries/
     ~\.google\.;
if ($invalid_referer) {
    return 403;
}

Nginx-http-proxy模块

ngx_http_proxy_module模块允许将请求传递给另一个服务器。

1、proxy_pass

设置代理服务器的协议和地址以及应映射位置的可选URI。作为协议，可以指定“ http”或“ https”。地址可以指定为域名或IP地址，也可以指定为可选端口。

注意：proxy_pass后面的路径不带uri时，其会将location的uri传递给后端主机；

Syntax: proxy_pass URL;
Default:    —
Context:    location, if in location, limit_except
proxy_pass http：// localhost：8000 / uri /;
    server {
...
server_name HOSTNAME;
location /uri/ {
proxy http://hos[:port];
}
...
    }
    http://HOSTNAME/uri --> http://host/uri 

proxy_pass后面的路径是一个uri时，其会将location的uri替换为proxy_pass的uri；

    server {
...
server_name HOSTNAME;
location /uri/ {
proxy http://host/new_uri/;
}
...
    }
    
    http://HOSTNAME/uri/ --> http://host/new_uri/

如果location定义其uri时使用了正则表达式的模式，或在if语句或limt_execept中使用proxy_pass指令，则proxy_pass之后必须不能使用uri; 用户请求时传递的uri将直接附加代理到的服务的之后；

    server {
...
server_name HOSTNAME;
location ~|~* /uri/ {
proxy http://host;
}
...
    }
    
    http://HOSTNAME/uri/ --> http://host/uri/；

2、proxy_set_header field value; //设定发往后端主机的请求报文的请求首部的值；

Syntax: proxy_set_header field value;
Default:    proxy_set_header Host $proxy_host; proxy_set_header Connection close;
Context:    http, server, location
proxy_set_header X-Real-IP  $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

3、proxy_cache_path //定义可用于proxy功能的缓存；

Syntax: proxy_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default:    —
Context:    http

4、proxy_cache zone | off; //指明要调用的缓存，或关闭缓存机制；

Syntax: proxy_cache zone | off;
Default:    
proxy_cache off;
Context:    http, server, location

5、 proxy_cache_key string; //缓存中用于“键”的内容；

Syntax: proxy_cache_key string;
Default:    
proxy_cache_key $scheme$proxy_host$request_uri;
Context:    http, server, location

6、proxy_cache_valid [code ...] time; //定义对特定响应码的响应内容的缓存时长;
定义在http{...}中；
proxy_cache_path /var/cache/nginx/proxy_cache levels=1:1:1 keys_zone=pxycache:20m max_size=1g;

定义在需要调用缓存功能的配置段，例如server{...}；
proxy_cache pxycache;
proxy_cache_key $request_uri;
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
7、proxy_cache_use_stale

Syntax: proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | off ...;
Default:    
proxy_cache_use_stale off;
Context:    http, server, location

确定在与代理的服务器进行通信时，哪些情况下可能会使用过时缓存的响应。指令的参数与proxy_next_upstream指令的参数相匹配 。

error如果无法选择处理请求的代理服务器，则 该参数还允许使用陈旧的缓存响应。

此外，updating如果当前正在更新，该参数允许使用陈旧的缓存响应。这样可以最大限度地减少更新缓存数据时对代理服务器的访问次数。
8、proxy_cache_methods GET | HEAD | POST ...; //缓存指定的请求方法

Syntax: proxy_cache_methods GET | HEAD | POST ...;
Default:    
proxy_cache_methods GET HEAD;
Context:    http, server, location

如果客户端请求方法在此指令中列出，则响应将被缓存。“ GET”和“ HEAD”方法总是添加到列表中，尽管建议明确指定它们。另请参阅proxy_no_cache指令。

9、proxy_hide_header field;
默认情况下，nginx不会将代理服务器的响应中的头字段“Date”，“Server”，“X-Pad”和“X-Accel -...”传递给客户端。该proxy_hide_header指令设置不会传递的其他字段。如果恰恰相反，需要允许字段的传递，那么可以使用proxy_pass_header指令。

10、proxy_connect_timeout time; //定义与代理服务器建立连接的超时时间

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

定义与代理服务器建立连接的超时时间。应该注意的是，这个超时通常不能超过75秒。
11、proxy_read_timeout time; //定义从代理服务器读取响应的超时

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

定义从代理服务器读取响应的超时。超时仅在两个连续读操作之间设置，而不是传输整个响应。如果代理的服务器在此时间内没有传输任何内容，则连接被关闭。

12、proxy_send_timeout time; //设置代理服务器发送请求的超时时间。

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

设置将代理服务器发送请求的超时。超时仅在两个连续的写入操作之间设置，而不是传输整个请求。如果代理服务器在此时间内没有收到任何内容，则连接将关闭。

Nginx-http头部信息模块

ngx_http_headers_module模块允许向由代理服务器响应给客户端的响应报文添加自定义首部，或修改指定首部的值；

1、add_header name value [always]; //添加自定义首部；

add_header X-Via  $server_addr;
add_header X-Accel $server_name;

2、expires [modified] time; //用于定义Expire或Cache-Control首部的值；

Syntax: expires [modified] time;
expires epoch | max | off;
Default:    
expires off;
Context:    http, server, location, if in location

只要响应代码等于200,201,204,206,301,302,303,304,307或308，则启用或禁用添加或修改“过期”和“缓存控制”响应头字段。参数可以是积极或消极的时间。

“Expires”字段中的时间计算为当前时间和time指令中指定的总和。如果使用modified参数（0.7.0,0.6.32），则将该时间计算为文件修改时间与time指令中指定的时间之和。

另外，可以使用“ @”前缀指定一天的时间：

expires@ 15h30m;

该epoch参数对应于绝对时间“ Thu, 01 Jan 1970 00:00:01 GMT”。“缓存控制”字段的内容取决于指定时间的符号：

时间为负 - “缓存控制：无缓存”。

时间为正或零 - “Cache-Control：max-age = t”，其中t是指令指定的时间，以秒为单位。

该max参数设置“过期”值“ Thu, 31 Dec 2037 23:55:55 GMT”，和“缓存控制”到10年。

该off参数禁止添加或修改“Expires”和“Cache-Control”响应头域。

ngx_http_fastcgi_module模块

允许对fastcgi服务器的请求通过
The ngx_http_fastcgi_module module allows passing requests to a FastCGI server.

1、fastcgi_pass address; //指定fastcgi的服务器地址，地址可以是IP、域名和端口

Context:location, if in location；

2、fastcgi_index name; //fastcgi默认的主页资源;

3、fastcgi_param parameter value [if_not_empty]; //设置一个参数，该参数应该传递给FastCGI服务器。该值可以包含文本、变量和它们的组合，参数值应该非空。
通过/pm_status和/ping来获取fpm server状态信息；

    location ~* ^/(pm_status|ping)$ {
        include        fastcgi_params;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_param  SCRIPT_FILENAME  $fastcgi_script_name;
    }

4、fastcgi_cache_path //定义fastcgi的缓存；缓存位置为磁盘上的文件系统，由path所指定路径来定义；

Syntax: fastcgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default:    —
Context:    http

设置缓存的路径和其他参数。缓存数据存储在文件中。缓存中的密钥和文件名都是将MD5功能应用于代理URL的结果。该levels参数定义缓存的层次级别：从1到3，每个级别接受值1或2.例如，在以下配置中

fastcgi_cache_path / data / nginx / cache levels = 1：2 keys_zone = one：10m;
缓存中的文件名将如下所示：

/ data / nginx / cache / c / 29 / b7f54b2df7773722d382f4809d650 29c
缓存的响应首先写入临时文件，然后重新命名该文件。
(1)levels=levels：缓存目录的层级数量，以及每一级的目录数量；

leves=1:2:2(levels=一级:二级:三级) //一级1个字符，二级2个字符，三级2个字符

(2)keys_zone=name:size // k/v映射的内存空间的名称及大小

(3)inactive=time //非活动时长

(4)max_size=size //磁盘上用于缓存数据的缓存空间上限

5、fastcgi_cache zone | off; //调用指定的缓存空间来缓存数据；http, server, location

6、fastcgi_cache_key string; //定义用作缓存项的key的字符串；

7、fastcgi_cache_methods GET | HEAD | POST ...; //为哪些请求方法使用缓存；

8、fastcgi_cache_min_uses number; //缓存空间中的缓存项在inactive定义的非活动时间内至少要被访问到此处所指定的次数方可被认作活动项；

9、fastcgi_cache_valid [code ...] time; //不同的响应码各自的缓存时长；
示例：

http {
...
fastcgi_cache_path /var/cache/nginx/fastcgi_cache levels=1:2:1 keys_zone=fcgi:20m inactive=120s;
...
server {
    ...
    location ~* \.php$ {
        ...
        fastcgi_cache fcgi;
        fastcgi_cache_key $request_uri;
        fastcgi_cache_valid 200 302 10m;
        fastcgi_cache_valid 301 1h;
        fastcgi_cache_valid any 1m; 
        ...
    }
    ...
}
...
        }

10、fastcgi_keep_conn on | off;

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

默认情况下，FastCGI服务器将在发送响应后立即关闭连接。但是，当该指令设置为该值时on，nginx将指示FastCGI服务器保持连接处于打开状态。这是必要的，特别是与FastCGI服务器的Keepalive连接功能。

ngx_http_upstream_module模块

该ngx_http_upstream_module模块用于定义可由proxy_pass， fastcgi_pass， uwsgi_pass， scgi_pass和 memcached_pa​​ss指令引用的服务器组，默认调度方式为wrr。
(1) upstream name { ... } //定义后端服务器组；引入一个新的上下文；只能用于http{}上下文中；

(2) server address [parameters];
定义服务器地址和相关的参数；
地址格式：IP[:PORT]、HOSTNAME[:PORT]、unix:/PATH/TO/SOME_SOCK_FILE
参数：
weight=number //权重，默认为1；

max_fails=number //失败尝试的最大次数；

fail_timeout=time //设置服务器为不可用状态的超时时长；

backup //把服务器标记为“备用”状态； 

down //手动标记其为不可用；

(3) least_conn; //最少连接调度算法； 当server拥有不同的权重时为wlc；当所有后端主机的连接数相同时，则使用wrr进行调度；

(4) ip_hash; //源地址hash算法；能够将来自同一个源IP地址的请求始终发往同一个upstream server；

(5) hash key [consistent]; //基于指定的key的hash表实现请求调度，此处的key可以文本、变量或二者的组合；

consistent：参数，指定使用一致性hash算法；

示例：

    hash $request_uri consistent //对请求的uri进行一致性hash
    hash $remote_addr //对远程主机(客户端主机)进行hash
    hash $cookie_name //对cookie名进行hash

(6) keepalive connections; //可使用长连接的连接数量；每worker与后端服务保持的最大空闲长连接数量；

四层代理和负载均衡模块

模拟反代基于tcp或udp的服务连接，即工作于传输层的反代或调度器；

listen address:port //监听的端口

Syntax: listen address:port [ssl] [udp] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Default:    —
Context:    server

默认为tcp协议；udp: 监听udp协议的端口；

Nginx代理模块

ngx_stream_proxy_module

ngx_stream_proxy_module模块(1.9.0)允许通过TCP、UDP(1.9.13)和unix域套接字来代理数据流。

(1) proxy_pass address; //设置一个代理服务器的地址。该地址可以指定为一个域名或IP地址，一个端口或一个unix域的套接字路径。

(2) proxy_timeout timeout; //代理服务响应超时时间，默认为10m;在客户端或代理服务器连接上设置两个连续读或写操作之间的超时。如果在这个时间内没有传输数据，那么连接就关闭了。

(3) proxy_connect_timeout time; //定义与代理服务器建立连接的超时时间。设置nginx与被代理的服务器尝试建立连接的超时时长；默认为60s；

示例：

    stream {
        upstream sshsrvs {
            server 192.168.10.130:22;
            server 192.168.10.131:22;
            hash $remote_addr consistent;
        }

        server {
            listen 172.16.100.6:22202;
            proxy_pass sshsrvs; 
            proxy_timeout 60s;
            proxy_connect_timeout 10s;
        }
    }