7.1.5 模块化体系与常用核心模块

Nginx 以模块化为核心设计思想：核心负责事件驱动与调度，模块提供具体功能（请求处理、过滤、日志、代理等）。理解模块边界与加载方式，是运维排错与扩展的基础。

原理草图：模块化运行路径

模块分类与作用边界（简要）
- 核心模块：配置解析、进程管理、共享内存、日志基础设施。
- 事件模块：平台事件驱动实现，决定并发与连接效率。
- HTTP 模块：处理 HTTP 请求/响应，最常用。
- Stream 模块：TCP/UDP 代理（四层）。
- Mail 模块：邮件代理与认证。

模块安装与加载示例（动态模块）
1) 查看编译参数与已有模块

nginx -V 2>&1 | tr ' ' '\n' | egrep 'with-|add-'

2) 编译并加载动态模块（以 realip 模块为例）

# 假设源码已下载并与当前版本一致
cd /usr/local/src/nginx-1.24.0

# 生成动态模块
./configure --with-compat --add-dynamic-module=../nginx-http-realip-module
make modules

# 复制模块到 nginx 模块目录
cp objs/ngx_http_realip_module.so /etc/nginx/modules/

3) 在主配置加载模块

# /etc/nginx/nginx.conf
load_module modules/ngx_http_realip_module.so;

http {
    real_ip_header X-Forwarded-For;
    set_real_ip_from 10.0.0.0/8;
}

4) 校验与重载

nginx -t
systemctl reload nginx

常用核心模块配置示例（含预期效果）

# /etc/nginx/conf.d/site.conf
log_format main '$remote_addr $request $status $body_bytes_sent';
access_log /var/log/nginx/access.log main;

upstream api_backend {
    server 10.0.1.10:8080 weight=2;
    server 10.0.1.11:8080;
}

server {
    listen 80;
    server_name example.com;

    location /static/ {
        root /data/www;
        expires 7d;   # 静态缓存
    }

    location /api/ {
        proxy_pass http://api_backend;
        proxy_set_header Host $host;
        proxy_connect_timeout 3s;
        proxy_read_timeout 30s;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

预期效果：静态资源 7 天缓存；API 走上游负载均衡；访问日志输出主格式。

排错清单与命令（模块相关）

# 1) 模块加载失败：检查动态模块与主版本是否一致
nginx -V | grep 'nginx version'

# 2) 检查是否编译了目标模块（静态）
nginx -V 2>&1 | grep -- '--with-http_ssl_module'

# 3) 配置指令找不到：定位是哪个模块提供
nginx -T 2>/dev/null | egrep 'load_module|http|stream' -n

# 4) 语法校验
nginx -t

# 5) 查看错误日志
tail -n 200 /var/log/nginx/error.log

常见报错示例
- unknown directive "real_ip_header"：未加载 ngx_http_realip_module。
- module is not binary compatible：动态模块与主程序版本不一致。

练习
1) 为静态站点添加 Gzip 压缩并验证是否生效。

# /etc/nginx/conf.d/gzip.conf
gzip on;
gzip_types text/plain text/css application/javascript application/json;

验证：

curl -I -H "Accept-Encoding: gzip" http://example.com/static/app.js
# 预期：响应头包含 Content-Encoding: gzip

2) 配置限流（请求频率）

# /etc/nginx/conf.d/limit.conf
limit_req_zone $binary_remote_addr zone=req_zone:10m rate=5r/s;

server {
    location /api/ {
        limit_req zone=req_zone burst=10 nodelay;
        proxy_pass http://api_backend;
    }
}

验证：

for i in {1..20}; do curl -s -o /dev/null -w "%{http_code}\n" http://example.com/api/; done
# 预期：部分请求返回 503（被限流）

通过模块化的理解与可执行示例，可在不同场景下快速组合能力、定位问题并安全扩展功能。