Nginx 模块

目录

• 前言
• ngx_http_index_module
• ngx_http_autoindex_module
• ngx_http_charset_module
• ngx_http_stub_status_module
• ngx_http_auth_basic_module
• ngx_http_access_module
• ngx_http_limit_conn_module
• ngx_http_limit_req_module
• Difference of alias & root
• location 匹配优先级

前言

访问控制： ngx_http_auth_basic_module , ngx_http_access_module
访问限制： ngx_http_limit_conn_module , ngx_http_limit_req_module
基本状态： ngx_http_stub_status_module
其他： ngx_http_index_module , ngx_http_autoindex_module ,ngx_http_charset_module

ngx_http_index_module

The ngx_http_index_module module processes requests ending with the slash character (‘/’). Such requests can also be processed by the ngx_http_autoindex_module and ngx_http_random_index_module modules.

翻译：

ngx_http_index_module模块处理以斜杠号（'/'）为结尾的请求，此类请求也可以交给 ngx_http_autoindex_module 和ngx_http_random_index_module模块处理，ngx_http_random_index_module会选择一个随机文件作为索引文件。

# Example Configuration （配置示例）
location / {
    index index.$geo.html index.html;
}

# Directives （指示，命令）
Syntax:		index file ...;
Default:	index index.html;
Context:	http, server, location

# 实例
[root@web01 ~]# cat /etc/nginx/conf.d/blog.wqh.com.conf 
server {
    listen 80;
    server_name blog.wqh.com;
    location / {
      root /code/blog;
      index index.html index.htm blog.htm;
    }
}

ngx_http_autoindex_module

The ngx_http_autoindex_module module processes requests ending with the slash character (‘/’) and produces a directory listing. Usually a request is passed to the ngx_http_autoindex_module module when the ngx_http_index_module module cannot find an index file.

翻译：

ngx_http_autoindex_module 模块处理以斜杠号（'/'）为结尾的请求，并产生一个目录列表。通常情况下，在ngx_http_index_module 模块无法找到索引文件时，这个请求就被 ngx_http_autoindex_module 模块处理。

# Example Configuration  
location / {
    autoindex on;
}

# Directives  
# 启用/禁用 目录列表
Syntax:		autoindex on | off;
Default:	autoindex off;
Context:	http, server, location
# 是否显示文件精确大小
Syntax:		autoindex_exact_size on | off;
Default:	autoindex_exact_size on;
Context:	http, server, location
# 设置目录列表的格式
Syntax:		autoindex_format html | xml | json | jsonp;
Default:	autoindex_format html;
Context:	http, server, location
This directive appeared in version 1.7.9.
# 客户端显示的文件时间 是否与文件服务器的文件时间一致
Syntax:		autoindex_localtime on | off;
Default:	autoindex_localtime off;
Context:	http, server, location

# 实例
[root@web01 ~]# vi /etc/nginx/conf.d/download.wqh.com.conf 
server {
    listen 80;
    server_name download.wqh.com;
    charset        utf-8,gbk;
    location / {
      root /code/download;
      autoindex on;
      autoindex_localtime on;
      autoindex_exact_size off;
    }
}

ngx_http_charset_module

# 控制字符集的模块，此处设置的字符集将赋值于 HTTP 响应首部 Content-Type 发送给客户端
# Example Configuration
include        conf/koi-win;
charset        windows-1251;
source_charset koi8-r;


# Directives
Syntax:		charset $charset | off;
Default:	charset off;
Context:	http, server, location, if in location

# 关于 GBK 和 UTF-8
GBK：专门用来解决中文的编码，包含全部中文字符，但无论中文英文都用 16位（两个字节） 编码
UTF-8：包含全世界所有国家需要用到的字符，英文 使用 8位（一个字节），中文 使用 24位（三个字节）编码
# 实例
server {
    listen 80;
    server_name download.wqh.com;
    charset        utf-8,gbk;
    location / {
      root /code/download;
      autoindex on;
      autoindex_localtime on;
      autoindex_exact_size off;
    }
}

ngx_http_stub_status_module

The ngx_http_stub_status_module module provides access to basic status information.

翻译：ngx_http_status_module 模块提供对基本状态信息的访问，会提供以下信息（官网摘抄）

Name	Description
Active connections	The current number of active client connections including Waiting connections.
accepts	The total number of accepted client connections.
handled	The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached (for example, the worker_connections limit).
requests	The total number of client requests.
Reading	The current number of connections where nginx is reading the request header.
Writing	The current number of connections where nginx is writing the response back to the client.
Waiting	The current number of idle client connections waiting for a request.

# Example Configuration
location = /basic_status {
    stub_status;
}

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

# 实例
[root@web01 ~]# cat /etc/nginx/conf.d/download.wqh.com.conf 
server {
    listen 80;
    server_name download.wqh.com;
    charset        utf-8;
    location / {
      root /code/download;
      autoindex on;
      autoindex_localtime on;
      autoindex_exact_size off;
    }
    location /status {
      stub_status;
    }
}
Active connections  # 当前活跃的连接数量（包括等待请求的限制客户端连接数量）
accepts             # 接收的连接数（TCP连接）
handled             # 处理的连接数（TCP连接），通常与 accepts 相同，除非受限于 worker_connections连接数
requests            # 客户端 http请求 的总数

Reading             # 读取的 http 请求首部
Writing             # 返回给客户端的 http 响应首部
Waiting             # 当前正在等待请求的闲置客户端连接数量，此时开启了 keepalive

# 注意, 一次TCP的连接（无论长短），可以发起多次 http的请求, 如下参数可配置进行验证
# 长连接 / 短链接 和 请求数量无关
keepalive_timeout  0;   # 等同于 关闭长连接，
keepalive_timeout  65;  # 65s 没有活动 则断开连接

ngx_http_auth_basic_module

The ngx_http_auth_basic_module module allows limiting access to resources by validating the user name and password using the “HTTP Basic Authentication” protocol.

翻译：ngx_http_auth_basic_module 模块允许通过认证用户名和密码，对资源限制访问，使用了 HTTP基本认证（HTTP Basic Authentication）协议。

# Example Configuration
location / {
    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}

# Directives
Syntax:		auth_basic `string` | off;
Default:	auth_basic off;
Context:	http, server, location, limit_except

# 实例
[root@web01 ~]# cat /etc/nginx/conf.d/download.wqh.com.conf
server {
    listen 80;
    server_name download.wqh.com;
    charset        utf-8;
    location / {
      root /code/download;
      autoindex on;
      autoindex_localtime on;
      autoindex_exact_size off;
      auth_basic    "close site";
      auth_basic_user_file /etc/nginx/htpasswd;
    }
    location /status {
      stub_status;
      auth_basic    "close site";
      auth_basic_user_file /etc/nginx/htpasswd;
    } 
}
# 需要生成 用户名、密码 文件
# 1.需要安装 httpd-tools，该包中携带了 htpasswd 命令 （安装 httpd 也可以）
[root@web01 ~]# yum install httpd-tools
# 2.创建新的密码文件， -c 创建新文件 -b 允许命令行输入密码
[root@web01 ~]# htpasswd -b -c /etc/nginx/htpasswd wqh wqh123
Adding password for user wqh
# 3.查看密码文件
[root@web01 ~]# cat /etc/nginx/htpasswd 
wqh:$apr1$L7WZzOzC$HmCQGrUP.Hvzcp6xJMoyf1
# 4.添加新的用户信息
[root@web01 ~]# htpasswd -b  /etc/nginx/htpasswd user user123
Adding password for user user
[root@web01 ~]# cat /etc/nginx/htpasswd 
wqh:$apr1$L7WZzOzC$HmCQGrUP.Hvzcp6xJMoyf1
user:$apr1$ZHlNfXJM$/y4uw/Kqn/Q15y3NbzisO1
# 5.交互式添加新的用户信息
[root@web01 ~]# htpasswd /etc/nginx/htpasswd test
New password: 
Re-type new password: 
Adding password for user test
# 6.客户端访问，若客户端为 linux 系统，可以用 curl -u 选项
[root@web02 ~]# curl download.wqh.com/status
<html>
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>nginx/1.18.0</center>
</body>
</html>
[root@web02 ~]# curl -u wqh:wqh123 download.wqh.com/status
Active connections: 1 
server accepts handled requests
 848 848 1592 
Reading: 0 Writing: 1 Waiting: 0

ngx_http_access_module

The ngx_http_access_module module allows limiting access to certain client addresses.

翻译：ngx_http_access_module 模块允许对指定的客户端 IP 地址（或网段）限制访问 。

# Example Configuration
location / {
    deny  192.168.1.1;
    allow 192.168.1.0/24;
    allow 10.1.1.0/16;
    allow 2001:0db8::/32;
    deny  all;
}
# The rules are checked in sequence until the first match is found. In this example, access is allowed only for IPv4 networks 10.1.1.0/16 and 192.168.1.0/24 excluding the address 192.168.1.1, and for IPv6 network 2001:0db8::/32. 
# 此模块的规则按顺序匹配，在这个例子中，允许 IPV4 网段 10.1.1.0/16 和 192.168.1.0/24（不包括 192.168.1.1 ）访问，也允许 IPV6 网段 2001:0db8::/32 访问

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

# 实例
[root@web01 ~]# cat /etc/nginx/conf.d/download.wqh.com.conf
server {
    listen 80;
    server_name download.wqh.com;
    # ngx_http_limit_conn_module's limit_coon
    limit_conn addr 1;
    # ngx_http_charset_module
    charset        utf-8,gbk;

    # ngx_http_index_module
    location / {
      root /code/download;
      index index.html index.htm;
      # ngx_http_limit_req_module's limit_req
      limit_req zone=one burst=1 nodelay;
      # ngx_http_limit_req_module's limit_req_status
      limit_req_status 456;
      error_page 456 /456.html;
    }


    # ngx_stub_status_module
    location /status {
      stub_status;
      # ngx_http_auth_basic_module
      auth_basic    "close site";
      auth_basic_user_file /etc/nginx/htpasswd;
    }
   
    # Difference of alias & root
    # request URI = "/download"
    location /download {
      # list_locatation = /down/download
      root /down;
      autoindex on; 
      autoindex_localtime on;
      autoindex_exact_size off;
      # ngx_http_auth_basic_module
      auth_basic    "close site";
      auth_basic_user_file /etc/nginx/htpasswd;
    }
    # request URI = "/download_test"
    location /download_test {
      # list_locatation = /down
      alias /down;
      autoindex on;
      autoindex_localtime on;
      autoindex_exact_size off;
      # ngx_http_acess_module     <------- allow 和 deny  配置
      allow 10.0.0.1;
      deny all;
    }
}

ngx_http_limit_conn_module

The ngx_http_limit_conn_module module is used to limit the number of connections per the defined key, in particular, the number of connections from a single IP address.Not all connections are counted. A connection is counted only if it has a request being processed by the server and the whole request header has already been read.

翻译：ngx_http_limit_conn_module 模块可以根据定义的键来限制每个键值的连接数，特别是来源于同一个 IP 地址 的连接 。并不是所有的连接都被计数，只有那些正在被处理的请求（请求首部的信息已被完全读入）所在的连接才会被计数 。

# Example Configuration
http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;       <------- 定义的键，在内存中开辟 10M 空间，暂存键值对的数据

    ...

    server {

        ...

        location /download/ {
            limit_conn addr 1;
        }

# Directives
# limit_conn_zone 
Syntax:		limit_conn_zone key zone=name:size; 		<------- 定义的键（语法）
Default:	—
Context:	http
# limit_conn
Syntax:		limit_conn zone number;
Default:	—
Context:	http, server, location


# 实例
# 1. 先在 http层 配置 limit_conn_zone
[root@web01 ~]# cat /etc/nginx/nginx.conf
user  nginx;
worker_processes  1;
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;
events {
    worker_connections  1024;
}
http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log  /var/log/nginx/access.log  main;
    sendfile        on;
    #tcp_nopush     on;
    keepalive_timeout  65;
    #gzip  on;
    # ngx_http_limit_conn_module's  limit_conn_zone 		<------- limit_conn_zone 配置
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    # ngx_http_limit_req_module's  limit_req_zone 
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
    include /etc/nginx/conf.d/*.conf;
}

# 2. 然后在 server层 配置 limit_conn
[root@web01 ~]# cat /etc/nginx/conf.d/download.wqh.com.conf
server {
    listen 80;
    server_name download.wqh.com;
    # ngx_http_limit_conn_module's limit_coon 		<------- limit_conn 配置
    limit_conn addr 1;
    # ngx_http_charset_module
    charset        utf-8,gbk;
    
    # ngx_http_index_module
    location / {
      root /code/download;
      index index.html index.htm;
      # ngx_http_limit_req_module's limit_req
      limit_req zone=one burst=1 nodelay;
      # ngx_http_limit_req_module's limit_req_status
      limit_req_status 456;
      error_page 456 /456.html;
    }
    # ngx_stub_status_module
    location /status {
      stub_status;
      # ngx_http_auth_basic_module
      auth_basic    "close site";
      auth_basic_user_file /etc/nginx/htpasswd;
    }
    # Difference of alias & root
    # request URI = "/download"
    location /download {
      # list_locatation = /down/download
      root /down;
      autoindex on; 
      autoindex_localtime on;
      autoindex_exact_size off;
      # ngx_http_auth_basic_module
      auth_basic    "close site";
      auth_basic_user_file /etc/nginx/htpasswd;
    }
    # request URI = "/download_test"
    location /download_test {
      # list_locatation = /down
      alias /down;
      autoindex on;
      autoindex_localtime on;
      autoindex_exact_size off;
      # ngx_http_acess_module
      allow 10.0.0.1;
      deny all;
    }
}

ngx_http_limit_req_module

The ngx_http_limit_req_module module (0.7.21) is used to limit the request processing rate per a defined key, in particular, the processing rate of requests coming from a single IP address. The limitation is done using the “leaky bucket” method.

翻译： ngx_http_limit_req_module 模块用来限制对每个定义的键的请求处理速率，特别是来源于同一个 IP 地址 的请求处理速率 。实现的原理是 “漏桶”原理 。

# Example Configuration
http {
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

    ...

    server {

        ...

        location /search/ {
            limit_req zone=one burst=5;
        }
        
# Directives
# limit_req_zone
Syntax:		limit_req_zone key zone=name:size rate=rate [sync];
Default:	—
Context:	http
# limit_req
Syntax:		limit_req zone=name [burst=number] [nodelay | delay=number];   
Default:	—
Context:	http, server, location
# limit_req_status
Syntax:	        limit_req_status code;
Default:	limit_req_status 503;
Context:	http, server, location
This directive appeared in version 1.3.15.
# 关于 limit_req 中的 nodelay （转自 http://www.linuxe.cn/post-398.html ）
nodelay：对用户发起的请求不做延迟处理，而是立即处理。比如上面定义了rate=1r/s，即每秒钟只处理1个请求。
如果同一时刻有两个后缀为htm的请求过来了，若设置了nodelay，则会立刻处理这两个请求。
若没设置nodelay，则会严格执行rate=1r/s的配置，即只处理一个请求，然后下一秒钟再处理另外一个请求。
直观的看就是页面数据卡了，过了一秒后才加载出来。

真正对限流起作用的配置就是rate=1r/s和burst=5这两个配置，参考具体案例以便理解：
有两个请求同时到达Nginx，其中一个被处理，另一个放到了burst缓冲队列里。由于配置了nodelay，所以第二个请求依然被处理了，
但会占用burst缓冲队列的一个长度。如果下一秒没有请求过来，这一个长度的空间就会被释放，否则会继续占用burst队列。
当burst空间占用达到设置的5之后所有请求就会直接被Nginx拒绝，并返回503错误。
可见如果第二秒又来了两个请求，其中一个请求又占用了一个burst空间，第三秒、第四秒直到第五秒，每秒都有两个请求过来，
虽然两个请求都被处理了（因为配置了nodelay），但其中一个请求仍然占用了一个burst长度，五秒后整个burst长度=5都被占用了。
第六秒再过来两个请求，其中一个请求就被拒绝了。
被拒绝的请求在Nginx错误日志中可以看到是被某个zone给拒绝了

# 实例
# 1. 先在 http层 配置 limit_req_zone
[root@web01 ~]# cat /etc/nginx/nginx.conf
user  nginx;
worker_processes  1;
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;
events {
    worker_connections  1024;
}
http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log  /var/log/nginx/access.log  main;
    sendfile        on;
    #tcp_nopush     on;
    keepalive_timeout  65;
    #gzip  on;
    # ngx_http_limit_conn_module's  limit_conn_zone 		 
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    # ngx_http_limit_req_module's  limit_req_zone		  <------- limit_req_zone 配置		
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
    include /etc/nginx/conf.d/*.conf;
}

# 2. 然后在 server层 配置 limit_req ，limit_req_status
[root@web01 ~]# cat /etc/nginx/conf.d/download.wqh.com.conf 
server {
    listen 80;
    server_name download.wqh.com;
    # ngx_http_limit_conn_module's limit_coon
    limit_conn addr 1;
    # ngx_http_charset_module
    charset        utf-8,gbk;

    # ngx_http_index_module
    location / {
      root /code/download;
      index index.html index.htm;
      # ngx_http_limit_req_module's limit_req		  <------- limit_req 配置
      limit_req zone=one burst=1 nodelay;
      # ngx_http_limit_req_module's limit_req_status  <------- limit_req_status 配置
      limit_req_status 456;		 		
      # Bind the status_code and the error_page      <------- 绑定 状态码 和 错误页面  
      error_page 456 /456.html;
    }
    # ngx_stub_status_module
    location /status {
      stub_status;
      # ngx_http_auth_basic_module
      auth_basic    "close site";
      auth_basic_user_file /etc/nginx/htpasswd;
    }
    # Difference of alias & root
    # request URI = "/download"
    location /download {
      # list_locatation = /down/download
      root /down;
      autoindex on; 
      autoindex_localtime on;
      autoindex_exact_size off;
      # ngx_http_auth_basic_module
      auth_basic    "close site";
      auth_basic_user_file /etc/nginx/htpasswd;
    }
    # request URI = "/download_test"
    location /download_test {
      # list_locatation = /down
      alias /down;
      autoindex on;
      autoindex_localtime on;
      autoindex_exact_size off;
      # ngx_http_acess_module
      allow 10.0.0.1;
      deny all;
    }
}

Difference of alias & root

[root@web01 ~]# vi /etc/nginx/conf.d/download.wqh.com.conf 
server {
    listen 80;
    server_name download.wqh.com;

    # ngx_http_charset_module
    charset        utf-8,gbk;

   
    # ngx_http_index_module
    location / {
      root /code/download;
      index index.html index.htm;
    }


    # ngx_stub_status_module
    location /status {
      stub_status;
      # ngx_http_auth_basic_module
      auth_basic    "close site";       <--------- 限制访问
      auth_basic_user_file /etc/nginx/htpasswd;
    }
   
    # Difference of alias & root
    # request URI = "/download/"
    location /download {
      # list_locatation = /down/download             
      root /down;          <--------- 会找 /down/download ，显示 /down/download 下的目录列表，root 的作用是指定 URI 中的 根路径位置(`/`)，受 URI 的影响
      autoindex on; 
      autoindex_localtime on;
      autoindex_exact_size off;
      # ngx_http_auth_basic_module
      auth_basic    "close site";       <--------- 限制访问
      auth_basic_user_file /etc/nginx/htpasswd;
    }
    # request URI = "/download_test"
    location /download_test {
      # list_locatation = /down
      alias /down;         <--------- 会找 /down ，显示 /down 下的目录列表，alias 的作用是指定 URI 的别名，不受 URI 影响
      autoindex on;
      autoindex_localtime on;
      autoindex_exact_size off;
      # ngx_http_auth_basic_module
      auth_basic    "close site";       <--------- 限制访问
      auth_basic_user_file /etc/nginx/htpasswd;
    }
}

location 匹配优先级

优先级	匹配符	匹配规则
1	location = /uri	精确匹配，优先级最高
2	location ^～ /uri	普通字符串匹配，不支持正则表达式，当匹配成功后停止其他location匹配，优先级高于正则
3	location ~	正则匹配，区分大小写
4	location ~*	正则匹配，不区分大小写
5	location /url	前缀匹配
6	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
# 如果请求的是 “/documents/1.jpg” 则匹配到 E

# 实例
[root@web01 ~]# cat /etc/nginx/conf.d/search.wqh.com.conf
server {
    listen 80;
    server_name search.wqh.com;
    # 精准匹配，优先级 1
    location = / {
        default_type text/html;
        return 200 "location =/";
    }
    # 通用匹配，优先级 5
    location / {
        default_type text/html;
        return 200 "location /";
    }
    # 前缀匹配，优先级 4
    location /documents {
        default_type text/html;
        return 200 "location /documents";
    }
    # 普通字符串匹配，不支持正则，优先级 2
    location ^~ /images/ {
        default_type text/html;
        return 200 "location ^~ /images/";
    }
    # 正则匹配，优先级 3
    location ~* .(gif|jpg|jsp)$ {
        default_type text/html;
        return 200 "location ~* .(gif|jpg|jsp)";
    }
}