NGINX `ngx_http_core_module` 深度解读与实战指南

一、模块定位与主要功能

• 核心职责
  • 接受并解析客户端请求
  • 管理连接与请求生命周期（超时、长连接等）
  • 路由与分发：server、location、try_files
  • 静态文件服务：root / alias / sendfile
  • 缓冲与 I/O 优化：client_body_buffer_size、aio、directio
  • 访问控制与限速：limit_except、limit_rate、satisfy
  • 错误处理：error_page、recursive_error_pages
  • 日志与调试：log_not_found、log_subrequest

二、请求与连接管理

1. 超时控制

client_header_timeout  60s;   # 读取请求头超时时间
client_body_timeout    60s;   # 读取请求体超时时间
send_timeout           60s;   # 发送响应超时时间
keepalive_timeout      75s;   # 长连接超时时间

合理调节可平衡用户体验与资源占用，避免慢速客户端拖垮 worker。

2. 缓冲与临时文件

client_body_buffer_size     16k;          # 请求体缓冲大小
client_body_in_single_buffer on;           # 将请求体保存在单一缓冲区
client_body_temp_path       /tmp/nginx_body 1 2;  

当请求体过大时，NGINX 会将剩余部分写入临时文件。client_body_in_file_only on|clean 可强制或清理这些文件。

三、静态文件 I/O 优化

1. sendfile 与 aio

sendfile        on;       # 使用零拷贝
tcp_nopush      on;       # 合并头部与文件首块
aio             on;       # 异步读文件（Linux/FreeBSD）
directio        4m;       # 文件大于 4MB 时启用 O_DIRECT

• Zero-copy：sendfile 将内核页缓存直接发送给网络套接字。
• AIO + DirectIO：对于大文件启用异步与直接 I/O，减轻 worker 进程阻塞。

2. 读写分块

sendfile_max_chunk 2m;    # 限制单次 sendfile 大小，防止吞占过多 worker
output_buffers      2 32k;# 磁盘文件读取缓冲区
postpone_output     1460;  # 在缓冲区满一定数据后再发送

四、路由与文件定位

1. root vs alias

location /images/ {
    root  /data/www;         # /images/foo.jpg → /data/www/images/foo.jpg
}
location /static/ {
    alias /data/static/;     # /static/foo.css  → /data/static/foo.css
}

• alias：直接替换整个 URI 前缀，更灵活；
• 正则 Location 下 alias：必须引用捕获组。

2. try_files

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

按顺序检测文件或目录，未命中则内部重定向或返回错误。

3. location 匹配优先级

1. 精确匹配 (= /)
2. 前缀匹配最长 (^~)
3. 正则按定义顺序
4. 普通前缀

五、访问控制与限速

1. 方法限制

location /api/ {
    limit_except GET POST {
        deny all;
    }
}

仅允许指定方法，其余返回 405 或 403。

2. 速率限制

limit_rate       100k;       # 每个请求最大 100KB/s
limit_rate_after 1m;         # 前 1MB 不限速

配合 map 动态速率可实现分级限流；也可通过 $limit_rate 变量设置。

3. 访问策略

satisfy any;
allow  192.168.1.0/24;
deny   all;
auth_basic           "Restricted";
auth_basic_user_file /etc/nginx/htpasswd;

all 要求同时满足 IP 白名单与身份验证；any 则二者其一即可。

六、错误处理与日志

1. 错误页自定义

error_page 404  /404.html;
error_page 500 502 503 504  /50x.html;
error_page 403 =301 http://example.com/forbidden.html;

支持内部重定向与外部跳转，可变更响应码：=200。

2. 日志开关

log_not_found    off;  # 不记录 404
log_subrequest   on;   # 记录子请求
recursive_error_pages on; # 多级错误页跳转

七、内置变量精要

变量	含义
$remote_addr	客户端 IP
$request_uri	原始请求 URI
$args	查询字符串
$request_body	请求体（小体量时）
$document_root	root 或 alias 值
$uri	规范化后的 URI（可能因重写改变）
$host	Host 头或服务器名
$scheme	http/https
$status	响应状态码
$connection_requests	单连接请求计数
$request_time	请求处理总时长，精度毫秒

借助这些变量，可在日志、proxy_pass、add_header 等指令中灵活操作。

八、最佳实践与调优建议

1. 连接与超时：根据业务特性合理缩短超时，避免“慢速客户端攻击”。
2. 缓冲与 I/O：静态大文件启用 sendfile+aio+directio；小文件用默认即可。
3. 路由规则顺序：将最热路径放在前面（如 = /favicon.ico、^~ /static/）加速匹配。
4. 错误页与重试：避免过度递归的错误重定向，recursive_error_pages 仅在必要时开启。
5. 安全策略：结合 limit_except、satisfy 与 disable_symlinks 加固防护。
6. 日志管理：对高并发路径关闭 log_not_found，对子请求、反向代理开启 log_subrequest，便于排查。

九、总结

ngx_http_core_module 是 NGINX HTTP 服务的基础基石，其指令涵盖了从连接管理、请求解析到路由分发、文件 I/O、访问控制、错误处理等核心场景。通过合理组合各项指令与内置变量，可打造高性能、可维护且安全的 Web 服务架构。希望本篇详解能帮助你在生产环境中灵活运用、精细调优，打造卓越的 NGINX 应用。