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 中添加即可：
WebChat Voice Proxy
下载
⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**
location /api/ {
proxy_pass http://backend;
proxy_read_timeout 60;
}
单位为秒，默认值是 60 秒。可设为整数或带小数（如 30.5），但通常用整数更清晰。
结合常见场景调优建议
根据后端服务特性调整，避免过短导致误超时，或过长拖慢客户端感知：
- 普通 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"查看实际加载的配置片段
