proxy_read_timeout控制Nginx收到后端响应头后等待响应体数据到达的最大空闲时长，超时返回504；仅作用于location/server块内proxy_pass请求，不管理连接建立或请求发送，需按路径隔离配置并同步调大proxy_send_timeout、send_timeout及upstream keepalive。

在 Nginx 中，proxy_read_timeout 用于控制 Nginx 作为反向代理时，从后端服务器（如 FastAPI、Django、Node.js 等）读取响应的超时时间。它不是请求发出去就计时，而是从 Nginx 建立连接并开始接收后端响应数据起，到完整收到响应（或中间长时间无数据）为止的最大等待时长。

作用范围与生效位置

该指令必须放在 location 块或 server 块中，不能写在 http 全局块顶层（除非你明确希望所有 location 统一使用）。它只影响当前作用域下启用 proxy_pass 的请求。

• 如果后端响应头已返回但响应体传输缓慢（比如大文件下载、流式接口），超时从第一个字节开始计时
• 若后端完全无响应（连接已建立但一直不发数据），也会在此时限后断开连接并返回 504 Gateway Timeout
• 注意：它不控制 TCP 连接建立耗时（那是 proxy_connect_timeout），也不控制发送请求给后端的超时（那是 proxy_send_timeout）

基本配置写法

在对应 location 中添加即可：

location /api/ {
    proxy_pass http://backend;
    proxy_read_timeout 60;
}

单位为秒，默认值是 60 秒。可设为整数或带小数（如 30.5），但通常用整数更清晰。

WebChat Voice Proxy

⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**

下载

结合常见场景调优建议

根据后端服务特性调整，避免过短导致误超时，或过长拖慢客户端感知：

• 普通 REST API（JSON 响应快）：设为 10～30 秒 足够，太长反而掩盖后端性能问题
• 报表导出、大文件上传回调等长耗时任务：可设为 300～600 秒，并确保后端也做了相应超时放宽
• 流式响应（SSE、gRPC-Web、Chunked JSON）：需设得足够长（如 3600），同时建议配合 proxy_buffering off 和 proxy_cache off 避免缓存干扰流式传输
• 若用 proxy_http_version 1.1 + proxy_set_header Connection '' 复用连接，proxy_read_timeout 仍只针对单次响应，不影响连接复用本身

验证是否生效

修改配置后重载 Nginx：nginx -s reload。可通过以下方式确认：

• 查看 Nginx 错误日志（error_log 指定路径），触发超时会记录 upstream timed out
• 用 curl -v http://your-domain/api/slow-endpoint 观察是否在设定秒数后返回 504
• 检查运行中的配置：执行 nginx -T 2>/dev/null | grep -A5 "location.*api" 查看实际加载的配置片段