这条排查路径解决什么
接口报 502/504 或者表现为「超时」时，问题位置可能有四处：DNS、网络链路、网关（Nginx 或负载均衡）、后端应用。curl 的 -w 能把一次请求的总耗时拆成 DNS 解析、TCP 连接、TLS 握手、首字节、传输各段，再用 --resolve 绕过 DNS 直连某台后端做对照，几分钟就能把范围收敛到其中一段，避免一上来就翻网关配置或改应用参数。
基本信息
| 适用场景 | 接口 502/504、偶发超时、上传下载慢 |
|---|---|
| 核心工具 | curl -w 耗时分解、curl --resolve 指定解析、tcpdump 与网关日志旁证 |
| 关键判据 | 哪一段耗时异常；直连后端是否同样慢 |
| 结论去向 | DNS 段异常查解析；连接段异常查链路与防火墙；TTFB 异常查应用；状态码查网关与后端分工 |
典型使用场景
- 用户报「接口超时」：先看 name_lookup 与 connect，判断是解析连通性问题还是应用慢
- 502 Bad Gateway：直连后端端口确认后端是否存活，再看网关 upstream 配置与健康检查
- 间歇性慢：同一接口连打十几次，用 -w 逐次记录分段耗时找规律
- 证书与握手问题：appconnect 段失败或报证书错误，转用 openssl s_client 深入
- 上量前后对比：发布前后各打一轮，用同一套指标确认是否引入退化
耗时分解
耗时分解
curl -sS -o /dev/null \
-w 'dns=%{time_namelookup} conn=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total} code=%{http_code}\n' \
--max-time 15 https://api.example.com/health # 一次请求拆成五段耗时绕过 DNS 直连后端对比
绕过 DNS 直连后端对比
curl -sS --resolve api.example.com:443:10.0.0.9 \
-o /dev/null -w 'via-gateway code=%{http_code} total=%{time_total}\n' https://api.example.com/health # 指定解析到某台后端
curl -sS -o /dev/null -w 'direct-backend code=%{http_code} total=%{time_total}\n' \
http://10.0.0.9:8080/health # 后端机本机直测，绕开网关旁证材料
旁证材料
tail -n 50 /var/log/nginx/error.log # 网关侧错误原因
ss -tn state established '( dport = :8080 )' | wc -l # 后端机上：当前压在 8080 的连接数
ss -s # 连接总数与 TIME-WAIT 概况
nginx -T | grep -A5 'upstream' # 确认实际生效的 upstream 与超时参数耗时字段逐项读法
| 字段 | 含义 | 正常与异常 |
|---|---|---|
| time_namelookup | DNS 解析完成用时 | 几十毫秒内；持续几百毫秒说明解析慢或有超时重试 |
| time_connect | TCP 三次握手完成用时 | 内网几毫秒、公网几十毫秒；明显偏大说明链路丢包或拥塞 |
| time_appconnect | TLS 握手完成用时（HTTPS） | 超过 200ms 要查证书链长度与会话复用 |
| time_starttransfer | 首字节到达，已包含前面所有阶段 | 即 TTFB，显著高于前面几项之和说明后端处理慢 |
| time_total | 整次请求总耗时 | 与业务超时阈值对比，判断是刚好超时还是深度超时 |
| http_code | HTTP 状态码 | 502 是网关拿到无效响应，504 是网关等后端超时，两者指向不同方向 |
快速判据：TTFB 高且后端直测也慢，问题在应用；整条链路慢但直连后端很快，问题在网关或中间网络；name_lookup 异常突出，先换 DNS 再谈应用。
不要把 502 与 504 混为一谈：502 表示网关从后端拿到无效响应（进程崩了、提前断开、协议不符），504 表示网关在超时时间内没等到后端响应（后端慢或被限流）。顺着这两个方向查，比盲目调大 Nginx 超时参数有效得多。