proxy_read_timeout仅控制Nginx在收到响应头后等待响应体数据到达的空闲超时，超时即504；需按路径隔离配置（如普通API设20秒、导出接口据P99×1.2～1.5设值），并同步调大proxy_send_timeout、send_timeout、启用upstream keepalive，且后端超时须设为Nginx值的0.8倍。

proxy_read_timeout 是 Nginx 反向代理中控制“从后端读响应体”的空闲等待上限，不是整个请求耗时，只管一件事：后端已返回响应头之后，Nginx 等待后续响应数据到达的静默时间。超了就断连、报 504。

---

它管什么、不管什么

• ✅ 管：后端发完响应头（如 HTTP/1.1 200 OK）后，Nginx 等响应体（比如导出的 Excel 流、AI 推理结果、SSE 数据帧）到来的空闲时长
• ❌ 不管：
  • TCP 连接建立（那是 proxy_connect_timeout）
  • Nginx 把请求发给后端（那是 proxy_send_timeout）
  • Nginx 把响应传给客户端（那是 send_timeout）
  • OPTIONS 预检、WebSocket 握手、客户端上传过程

常见误判：日志里出现 upstream timed out (110: Connection timed out)，但没写明是 connect 还是 read —— 实际大概率是 proxy_read_timeout 触发的。

---

按业务路径单独设值，别全局一刀切

后端同时跑登录接口和报表导出？不能全用一个值。

• 普通 API（如 /api/user, /api/login）：设 proxy_read_timeout 20;（P99 通常 1–3 秒，留 5 倍余量够用）
• 长耗时路径（如 /api/export/, /api/submit-xml, /api/ai/infer）：单独写 location 块
  • 参考真实 P99 × 1.2～1.5：若监控显示导出 P99 是 285 秒，设 360；若波动大（30 秒～10 分钟），宁可略高，但避免盲目填 86400

示例配置：

aperture: the L402 aware reverse proxy

安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。

下载

location ^~ /api/export/ {
    proxy_pass http://backend;
    proxy_read_timeout 360;
    proxy_send_timeout 360;
    send_timeout 360;
    proxy_buffering off;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
}

---

必须同步调优的关联参数

单改 proxy_read_timeout 就像加固门却忘了关窗，效果有限甚至失效：

• proxy_send_timeout ≥ 你设的 proxy_read_timeout
  （防止大 JSON 或文件还没发完，Nginx 就先切断请求）
• send_timeout ≥ proxy_read_timeout
  （确保弱网用户下载导出文件时，Nginx 不会中途断开客户端连接）
• upstream 块启用 keepalive 32，并配 proxy_http_version 1.1 和 proxy_set_header Connection ''
  （否则每次请求都重建 TCP 连接，再长的 timeout 也没意义）

---

后端超时必须比 Nginx 小，留出缓冲

Nginx 和后端超时要错开，避免互相“等死”：

• 若 proxy_read_timeout 设为 300 秒，Tomcat 的 connectionTimeout 或 Spring Boot 的 server.tomcat.connection-timeout 应设为 240 秒左右（0.8 倍）
• 太接近（如后端设 295）→ 后端先断，Nginx 还在等，最终报 502 或 504
• 太宽松（如后端设 600）→ Nginx 先超时，后端还在跑，浪费资源且无预警

---

流式接口要额外关缓冲

对导出 Excel、SSE、实时日志、gRPC-Web 流等场景：

• 加 proxy_buffering off;
  （避免 Nginx 缓存整块响应再吐给客户端，导致“卡住假超时”）
• 可加 chunked_transfer_encoding on;
  （支持分块传输，提升大响应兼容性）
• 注意：WebSocket 或 SSE 中，proxy_read_timeout 控制的是两次数据帧之间的最大静默间隔，不是会话总时长

不复杂但容易忽略