Nginx 中的超时（Timeout）配置是保障服务器性能、稳定性和资源高效利用的关键参数，主要分为客户端超时、代理超时和连接保持超时三大类。以下是各类超时参数的含义及配置建议，结合生产环境的最佳实践整理而成：
⏱️ 一、客户端超时（Client-Side Timeouts）
-
client_header_timeout
• 含义：等待客户端发送完整 HTTP 请求头的最大时间。若超时，Nginx 返回 408 Request Time-out。• 默认值：60 秒 。
• 建议配置：
◦ 常规服务：5–30 秒（如 API 网关建议 10 秒）。
◦ 高延迟网络（如移动端）：可延长至 30 秒，避免因网络抖动中断连接。
-
client_body_timeout
• 含义：等待客户端发送请求体的间隔时间（非总时长）。超时则关闭连接。• 默认值：60 秒 。
• 建议配置：
◦ 普通表单提交：5–30 秒 。
◦ 大文件上传：300 秒以上（需配合 client_max_body_size 限制）。
-
send_timeout
• 含义：向客户端发送响应的两次写操作间隔时间。超时则关闭连接。• 默认值：60 秒 。
• 建议配置：
◦ 静态资源/CDN：10–30 秒 。
◦ 大文件下载：120 秒以上（如视频流服务）。
🔁 二、代理超时（Proxy-Side Timeouts）
-
proxy_connect_timeout
• 含义：Nginx 与后端服务器建立 TCP 连接的超时时间（含 SSL 握手）。• 默认值：60 秒 。
• 建议配置：
◦ 内网低延迟：1–5 秒 。
◦ 跨地域/高延迟：15–30 秒（如云服务跨区调用）。
-
proxy_send_timeout
• 含义：向后端发送请求的两次写操作间隔时间。• 默认值：60 秒 。
• 建议配置：
◦ 普通请求：30–60 秒 。
◦ 大文件上传至后端：≥900 秒（如 1GB 文件在 10Mbps 带宽下需约 15 分钟）。
-
proxy_read_timeout
• 含义：从后端读取响应的最大等待时间（含后端处理时间）。• 默认值：60 秒 。
• 建议配置：
◦ API 服务：30–60 秒 。
◦ 长任务处理（如报表生成）：300 秒以上（需与后端服务超时对齐）。
🔗 三、连接保持超时（Keepalive Timeouts）
-
keepalive_timeout
• 含义：客户端连接空闲保持时间（长连接复用）。• 默认值：75 秒 。
• 建议配置：
◦ 高并发网站：15–30 秒（减少资源占用）。
◦ API 网关：30–60 秒（平衡连接复用与释放效率）。
◦ WebSocket/实时推送：60 秒以上（需配合 proxy_http_version 1.1）。
• 特殊说明：
◦ 格式支持两个参数：keepalive_timeout 30s 25s;（服务端超时 30 秒，响应头通知客户端 25 秒）。
◦ 实际生效时间取客户端与服务端设置的最小值（例：服务端设 30 秒，客户端设 20 秒 → 20 秒后连接关闭）。
⚙️ 四、其他关键超时参数
• resolver_timeout：DNS 解析超时，默认 30 秒，建议 10 秒（避免 DNS 故障拖累服务）。
• fastcgi_read_timeout：PHP-FPM 响应读取超时，类比 proxy_read_timeout，建议 30–60 秒 。
• lingering_timeout：客户端关闭连接后，Nginx 等待剩余数据的超时，默认 5 秒，建议 20 秒 。
📊 五、配置场景推荐值总结
场景 关键参数 推荐值 说明
API 网关 proxy_read_timeout 15–25 秒 快速失败，避免阻塞
client_header_timeout 5–10 秒
大文件上传/下载 client_body_timeout 300 秒+ 根据带宽调整
proxy_send_timeout 900 秒+
高并发 Web 服务 keepalive_timeout 15–30 秒 防连接泛滥
worker_connections ≥2048 配合连接数限制
WebSocket proxy_read_timeout 60 秒+ 需心跳保活
keepalive_timeout 60 秒
🛠️ 六、配置示例与调优建议
http {
# 客户端超时
client_header_timeout 10s;
client_body_timeout 30s;
send_timeout 20s;
# 连接保持
keepalive_timeout 30s 25s; # 服务端30秒，通知客户端25秒
# 代理超时
proxy_connect_timeout 5s;
proxy_send_timeout 15s;
proxy_read_timeout 30s;
server {
location /api/ {
proxy_pass http://backend;
proxy_read_timeout 25s; # API场景单独缩短
}
location /upload/ {
client_body_timeout 300s; # 大文件上传
proxy_send_timeout 900s;
}
}
}
调优步骤：
基线监控：
grep "timed out" /var/log/nginx/error.log # 定位超时报错分层测试：
• 用 curl -v 或 k6 压测，观察 request_time 与 upstream_response_time 。灰度调整：
• 先修改 1% 流量，监控错误率（5xx）和 P99 延迟。
⚠️ 七、避坑指南
超时冲突：
• 负载均衡器（如 AWS ALB）的超时需 ≥ Nginx 的 proxy_read_timeout，否则触发 504 Gateway Timeout 。资源泄漏：
• 过长的 keepalive_timeout 会导致文件描述符耗尽，需配合 worker_connections 限制。NAT 超时：
• 移动网络 NAT 表可能 60 秒回收连接，建议每 55 秒 发送心跳包。
合理配置 Nginx 超时是性能与稳定性的基石，需根据业务场景、网络环境和后端能力动态调整。核心原则：
• 客户端超时防慢连接攻击，代理超时对齐后端 SLA，连接复用平衡资源与效率。
• 持续监控日志（error.log）及指标（如 Prometheus 的 nginx_connections_active），实现闭环调优。
