Nginx代理超时需分阶段精准配置：客户端连接阶段设client_header_timeout、client_body_timeout、send_timeout；后端连接阶段设proxy_connect_timeout；代理数据收发阶段设proxy_send_timeout、proxy_read_timeout；特殊路径通过location差异化覆盖。
在 Nginx 的 server 块中配置代理后端应用时，超时处理不能只靠一两个参数“一揽子解决”，必须按阶段精准设置，否则容易出现 408、502、504 等错误，且问题难以定位。
客户端连接阶段的超时控制
这部分影响的是用户到 Nginx 的链路，虽不直接涉及后端，但若在此阶段失败，请求根本不会到达后端服务。
- client_header_timeout：等待客户端发完全部请求头（如 Host、User-Agent）的最长时间。默认 60 秒，内网建议设为 10–20 秒；弱网或移动端可放宽至 30 秒
- client_body_timeout：两次接收请求体数据之间的最大间隔（不是整个上传耗时）。文件上传场景需关注，建议 15–30 秒
- send_timeout：Nginx 向客户端发送响应时，两次写操作之间的间隔上限。大文件下载或流式响应建议设为 30–60 秒
Nginx 连接后端的超时设置
这是代理链路的第一道握手关，决定请求能否成功转发出去，与后端是否可达强相关。
- proxy_connect_timeout：仅控制 TCP 三次握手完成的时间，不含 SSL 握手（HTTPS 后端时需额外预留时间）。内网设 3–5 秒，跨机房或公网建议 5–10 秒
- 超时后返回 502 Bad Gateway，日志中常见
upstream timed out (110: Connection timed out) - 该值不宜过短（误判后端不可用），也不宜过长（用户干等无反馈）
代理过程中数据收发的超时管理
连接已建立，但后端处理慢或网络抖动，这时靠这两个参数兜底，直接决定是否返回 504。
- proxy_send_timeout：Nginx 向后端发送完整请求（含 header + body）的总时限。大 payload 或文件上传建议 30–60 秒
- proxy_read_timeout：从后端读取响应的总时间（含首字节延迟和后续数据传输）。普通 API 可设 60 秒；报表导出、AI 推理等长任务建议 120–300 秒
- 注意：这两个超时是“单次连续等待”，不是累计耗时；超时即断连并返回 504 Gateway Timeout
特殊路径的差异化覆盖
全局统一设置是基础，但业务差异要求局部灵活调整，关键是要“只覆盖必要项”，避免破坏继承逻辑。
- 例如上传接口
/upload/可单独延长proxy_read_timeout 300s和client_body_timeout 300s - 健康检查接口
/api/healthz应大幅缩短，如proxy_read_timeout 2s，加快故障发现 - 所有 location 中的 proxy 超时参数，只写需要修改的，其余自动继承 http 块定义
