504 gateway timeout 的核心是 proxy_connect_timeout、proxy_send_timeout、proxy_read_timeout 缺乏协同导致分段截断；需按场景差异化配置三者，确保逐级放大且与后端超时匹配，并结合 keepalive、日志分析和负载均衡优化。
504 Gateway Timeout 的核心问题，不是某个参数单独太小，而是 proxy_connect_timeout、proxy_send_timeout、proxy_read_timeout 三者之间缺乏协同，导致请求在不同阶段被“分段截断”。比如后端已连上、数据也在发，但响应迟迟不来，而 proxy_read_timeout 却远小于实际业务耗时，Nginx 就会提前放弃——这不是后端挂了，是网关“误判”了。
明确各超时参数的真实作用场景
别再死记“连接、发送、读取”六个字。关键看它卡在哪一环：
- proxy_connect_timeout：Nginx 主动拨号到后端的“接通等待时间”。适用于后端刚启动、冷加载慢、或网络中间有高延迟防火墙的场景。一般调至 60–120 秒 已足够，超过 180 秒需警惕后端健康检查机制是否失效。
-
proxy_send_timeout：Nginx 把完整请求（尤其是大 Body 或文件上传）发给后端的“传输耐心值”。若接口含 Base64 图片上传或批量导入，建议设为 180–600 秒，并确保后端接收缓冲区（如 Tomcat 的
maxHttpHeaderSize）同步匹配。 -
proxy_read_timeout：最常被低估的参数。它从 Nginx 发出请求后开始计时，直到收到后端响应头（不是完整 Body）。对复杂报表、导出任务、AI 推理类接口，这个值必须覆盖后端最长处理路径——建议设为 300–600 秒，且必须略大于后端自身超时（如 Spring Boot 的
server.tomcat.connection-timeout）。
避免“超时倒挂”：前后端超时必须逐级放大
Nginx 不是孤立存在的。如果后端服务设了 30 秒超时，而你把 proxy_read_timeout 设成 20 秒，那 Nginx 每次都在后端真正出错前就先报 504，掩盖真实问题。正确顺序是：
Gateway Monitor Installer
下载
在 macOS 上通过 LaunchAgent 安装、更新、运行和移除 OpenClaw Gateway Monitor + Gateway Watchdog。适用于用户请求一键部署监控的场景。
- 数据库连接池超时（如 HikariCP
connection-timeout=30000） connection-timeout=60000） proxy_read_timeout=300 - 所有超时单位统一用秒，避免混用 ms/s/min 引发配置错误
- 在 Nginx 日志中启用
$upstream_response_time字段，观察真实耗时分布。若大量请求的该值集中在 298–299 秒，说明你设的 300 秒只是“擦边”，应果断加到 360 秒并查后端瓶颈。
配合 keepalive 和负载均衡减少连接开销
光调大超时不够，还得让连接更“省力”。否则每个请求都新建 TCP 连接，光握手就吃掉几秒，变相压缩了真正的处理时间：
- 在
upstream块中启用长连接：keepalive 32（保持 32 个空闲连接），并添加proxy_http_version 1.1和proxy_set_header Connection "" - 负载均衡策略选
least_conn而非轮询，防止某台后端因瞬时积压拖垮整条链路 - 对临时性长耗时接口（如首次初始化），可单独配 location 块，只扩大其超时，不影响其他高频接口
验证与收口：用日志确认是否真改对了
改完配置别急着 reload，先确认日志能说话：
- 在 Nginx 配置中加入增强日志格式，捕获关键字段：
log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' 'rt=$request_time uct="$upstream_connect_time" uht="$upstream_header_time" urt="$upstream_response_time"'; - 观察日志中
urt（上游响应时间）是否明显下降或稳定在合理区间；若uct突然变大，说明网络或 DNS 是新瓶颈；若urt接近你设的proxy_read_timeout，那就不是 Nginx 的问题，得立刻切到后端查 GC、锁、慢 SQL
