直接调大proxy_read_timeout不是万能解法，它仅控制Nginx等待后端返回响应体首字节及后续chunk的空闲间隔；真正规避504需协同调优proxy_read_timeout、proxy_send_timeout和send_timeout，并按路径精准配置、关闭proxy_buffering、启用upstream keepalive，且后端超时须小于Nginx值。
直接调大 proxy_read_timeout 不是万能解法，它只管“后端已开始响应、但数据来得慢”这一段。真正规避大数据流式传输引发的 504，得抓住两个关键：一是让 Nginx 别在后端还没吐出第一个字节时就放弃；二是确保整个链路（上传、处理、回传）各环节超时匹配，不卡在某一处。
明确 proxy_read_timeout 的真实作用范围
它不是控制整个请求耗时，而是控制 Nginx 等待后端返回“响应体第一个字节”的最大空闲时间——也就是后端还在查库、算聚合、拉文件，却没往连接里写任何数据的那段“静默期”。报表导出、大 Excel 生成、长周期日志 PDF 渲染，都卡在这儿。
- 如果日志里出现
upstream timed out while reading response header from upstream，且$upstream_response_time很小（比如才 2 秒），说明后端根本没开始处理，问题不在proxy_read_timeout，而在proxy_connect_timeout或上游排队 - 如果后端确实在流式输出（如带
Transfer-Encoding: chunked或持续写入 body），但中间隔了太久没发新 chunk，Nginx 就会断连——这时proxy_read_timeout才是主因
按路径单独配置，别全局一刀切
全局设成 600 秒会拖垮其他接口。针对流式出口路径（比如 /api/v1/export、/stream/report）做精准配置：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 用
location ^~ /api/v1/export这类前缀匹配，避免正则开销 - 必须同时配齐三组超时：
proxy_read_timeout（等首字节+后续 chunk 间隔）、proxy_send_timeout（上传大请求体）、send_timeout（客户端下载慢时保活） - 实测 P99 耗时是基础：若导出接口 P99 是 220 秒，加 60 秒缓冲，三者统一设为 280 或 300 秒较稳妥
配套必须同步调整的参数
proxy_read_timeout 单独调大，大概率无效，因为其他环节会先断：
-
client_max_body_size和client_body_timeout：如果前端 POST 带大 JSON 或 Base64 参数，这两个值太小会导致请求还没发完就被拦（报 413，现象像超时） -
proxy_buffering off：对流式响应必须关缓冲，否则 Nginx 会攒满再吐，破坏流式语义，还可能触发缓冲区超时 -
upstream keepalive：启用长连接，减少反复建连开销，尤其当后端本身也依赖连接池时
后端与中间件也要对齐
Nginx 的耐心不能比后端还长：
- 后端框架（Spring Boot、Express、FastAPI）的请求超时应设为 Nginx 对应值的 0.8 倍左右，比如 Nginx 设 300 秒，后端设 240 秒
- 数据库连接池、HTTP 客户端（如 OkHttp、Requests）的 read timeout 也需同步放宽，否则后端自己先断，Nginx 反而收不到响应
- 若用消息队列或异步任务兜底，前端应改用轮询或 WebSocket，而非死等 HTTP 长连接——这比调超时更可持续
