Nginx 配置文件简介-4（Nginx 常用模块）
ngx_http_random_index_module
ngx_http_random_index_module模块处理以斜杠字符（'/'）结尾的请求，并在目录中选择一个随机文件作为索引文件。 在ngx_http_index_module模块之前处理该模块
语法：random_index on | off;
默认值：random_index off;
应用位置：location
案例：
location / {
random_index on;
}
ngx_http_realip_module
ngx_http_realip_module模块用于将客户端地址和可选端口更改为在指定的头字段中发送的端口。 更多详细介绍，猛击这里.
指令详解：
set_real_ip_from
语法：set_real_ip_from address | CIDR | unix:;
默认值：无
应用位置：http, server, location
作用：定义已知可发送正确替换地址的可信地址。 如果指定了特殊值unix：，则所有UNIX域套接字都将受信任。 也可以使用主机名（1.13.1）指定可信地址。
real_ip_header
语法：real_ip_header field | X-Real-IP | X-Forwarded-For | proxy_protocol;
默认值：real_ip_header X-Real-IP;
应用位置：http, server, location
作用：定义请求标头字段，其值将用于替换客户端地址。
real_ip_recursive
语法：real_ip_recursive on | off;
默认值：real_ip_recursive off;
应用位置：http, server, location
作用：当real_ip_recursive为off时，nginx会把real_ip_header指定的HTTP头中的最后一个IP当成真实IP，当real_ip_recursive为on时，nginx会把real_ip_header指定的HTTP头中的最后一个不是信任服务器的IP当成真实IP
综合案例：
set_real_ip_from 192.168.1.0/24; set_real_ip_from 192.168.2.1; real_ip_header X-Forwarded-For; real_ip_recursive on;
ngx_http_referer_module
ngx_http_referer_module模块可根据header中的referer信息屏蔽某些请求对网站或应用的访问，可以起到禁止直接访问网站static files的作用（防盗链或保护文件）
指令详解：
valid_referers
语法：valid_referers none | blocked | server_names | string ...;
默认值：无
应用位置：server, location
作用：valid_referers 代表可信referer，此处可信referer的设置将会使变量$invalid_referer的值为「0」，反之$invalid_referer的值为「1」，则执行IF条件名并返回相关限制结果。更多。
referer_hash_bucket_size
语法：referer_hash_bucket_size size;
默认值：referer_hash_bucket_size 64;
应用位置：server, location
作用：设置有效的参考哈希表大小的桶。
referer_hash_max_size
语法：referer_hash_max_size size;
默认值：referer_hash_max_size 2048;
应用位置：server, location
作用：设置 referer 哈希表的最大大小.
ngx_http_rewrite_module
ngx_http_rewrite_module模块用于使用PCRE正则表达式更改请求URI，返回重定向和有条件地选择配置。
指令详解：
break;
语法：break；
默认值：无
应用位置：server, location, if
作用：停止处理当前的ngx_http_rewrite_module指令集。
if
语法：if (condition) { ... }
默认值：无
应用位置：server, location
作用：评估指定的条件。 如果为true，则执行在大括号内指定的此模块指令，并在if指令内为该请求分配配置。 if指令内的配置继承自先前的配置级别。
案例：
if ($http_user_agent ~ MSIE) {
rewrite ^(.*)$ /msie/$1 break;
}
if ($request_method = POST) {
return 405;
}
if ($invalid_referer) {
return 403;
}
return
语法：return code [text];
return code URL; return URL;
默认值：无
应用位置：server, location, if
作用：停止处理并将指定的代码返回给客户端。
rewrite
语法：rewrite regex replacement [flag];
默认值：无
应用位置：server, location, if
作用：将用户请求的URI基于regex所描述的模式进行检查，匹配到时将其替换为replacement指定的新的URI 可用位置。
flag详解：
break 和 last 都能阻止继续执行后面的 rewrite 指令，但是 last 如果在 location 下用的话，对于重写后的 URI 会重新匹配 location ，但是 break 则不会重新匹配 location 。
last：停止处理当前的ngx_http_rewrite_module指令集，并开始搜索与更改的URI匹配的新位置;
break：与break指令一样，停止处理当前的ngx_http_rewrite_module指令集;
redirect：返回带有302代码的临时重定向;
permanent：返回301代码的永久重定向。;
案例：
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
rewrite_log
语法：rewrite_log on | off;
默认值：rewrite_log off;
应用位置：http, server, location, if
作用：启用或禁用将ngx_http_rewrite_module模块指令处理结果记录到通知级别的error_log中。
set
语法：set $variable value;
默认值：无
应用位置：server, location, if
作用：设置指定变量的值。 该值可以包含文本，变量及其组合。
uninitialized_variable_warn
语法： uninitialized_variable_warn on | off;
默认值：uninitialized_variable_warn on;
应用位置：http, server, location, if
作用：控制是否记录有关未初始化变量的警告。
ngx_http_secure_link_module
ngx_http_secure_link_module模块（0.7.18+）用于检查请求链接的可靠性，保护资源不受未授权的访问，限制链接的有效期,默认没有安装，需要自行添加编译参数安装. 详细1，详细2.
指令详解：
secure_link
语法：secure_link expression;
默认值：无
应用位置：http, server, location
作用：定义一个包含变量的字符串，从中提取链接的校验和值和生命周期。
secure_link_md5
语法：secure_link_md5 expression;
默认值：无
应用位置： http, server, location
作用：定义将为其计算MD5哈希值并与请求中传递的值进行比较的表达式。
secure_link_secret
语法：secure_link_secret word;
默认值：无
应用位置：location
作用：定义用于检查所请求链接的真实性的密码。
综合案例
location /s/ {
secure_link $arg_md5,$arg_expires;
secure_link_md5 "$secure_link_expires$uri$remote_addr secret";
if ($secure_link = "") {
return 403;
}
if ($secure_link = "0") {
return 410;
}
...
}
ngx_http_slice_module
ngx_http_slice_module模块（1.9.8）是一个过滤器，它将请求拆分为子请求，每个子请求返回一定范围的响应。 过滤器提供更有效的大响应缓存。
CDN系统中，向父层回源时，如果文件过大，使用slice可以让用户快速得到响应。
语法：slice size;
默认值：slice 0;
应用位置：http, server, location
作用： 文件切片，切片的大小。 零值禁用将响应拆分为切片。 请注意，值太低可能会导致内存使用过多并打开大量文件。
为了使子请求返回所需的范围，$ slice_range变量应作为Range请求头字段传递给代理服务器。 如果启用了缓存，则应将$ slice_range添加到缓存键，并启用具有206状态代码的响应缓存。
案例：
location / {
slice 1m;
proxy_cache cache;
proxy_cache_key $uri$is_args$args$slice_range;
proxy_set_header Range $slice_range;
proxy_cache_valid 200 206 1h;
proxy_pass http://localhost:8000;
}
ngx_http_split_clients_module
ngx_http_split_clients_module模块创建适合于A/B测试（也叫做分离测试）的变量。或者当做负载均衡来使用。我相信，有很多地方可以用上此模块。更多
语法：split_clients string $variable { ... }
默认值：无
应用位置：http
作用：为A / B测试创建变量。
案例：
http {
split_clients "${remote_addr}AAA" $variant {
0.5% .one;
2.0% .two;
* "";
}
server {
location / {
index index${variant}.html;
}
}
原始字符串的值经过MurmurHash2算法进行了哈希。 示例中，哈希值从0到21474835（0.5%）对应于变量$variant的".one"值， 哈希值从21474836到107374180（2%）对应于值".two"， 哈希值从107374181到4294967295对应于值""（一个空字符串）。
ngx_http_ssi_module
详细请了解这里。
ngx_http_ssl_module
ngx_http_ssl_module模块为HTTPS提供必要的支持。
指令详解：
ssl
语法：ssl on | off;
默认值：ssl off;
应用位置：http, server
作用：开启 SSL
备注：该指令在1.15.0版本中已过时。 应该使用listen指令的ssl参数。
ssl_buffer_size
语法：ssl_buffer_size size;
默认值：ssl_buffer_size 16k;
应用位置：http, server
作用：设置用于发送数据的缓冲区的大小。
ssl_certificate
语法：ssl_certificate file;
默认值：无
应用位置：http, server
作用：指定PEM格式的证书文件。
ssl_certificate_key
语法：ssl_certificate_key file;
默认值：无
应用位置：http, server
作用：指定具有给定虚拟服务器的PEM格式的密钥的文件。
ssl_ciphers
语法：ssl_ciphers ciphers;
默认值：ssl_ciphers HIGH:!aNULL:!MD5;
应用位置：http, server
作用：指定启用的密码。 密码以OpenSSL库理解的格式指定.
ssl_client_certificate
语法：ssl_client_certificate file;
默认值：无
应用位置：http, server
作用：如果启用了ssl_stapling，则指定具有PEM格式的可信CA证书的文件，该证书用于验证客户端证书和OCSP响应。更多.
ssl_crl
语法：ssl_crl file;
默认值：无
应用位置：http, server
作用：指定具有PEM格式的已吊销证书（CRL）的文件，用于验证客户端证书。CRL 是证书吊销列表。
ssl_dhparam
语法：ssl_dhparam file;
默认值：无
应用位置：http,server
作用：为DHE密码指定具有DH参数的文件。
ssl_stapling
语法：ssl_stapling on | off;
默认值：ssl_stapling off;
应用位置：http, server
作用：启用或禁用服务器对OCSP响应的装订
ssl_early_data
语法：ssl_early_data on | off;
默认值：ssl_early_data off;
应用位置：http, server
作用：启用或禁用TLS 1.3，指令出现在1.15.3版本中。
ssl_ecdh_curve
语法：ssl_ecdh_curve curve;
默认值：ssl_ecdh_curve auto;
应用位置：http, server
作用：指定ECDHE密码的曲线
ssl_password_file
语法：ssl_password_file file;
默认值：无
应用位置：http, server
作用：指定具有密钥密码的文件，其中每个密码在单独的行上指定。 在加载密钥时依次尝试密码短语。
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] [TLSv1.3];
默认值：ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
应用位置：http, server
作用：启用指定的协议。
ssl_session_cache
语法：ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
默认值：ssl_session_cache none;
应用位置：http, server
作用：设置存储会话参数的缓存的类型和大小。更多详细
ssl_session_ticket_key
语法：ssl_session_ticket_key file;
默认值：无
应用位置：http, server
作用：设置具有用于加密和解密TLS会话票证的密钥的文件。 如果必须在多个服务器之间共享相同的密钥，则该指令是必需的。 默认情况下，使用随机生成的密钥。更多
ssl_session_tickets
语法：ssl_session_tickets on | off
默认值：ssl_session_tickets on
应用位置：http, server
作用：启用或禁用通过TLS会话票证
ssl_session_timeout
语法：ssl_session_timeout time;
默认值：ssl_session_timeout 5m;
应用位置：http, server
作用：指定客户端可以重用会话参数的时间。
ssl_stapling_file
语法：ssl_stapling_file file;
默认值：无
应用位置：http, server
作用：设置后，将从指定的文件中获取装订的OCSP响应，而不是查询服务器证书中指定的OCSP响应程序。该文件应为DER格式，由“openssl ocsp”命令生成。
ssl_stapling_responder
语法：ssl_stapling_responder url;
默认值：无
应用位置：http, server
作用：覆盖“Authority Information Access”证书扩展中指定的OCSP响应程序的URL。
ssl_stapling_verify
语法：ssl_stapling_verify on | off;
默认值：ssl_stapling_verify off;
应用位置：http, server
作用：启用或禁用服务器对OCSP响应的验证。
ssl_trusted_certificate
语法：ssl_trusted_certificate file;
默认值：无
应用位置：http, server
作用：如果启用了ssl_stapling，则指定具有PEM格式的可信CA证书的文件，该证书用于验证客户端证书和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变量中。
ssl_verify_depth
语法：ssl_verify_depth number;
默认值：ssl_verify_depth 1;
应用位置：http, server
作用：设置客户端证书链中的验证深度。
ngx_http_stub_status_module
ngx_http_stub_status_module模块提供对基本状态信息的访问。在1.7.5之前的版本中，指令语法需要任意参数，例如“stub_status on”。
语法：stub_status;
默认值：无
应用位置：server, location
作用：访问基本状态信息。
案例：
location = /basic_status {
stub_status;
}
ngx_http_upstream_module
ngx_http_upstream_module模块用于定义可由proxy_pass，fastcgi_pass，uwsgi_pass，scgi_pass，memcached_pass和grpc_pass指令引用的服务器组。
指令详解：
upstream
语法：upstream name { ... }
默认值：无
应用位置：http
作用：定义一组服务器。 服务器可以侦听不同的端口。 此外，可以混合侦听TCP和UNIX域套接字的服务器。
server
语法：server address [parameters];
默认值：无
应用位置：upstream
作用：定义服务器的地址和其他参数。 可以将地址指定为域名或IP地址，带有可选端口，或者指定为“unix：”前缀后指定的UNIX域套接字路径。 如果未指定端口，则使用端口80。 解析为多个IP地址的域名一次定义多个服务器。
常用参数：
weight=number 设置服务器的权重，默认为1。max_conns=number 限制与代理服务器的最大并发活动连接数（1.11.5）。 默认值为零，表示没有限制。 如果服务器组不驻留在共享内存中，则每个工作进程都有限制。max_fails=number 不可访问错误次数- fail_timeout=time 不可访问时间，错误次数时间间隔（如果在fail_timeout时间内错误次数超过max_fails次，则服务器不可访问fail_timeout时长）
- backup 指定为备用服务器
- slow_start=time 慢启动时长，权重从0到full的时间
- down 服务器不可访问
zone
语法：zone name [size]; # 商业版本的nginx才有，用于动态配置 nginx.
默认值：无
应用位置：upstream
作用：定义共享内存区域的名称和大小，该区域保持组的配置和在工作进程之间共享的运行时状态。几个组可能共享同一个区域。在这种情况下，只指定大小一次就足够了。此外，作为我们商业订阅的一部分，这些组允许更改组成员或修改特定服务器的设置，而无需重新启动nginx。配置可以通过API模块(1.13.3)访问。
state
语法：state file;
默认值：无
应用位置：upstream
案例：
state /var/lib/nginx/state/servers.conf
作用：指定保持动态可配置组状态的文件。该状态目前仅限于具有其参数的服务器列表。 解析配置时会读取文件，并在每次更改上游配置时更新。 应避免直接更改文件内容。 该指令不能与server指令一起使用。
hash
语法：hash key [consistent];
默认值：无
应用位置：upstream
作用：对某一个 key 进行哈希或者使用一致性哈希算法进行负载均衡.
案例：
hash $uri # 哈希算法 hash $consistent_key consistent # 一致性哈希算法
ip_hash
语法：ip_hash;
默认值：无
应用位置：upstream
作用：根据客户端的 IP 进行负载均衡，即相同的 IP 将负载均衡到同一个 upstream server
keepalive
语法：keepalive connections;
默认值：无
应用位置：upstream
作用：激活缓存以连接到上游服务器。connections参数设置在每个工作进程的缓存中保留的上游服务器的最大空闲keepalive连接数。 超过此数量时，将关闭最近最少使用的连接。
keepalive_requests
语法：keepalive_requests number;
默认值：keepalive_requests 100;
应用位置：upstream
作用：设置可通过一个keepalive连接提供的最大请求数。 在发出最大请求数后，将关闭连接。
keepalive_timeout
语法：keepalive_timeout timeout;
默认值：keepalive_timeout 60s;
应用位置：upstream
作用：设置超时，在此期间与上游服务器的空闲keepalive连接将保持打开状态。
ntlm
语法：ntlm；
默认值：无
应用位置：upstream
作用：允许使用NTLM身份验证代理请求。 一旦客户端发送具有以“Negotiate”或“NTLM”开头的“Authorization”头字段值的请求，上游连接就绑定到客户端连接。 进一步的客户端请求将通过相同的上游连接进行代理，从而保持身份验证上下文。为了使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 "";
...
}
}
least_conn
语法：least_conn;
默认值：无
应用位置：upstream
作用：将请求负载均衡到最少活跃连接的上游服务器。如果配置的服务器较少，则将转而使用基于权重的轮询算法.
queue
语法：queue number [timeout=time]; # 商业版本中才有.
默认值：无
应用位置：upstream
作用：如果在处理请求时无法立即选择上游服务器，则请求将被放入队列中。 该指令指定了可以同时在队列中的最大请求数。 如果队列已满，或者在超时参数中指定的时间段内无法选择要传递请求的服务器，则会将502（错误网关）错误返回给客户端。
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]
[header]
[sync];
默认值：无
应用位置：upstream
作用：启用会话关联，这会将来自同一客户端的请求传递到一组服务器中的同一服务器。 有三种方法可供选择。
案例：
upstream backend {
server backend1.example.com route=a;
server backend2.example.com route=b;
sticky cookie srv_id expires=1h domain=.example.com path=/;
}
map $cookie_jsessionid $route_cookie {
~.+\.(?P<route>\w+)$ $route;
}
map $request_uri $route_uri {
~jsessionid=.+\.(?P<route>\w+)$ $route;
}
upstream backend {
server backend1.example.com route=a;
server backend2.example.com route=b;
sticky route $route_cookie $route_uri;
}
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;
}
ngx_http_upstream_conf_module # ngx_http_upstream_conf_module模块允许通过简单的HTTP接口即时配置上游服务器组，而无需重新启动nginx。 http或流服务器组必须驻留在共享内存中。 商业版本才有.
ngx_http_upstream_hc_module
ngx_http_upstream_hc_module模块允许对周围位置中引用的组中的服务器进行定期运行状况检查。 服务器组必须驻留在共享内存中。商业版本才有.
案例：
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，并在正文中包含“Welcome to nginx！”。
ngx_http_userid_module
ngx_http_userid_module模块为客户端身份证明设置cookie。接收设置cookie可以被记录在内嵌变量$uid_got和$uid_set中。该模块与Apache的mod_uid一致。
指令详解：
userid
语法：userid on | v1 | log | off;
默认值：userid off;
应用位置：http, server, location
作用：启用或禁用设置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
作用：如果参数未关闭，则启用cookie标记机制并设置用作标记的字符。此机制用于添加或更改userid_p3p和/或cookie过期时间，同时保留客户端标识符。标记可以是英文字母(区分大小写)、数字或“=”字符的任何字母。
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，默认值为零。 对于版本2 cookie，默认值是由服务器IP地址的最后四个八位字节组成的数字。
案例：
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"';
浙公网安备 33010602011771号