Nginx 核心模块与指令详解

Core Modules and Directives Explained

概述

Nginx的强大功能来源于其模块化架构。理解核心模块和指令是深入掌握Nginx的关键。本文将详细介绍Nginx的核心模块、常用指令及其配置方法。

1. Nginx架构概述

1.1 模块化架构

Nginx Core
├── Event Module (事件模块)
├── HTTP Core Module (HTTP核心模块)
├── Mail Module (邮件模块)
├── Stream Module (流模块)
└── Third-party Modules (第三方模块)

1.2 配置上下文

# 全局上下文
user nginx;
worker_processes auto;

# 事件上下文
events {
    worker_connections 1024;
}

# HTTP上下文
http {
    # HTTP全局设置

    # 服务器上下文
    server {
        # 服务器设置

        # 位置上下文
        location / {
            # 位置设置
        }
    }
}

2. 核心模块详解

2.1 核心模块 (Core Module)

基本指令

# 运行用户
user nginx;

# 工作进程数量
worker_processes auto;  # auto | number

# 错误日志
error_log /var/log/nginx/error.log warn;

# PID文件位置
pid /var/run/nginx.pid;

# 工作目录
working_directory /var/cache/nginx;

# 进程优先级 (-20 到 20)
worker_priority 0;

# 文件描述符限制
worker_rlimit_nofile 65535;

# CPU亲和性
worker_cpu_affinity auto;

进程管理

# 主进程以daemon方式运行
daemon on;

# 主进程文件锁
lock_file /var/run/nginx.lock;

# 环境变量
env HOSTNAME;
env PATH;

# 定时器分辨率
timer_resolution 100ms;

2.2 事件模块 (Events Module)

events {
    # 事件驱动模型
    use epoll;  # epoll | kqueue | select | poll

    # 每个工作进程的连接数
    worker_connections 1024;

    # 是否接受多个连接
    multi_accept on;

    # 连接互斥锁
    accept_mutex on;
    accept_mutex_delay 500ms;

    # 调试连接
    debug_connection 192.168.1.1;
    debug_connection localhost;
}

2.3 HTTP核心模块

基础配置

http {
    # MIME类型
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # 字符集
    charset utf-8;
    source_charset utf-8;

    # 日志格式
    log_format main '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent"';

    log_format detailed '$remote_addr - $remote_user [$time_local] '
                       '"$request" $status $body_bytes_sent '
                       '"$http_referer" "$http_user_agent" '
                       '$request_time $upstream_response_time';

    # 访问日志
    access_log /var/log/nginx/access.log main;

    # 文件传输
    sendfile on;
    sendfile_max_chunk 1m;

    # TCP优化
    tcp_nopush on;
    tcp_nodelay on;

    # 连接保持
    keepalive_timeout 65;
    keepalive_requests 100;
}

3. Server块配置指令

3.1 基本服务器指令

server {
    # 监听端口和地址
    listen 80;
    listen [::]:80;
    listen 443 ssl http2;
    listen 80 default_server;

    # 服务器名称
    server_name example.com www.example.com;
    server_name *.example.com;
    server_name ~^(?<subdomain>\w+)\.example\.com$;

    # 根目录
    root /var/www/html;

    # 索引文件
    index index.html index.htm index.php;

    # 字符集
    charset utf-8;

    # 错误页面
    error_page 404 /404.html;
    error_page 500 502 503 504 /50x.html;

    # 访问日志
    access_log /var/log/nginx/example.com.access.log;
    error_log /var/log/nginx/example.com.error.log;
}

3.2 客户端请求配置

server {
    # 客户端请求体大小限制
    client_max_body_size 100m;
    client_body_buffer_size 128k;
    client_body_timeout 60s;

    # 客户端头部大小限制
    client_header_buffer_size 1k;
    large_client_header_buffers 4 4k;
    client_header_timeout 60s;

    # 发送超时
    send_timeout 60s;

    # 连接限制
    limit_conn_zone $binary_remote_addr zone=conn_limit_per_ip:10m;
    limit_conn conn_limit_per_ip 10;

    # 请求限制
    limit_req_zone $binary_remote_addr zone=req_limit_per_ip:10m rate=5r/s;
    limit_req zone=req_limit_per_ip burst=10 nodelay;
}

4. Location块配置指令

4.1 Location匹配规则

server {
    # 精确匹配
    location = /exact {
        return 200 "Exact match";
    }

    # 前缀匹配（优先）
    location ^~ /priority {
        return 200 "Priority prefix match";
    }

    # 正则匹配（区分大小写）
    location ~ \.(jpg|jpeg|png|gif)$ {
        expires 1y;
    }

    # 正则匹配（不区分大小写）
    location ~* \.(jpg|jpeg|png|gif)$ {
        expires 1y;
    }

    # 前缀匹配
    location /prefix {
        return 200 "Prefix match";
    }

    # 默认匹配
    location / {
        try_files $uri $uri/ =404;
    }
}

4.2 Location内部指令

location / {
    # 文件查找顺序
    try_files $uri $uri/ @fallback;

    # 别名（替代root）
    alias /var/www/static/;

    # 内部重定向
    try_files $uri $uri/ /index.php?$query_string;

    # 外部重定向
    return 301 https://example.com$request_uri;

    # 条件判断
    if ($request_method = POST) {
        return 405;
    }

    # 设置变量
    set $mobile_rewrite do_not_perform;

    # 添加头部
    add_header X-Frame-Options SAMEORIGIN;
    add_header X-Content-Type-Options nosniff;
}

# 命名location
location @fallback {
    proxy_pass http://backend;
}

5. 常用内置变量

5.1 请求相关变量

# 请求信息
$request                 # 完整请求行
$request_method          # 请求方法 (GET, POST等)
$request_uri             # 完整URI (包含参数)
$uri                     # URI路径部分
$document_uri            # 同$uri
$args                    # 查询参数
$query_string            # 同$args
$scheme                  # 协议 (http或https)

# 使用示例
log_format custom '$remote_addr - [$time_local] '
                 '"$request_method $uri" $status '
                 'args="$args"';

5.2 客户端相关变量

# 客户端信息
$remote_addr             # 客户端IP地址
$remote_port             # 客户端端口
$remote_user             # 认证用户名
$binary_remote_addr      # 二进制IP地址
$http_user_agent         # User-Agent头
$http_referer            # Referer头
$http_host               # Host头
$http_x_forwarded_for    # X-Forwarded-For头

# 使用示例
location /api {
    if ($http_user_agent ~* "bot|crawler|spider") {
        return 403;
    }
    proxy_pass http://backend;
}

5.3 服务器相关变量

# 服务器信息
$server_name             # 服务器名称
$server_addr             # 服务器IP地址
$server_port             # 服务器端口
$hostname                # 主机名
$nginx_version           # Nginx版本
$pid                     # 工作进程PID

# 时间相关
$time_local              # 本地时间
$time_iso8601            # ISO 8601格式时间
$msec                    # 毫秒时间戳

# 使用示例
add_header X-Server-Info "$hostname:$server_port";

6. 条件判断指令

6.1 if指令使用

location /conditional {
    # 变量存在判断
    if ($arg_debug) {
        return 200 "Debug mode enabled";
    }

    # 正则匹配
    if ($http_user_agent ~* "mobile|android|iphone") {
        set $mobile yes;
    }

    # 文件存在判断
    if (!-f $request_filename) {
        return 404;
    }

    # 目录存在判断
    if (-d $request_filename) {
        rewrite ^(.*)$ $1/ permanent;
    }

    # 多条件组合
    set $block 0;
    if ($request_method = POST) {
        set $block 1;
    }
    if ($http_user_agent ~* "bot") {
        set $block "${block}1";
    }
    if ($block = "11") {
        return 403;
    }
}

6.2 map指令使用

# 在HTTP块中定义映射
http {
    map $http_user_agent $mobile {
        default       0;
        ~*mobile      1;
        ~*android     1;
        ~*iphone      1;
    }

    map $uri $cache_control {
        default                 "no-cache";
        ~*\.(js|css)$          "max-age=31536000";
        ~*\.(jpg|jpeg|png)$    "max-age=86400";
    }

    server {
        location / {
            if ($mobile) {
                rewrite ^(.*)$ /mobile$1 last;
            }

            add_header Cache-Control $cache_control;

            try_files $uri $uri/ =404;
        }
    }
}

7. 重写规则

7.1 rewrite指令

server {
    # 基本重写
    rewrite ^/old-path/(.*)$ /new-path/$1 permanent;

    # 条件重写
    if ($scheme = http) {
        rewrite ^(.*)$ https://$server_name$1 permanent;
    }

    # 复杂重写规则
    location /product {
        rewrite ^/product/([0-9]+)/?$ /product.php?id=$1 last;
        rewrite ^/product/([0-9]+)/([a-z]+)/?$ /product.php?id=$1&action=$2 last;
    }

    # 带查询参数的重写
    rewrite ^/search/(.*)$ /search.php?q=$1&$args? last;
}

7.2 return指令

server {
    # 简单重定向
    location /old-site {
        return 301 https://newsite.com$request_uri;
    }

    # 返回内容
    location /status {
        return 200 "Server is healthy\n";
        add_header Content-Type text/plain;
    }

    # 条件返回
    location /maintenance {
        if (-f /var/www/maintenance.flag) {
            return 503 "Site under maintenance";
        }
        try_files $uri $uri/ =404;
    }
}

8. 模块加载与配置

8.1 动态模块加载

# 在主配置文件顶部加载模块
load_module modules/ngx_http_geoip_module.so;
load_module modules/ngx_http_image_filter_module.so;

http {
    # 使用GeoIP模块
    geoip_country /usr/share/GeoIP/GeoIP.dat;
    geoip_city /usr/share/GeoIP/GeoLiteCity.dat;

    map $geoip_country_code $blocked_country {
        default no;
        CN yes;
        RU yes;
    }

    server {
        if ($blocked_country = yes) {
            return 403;
        }
    }
}

8.2 检查已加载模块

# 查看编译的模块
nginx -V 2>&1 | tr ' ' '\n' | grep module

# 查看动态模块
ls /etc/nginx/modules/

# 检查配置
nginx -T | grep load_module

9. 调试和测试

9.1 调试配置

# 启用调试日志
error_log /var/log/nginx/debug.log debug;

# 特定IP调试
events {
    debug_connection 192.168.1.100;
}

# 请求调试
location /debug {
    add_header X-Debug-URI $uri;
    add_header X-Debug-Args $args;
    add_header X-Debug-Remote-Addr $remote_addr;
    return 200 "Debug info in headers";
}

9.2 配置测试方法

# 测试配置语法
nginx -t

# 显示最终配置
nginx -T

# 测试特定配置文件
nginx -t -c /path/to/nginx.conf

# 检查配置差异
nginx -T > current_config.txt

小结

通过本文的学习，你应该掌握：

1. Nginx模块化架构的基本概念
2. 核心模块和常用指令的配置方法
3. Location匹配规则和内部指令使用
4. 内置变量的含义和应用场景
5. 条件判断和重写规则的编写
6. 模块加载和调试技巧

下一篇文章将介绍虚拟主机的配置方法。