504错误主因是Nginx默认proxy_read_timeout=60秒过短，需按业务最大耗时+20%合理调大，并同步调整proxy_connect_timeout、proxy_send_timeout及云负载均衡超时；根本解法是改同步导出为“提交→异步执行→查状态→下载”四步架构，避免阻塞Worker进程。
导出接口超时是 Nginx 默认代理超时在作怪
504 gateway timeout 不是你的代码卡死，而是反向代理（通常是 nginx）等不到后端响应，主动切断了连接。默认 proxy_read_timeout 是 60 秒，而大数据导出（如百万行 excel、复杂报表 pdf）很容易超过这个阈值。
关键不是“加长等待时间”，而是先确认瓶颈在哪——是数据库查太慢？内存不足导致 GC 拖延？还是生成文件时阻塞主线程？
-
proxy_read_timeout必须调大，但别盲目设成 3600；建议按业务预期最大耗时 +20% 设置，比如预估最慢 8 分钟，就设proxy_read_timeout 600 - 同时检查
proxy_connect_timeout和proxy_send_timeout，三者需协同调整，否则可能卡在连接或上传阶段 - 如果用的是云服务（如阿里云 SLB、AWS ALB），它们自身也有独立的空闲超时设置（常为 60–300 秒），必须同步修改，否则 Nginx 调了也没用
避免在 Web 请求里直接生成大文件
同步导出大文件会占满一个 Worker 进程，不仅拖慢当前请求，还可能引发连接池耗尽、CPU 尖峰、OOM Killer 杀进程等问题。这不是超时问题，是架构误用。
- 把导出任务拆成「提交 → 异步执行 → 查询状态 → 下载」四步，用消息队列（如 RabbitMQ、Redis Stream）或后台任务框架（Celery、Sidekiq、Laravel Horizon）接管耗时操作
- 前端轮询
/api/export/status?id=xxx，后端只返回 JSON 状态（"pending"/"success"/"failed"），不走文件流 - 成功后生成带签名的临时 URL（如
/export/xxx.xlsx?token=abc123），有效期 1 小时，由静态文件服务（Nginx 的alias或对象存储直链）提供下载，彻底绕过应用层
Python Flask/FastAPI 导出卡顿的典型陷阱
很多人用 io.BytesIO + openpyxl 或 pandas.DataFrame.to_excel() 在内存拼大文件，看似简单，实则极易触发内存暴涨和 GIL 阻塞。
- 不要用
df.to_excel(BytesIO(), ...)处理 >10 万行数据；改用流式写入：用xlsxwriter.Workbook(..., {'in_memory': True})或分块写入 CSV（更轻量） - Flask 中禁用
Response直接返回大字节流，务必加direct_passthrough=False并设置content_length，否则 Nginx 可能因无法计算长度而提前断连 - FastAPI 若用
StreamingResponse，确保 generator 函数内部不包含 DB 查询或复杂计算——这些必须前置完成，流只负责吐已准备好的 chunk
导出路径没走缓存，反而压垮了应用服务器
当多个用户同时点同一个报表导出，又没做去重或缓存，就会反复触发相同查询+生成逻辑，CPU 和数据库瞬间拉满。
- 对参数确定、时效性要求不高的导出（如日汇总报表），用 Redis 缓存结果文件路径或 S3 key，缓存 TTL 设为 1 小时，命中即跳转下载
- 加一层轻量锁：用
SET resource:export:20240501 NX EX 300防止重复生成，失败则轮询等待 - 导出文件名别用时间戳，改用参数哈希（如
report_user_active_7d_{md5('2024-05-01,2024-05-31')}），便于缓存识别和复用
真正难的不是调大 timeout，而是判断该不该让它等——多数情况下，用户并不需要实时看到“正在导出”，只需要知道“稍后能拿到”。把同步阻塞变成异步契约，比修 Nginx 配置管用十倍。
