nginx Troubleshooting
Nginx 504 Gateway Timeout 排查方法
Nginx 返回 504 Gateway Timeout 时，error.log 会打印 upstream timed out (110: Connection timed out)，先测后端接口真实响应时间区分偶发/持续超时，再决定是优化后端慢查询/依赖阻塞还是调整 proxy_read_timeout 与 proxy_send_timeout。
504 是 Nginx 等待上游响应超时。先确认是上游处理慢还是 Nginx 超时配置过短，再决定优化后端或调整 proxy_read_timeout。
Scenario
这篇文章解决什么问题
适用于 Nginx 返回 504 Gateway Timeout、error.log 出现 upstream timed out (110: Connection timed out) 的场景。排查核心是区分后端处理慢还是 Nginx 超时配置过短，而不是盲目调大 proxy_read_timeout。
Symptoms
典型现象
- 浏览器或客户端等待很久后收到 504 Gateway Timeout。
- Nginx error.log 出现 upstream timed out (110: Connection timed out) while reading response header。
- 后端接口偶发性超时，高峰期更频繁，低峰期正常。
- 直接 curl 后端接口能返回，但耗时接近或超过 proxy_read_timeout 默认值 60s。
Before Debugging
排查前先确认
- 确认请求是否真正到达当前 Nginx，而不是 CDN、负载均衡或另一台机器。
- 保留一次失败请求的时间、域名、路径、状态码和客户端 IP，方便和 access/error log 对齐。
- 修改配置前先导出 nginx -T 的最终合并配置，避免只看了未生效的片段。
Root Causes
常见根因分层
入口层未命中或命中了旧配置
server_name、location 优先级、SNI、默认站点和 include 顺序都会让请求落到意外配置。症状通常是本机看起来配置正确，但线上响应头、证书或错误页与预期不一致。
- 用 nginx -T 看最终配置
- 用 curl -H Host 或 openssl -servername 精确复现
- 确认 reload 成功且没有旧进程残留
反向代理到后端链路异常
502、超时、上传失败和跨域问题经常发生在 Nginx 到 upstream 的这一跳，包括端口、DNS、协议、body size、header 和超时设置。
- 从 Nginx 机器 curl upstream
- 区分 connect refused、timeout、reset、invalid header
- 检查 upstream keepalive 与后端连接限制
前置网关和应用限制不一致
CDN、Ingress、API Gateway、Nginx、应用框架可能都有独立限制。只改其中一层会造成看似随机的失败。
- 逐层确认响应来源
- 统一上传大小、超时和 CORS 策略
- 修复后从外网重新验证
Diagnosis Path
分步诊断流程
1. 固定现场，避免追着变化状态跑
先记录故障时间、影响入口、完整错误和最近一次变更。Nginx 504 Gateway Timeout 排查方法 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。
- 截图或保存完整错误文本
- 记录请求域名/IP/端口/namespace/服务名
- 标出最近发布、配置、证书、镜像或依赖变更
sudo tail -n 100 /var/log/nginx/error.log
curl -v -o /dev/null -w "%{time_total}
" http://127.0.0.1:8080/slow-api2. 在故障发生的同一位置复现
很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。
- 从报错服务所在机器执行测试
- 必要时加 Host、SNI、namespace 或代理参数
- 把成功路径和失败路径的输出并排比较
curl -v -o /dev/null -w "%{time_total}
" http://127.0.0.1:8080/slow-api
sudo nginx -T | grep -i timeout
kubectl logs <pod> -n <namespace> --tail=2003. 读取服务端证据，而不是只看客户端提示
客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。
- 查看 error.log 确认是否为 upstream timed out 错误。
- 确认后端接口真实响应时间，区分偶发和持续超时。
- 检查 proxy_read_timeout 和 proxy_send_timeout 配置是否过短。
sudo nginx -T | grep -i timeout
kubectl logs <pod> -n <namespace> --tail=2004. 做最小修复并立即回归验证
每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。
- 检查 proxy_read_timeout 和 proxy_send_timeout 配置是否过短。
- 评估后端是否存在慢查询、资源瓶颈或依赖服务阻塞。
- 区分偶发超时和持续超时，分别采取不同处理策略。
sudo nginx -T | grep -i timeout
kubectl logs <pod> -n <namespace> --tail=200Commands
排查命令与使用意图
命令 1
用于读取日志或配置文件内容。重点看时间戳附近的 ERROR、FATAL、refused、timeout 等关键词。
sudo tail -n 100 /var/log/nginx/error.log命令 2
用于从指定位置模拟真实请求。加 -v 可以看到 DNS、TCP、TLS、HTTP 头和代理连接过程，是定位链路阶段的关键证据。
curl -v -o /dev/null -w "%{time_total}
" http://127.0.0.1:8080/slow-api命令 3
用于确认 Nginx 最终加载配置和语法状态。排查时应看合并后的配置，而不是只看某个片段文件。
sudo nginx -T | grep -i timeout命令 4
用于读取容器应用日志。CrashLoop 场景优先加 --previous，因为当前轮日志可能还没来得及输出。
kubectl logs <pod> -n <namespace> --tail=200Risk Notes
容易踩坑的地方
- 不要只调大 proxy_read_timeout 而不优化后端，这只是掩盖症状，长请求会继续堆积最终拖垮后端连接池。
- 不要忽略偶发性超时，它通常是后端慢查询、锁等待或依赖服务（DB/Redis/外部 API）阻塞的前兆。
- Nginx upstream 的 keepalive 连接数如果和后端 worker 不匹配，也会表现为间歇性 504。
Verification
修复后怎么确认
- 原始故障现象已经消失，且使用同一入口重新测试 Nginx 504 Gateway Timeout 能稳定成功。
- 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
- 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。
Prevention
后续预防
- 为慢接口设置独立的 location 块和独立的 proxy_read_timeout，避免全局调大影响其他接口。
- 在后端添加请求耗时监控和慢日志，把 P99 响应时间纳入告警。
- 评估后端是否需要异步化处理（消息队列/任务队列），而不是让 HTTP 请求同步等待。
常见问题
502 和 504 有什么区别？
502 是上游连接失败或返回无效响应；504 是连接成功但等待响应超时。
调大 proxy_read_timeout 能解决吗？
只能缓解症状，不能解决后端处理慢的根因。应优先优化后端性能或扩容。
Long-tail SEO
你可能正在搜索这些报错
下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。
- nginx 504 gateway timeout
- nginx upstream timed out
- nginx proxy_read_timeout 配置
- nginx 504 后端响应慢
- nginx 502 504 区别
- nginx upstream timeout 排查
- nginx 504 kubernetes pod
- nginx proxy 超时配置调整
Need More Help
这个问题还没完全解决？
把你的报错、环境和已经尝试过的步骤发给我，后续会优先补充到排障手册。