报表导出类接口504错误主因是proxy_read_timeout和proxy_send_timeout默认60秒过短，须按P99耗时+余量（如300秒）在location块中协同调大，并同步放开后端及中间件限制。
报表导出类接口在生产环境常因后端计算耗时长、响应体流式生成慢，导致 Nginx 提前断连，返回 504 错误。这不是后端挂了，而是 proxy_read_timeout 和 proxy_send_timeout 默认值（均为 60 秒）远低于真实业务耗时，必须协同调优，并落实到具体路径级配置。
先确认真实瓶颈在哪一环
两类超时作用不同，不能混用或只调一个：
- proxy_read_timeout：控制 Nginx 等待后端返回响应体“第一个字节”及后续数据的空闲间隔——报表导出中，后端常花几十秒查库/聚合，期间无任何输出，Nginx 就会超时；
- proxy_send_timeout：控制 Nginx 向后端发送完整请求体（如复杂筛选条件 JSON）的耐心程度——若导出请求带大 body 或需流式上传参数，该值不足也会中断转发。
按业务实测值设合理上限
不靠猜测，用数据驱动：
- 查近一周 /api/v1/export 或 /report/download 接口的 P99 响应耗时（含后端处理+首字节生成）；
- 若 P99 是 240 秒，加 30～60 秒余量（应对 DB 慢查询、GC 暂停、网络抖动），取 300 秒较稳妥；
- 若请求体较大（如含 Base64 参数或千行 JSON），同步估算上传时间：例如 5MB body，后端接收速率约 2MB/s，则 proxy_send_timeout 至少设为 180 秒（预留缓冲）。
必须在 location 块中显式配置
全局设置易被覆盖，且会误伤其他接口。针对导出路径单独配置最安全：
location ^~ /api/v1/export {
proxy_pass http://backend;
proxy_read_timeout 300;
proxy_send_timeout 300;
send_timeout 300;
client_max_body_size 200m;
client_body_timeout 300;
}
- send_timeout 要同步调大，避免客户端弱网下载中途断连；
- client_max_body_size 和 client_body_timeout 必须匹配，否则请求还没发完就被 Nginx 拦截（413 错误），和超时无关但现象相似；
- 开启 proxy_buffering off 可减少 Nginx 缓存开销，适合流式导出场景。
别忘了后端与中间件的配套放开
Nginx 调大只是前端一环，后端限制不解除照样失败：
- Spring Boot：spring.servlet.multipart.max-request-size 和 max-file-size 需 ≥ 200m；
- Python（Gunicorn）：--limit-request-body 参数要放开；
- Node.js（Express）：body-parser 的 limit 选项需调整；
- WAF 或 API 网关：检查是否对长请求或大 body 做了默认拦截，需临时放行导出路径。
