nginx-request-logging

Nginx 请求日志配置

本技能介绍如何为 Nginx Web 服务器配置自定义日志、速率限制和错误处理。

何时使用此技能

在任务涉及以下内容时使用此技能：

• 安装和配置 Nginx
• 设置自定义日志格式
• 实施速率限制
• 创建自定义错误页面（404、500 等）
• 配置 Nginx 监听非标准端口

配置前分析

修改任何 Nginx 配置前：

1. 检查现有配置结构

   • 阅读 /etc/nginx/nginx.conf，了解当前配置
   • 检查现有的 include 指令，了解文件组织方式
   • 找出日志格式、速率限制区域和其他全局设置的定义位置

2. 检查系统状态

   • 确认是否已安装 Nginx：which nginx 或 nginx -v
   • 检查 Nginx 是否正在运行：pgrep nginx 或 ps aux | grep nginx
   • 确认目标端口是否可用：ss -tlnp | grep <port> 或 netstat -tlnp | grep <port>

3. 备份原始配置

   • 修改前创建备份：cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak

配置方法

目录结构

Nginx 配置通常采用以下层级结构：

• /etc/nginx/nginx.conf - 主配置（全局设置、日志格式、速率限制区域）
• /etc/nginx/conf.d/ - 站点专属配置（服务器块）
• /etc/nginx/sites-available/ 和 /etc/nginx/sites-enabled/ - 另一种站点管理方式（基于 Debian 的系统）

配置位置指南

设置类型	位置	原因
日志格式定义	nginx.conf（http 块）	必须在服务器块中使用前定义
速率限制区域	nginx.conf（http 块）	区域在各服务器块间共享
服务器块	conf.d/*.conf	模块化，易于管理
自定义错误页面	服务器块或 location 块	适用于特定上下文

速率限制配置

速率限制需要以下两部分：

1. 区域定义（在 nginx.conf 的 http 块中）：

   limit_req_zone $binary_remote_addr zone=zonename:10m rate=10r/s;
   

2. 应用区域（在服务器块或 location 块中）：

   limit_req zone=zonename burst=5 nodelay;
   

自定义日志格式

在 http 块中定义自定义日志格式：

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

在服务器块中应用：

access_log /var/log/nginx/custom_access.log custom_format;

服务管理

Nginx 服务的管理方式因环境而异：

环境	启动命令	重新加载命令	停止命令
systemd	systemctl start nginx	systemctl reload nginx	systemctl stop nginx
直接运行	nginx	nginx -s reload	nginx -s stop
Docker/容器	nginx -g 'daemon off;'	nginx -s reload	nginx -s quit

重要：启动或重新加载前，务必测试配置：

nginx -t

验证策略

基本功能

curl -s http://localhost:<port>/
curl -s -o /dev/null -w "%{http_code}" http://localhost:<port>/nonexistent

速率限制验证

触发速率限制需要并发请求。顺序发送的请求不会超过速率限制。

正确方法（并行请求）：

seq 20 | xargs -P 20 -I {} curl -s -o /dev/null -w "%{http_code}\n" http://localhost:<port>/

错误方法（不会触发速率限制）：

for i in {1..20}; do curl -s http://localhost:<port>/; done  # Too slow, sequential

日志验证

tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

常见问题

1. 找不到日志格式：必须先在 nginx.conf 中定义日志格式，然后才能在服务器块中引用

2. 未触发速率限制：顺序请求速度太慢；请使用 xargs -P 或类似方式发送并行请求

3. 配置语法错误：启动或重新加载前，务必运行 nginx -t

4. 端口已被占用：配置新端口前，使用 ss -tlnp 检查

5. 无法使用 systemctl：在容器或精简环境中，直接使用 nginx 命令

6. 默认站点冲突：创建自定义配置时，移除或禁用默认站点配置：

   rm -f /etc/nginx/sites-enabled/default
   

7. 缺少目录：写入配置前，确认所需目录存在：

   ls -la /etc/nginx/conf.d/
   

执行效率

• 批量处理文件操作：尽可能并行创建多个静态文件（index.html、404.html 等）
• 合并验证步骤：在一次验证中测试多个端点
• 提前规划验证：在实现之前确定测试策略
• 使用幂等命令：优先使用 mkdir -p、rm -f，以便妥善处理文件已存在或缺失的情况

工作流示例

1. 检查系统状态（是否已安装 Nginx、是否正在运行、端口是否可用）
2. 阅读现有的 nginx.conf 结构
3. 备份配置
4. 创建所需目录和静态内容
5. 修改 nginx.conf 以设置全局配置（日志格式、限流区域）
6. 在 conf.d/ 中创建服务器配置
7. 删除冲突的默认配置
8. 使用 nginx -t 测试配置
9. 启动或重新加载 Nginx 服务
10. 验证所有功能（主页、错误页面、限流、日志）