访问网站时蹦出 413、502、504 这三种错误码,很多人第一反应是"服务器挂了",其实是三件完全不同的事:413 是请求太大,进门就被挡了;502 是网关拿不到后端响应,后端"人不在";504 是网关等后端超时,后端"人在但不回话"。分不清这三者,排查就会南辕北辙——明明该查 Nginx 请求体限制,却跑去重启应用,白折腾半天。
这篇文章把 413、502、504 放在一起对比,讲清楚每个错误码是谁返回的、典型触发场景、最常见的几类原因,以及最容易上手的排查顺序。三种错误都会涉及 Nginx/反向代理、后端应用、防火墙/负载均衡等多层,因此文章会给出分层定位的思路,让你能快速判断"问题出在哪一层",而不是盲目重启。
文中的超时阈值、请求体大小限制等都是常见经验值,需要结合你的业务实际情况调整。涉及的配置修改都会给出校验和回滚方式,因为改错一层配置,可能把整个站点搞挂。
一、先分清谁在报错:一张对照表
这三个状态码都属于 4xx/5xx,但语义和来源差别很大。先用一张表立个全局印象:
| 错误码 | 名称 | 谁返回的 | 一句话含义 | 典型触发 |
|---|---|---|---|---|
| 413 | Payload Too Large | Nginx/网关 | 请求体超过允许大小 | 上传大文件、提交超长表单 |
| 502 | Bad Gateway | Nginx/网关 | 连不上后端或后端返回无效响应 | 后端进程挂了、端口错、被防火墙拦 |
| 504 | Gateway Timeout | Nginx/网关 | 连上后端但响应超时 | 后端处理慢、数据库慢查询、超时设太短 |
关键认知:413、502、504 通常都由反向代理(Nginx、负载均衡器、CDN)而不是后端应用返回。也就是说,看到这类错误时,你的第一现场是代理层,而不是应用代码。例外也存在:后端应用自己也可能返回 502/504,但在 Web 架构里这两种码绝大多数是网关写进响应的。
再补一个重要区别:502 是"连接/响应层面失败",504 是"时间层面失败"。502 意味着你根本没拿到有效响应(连不上、连接被重置、后端进程不存在),504 意味着你连上了但等太久。这个区别决定了排查方向完全不同。
顺带说一个更底层的判断方法:看 Nginx 访问日志里同一时刻的 upstream_status 字段(需要在 log_format 里显式加入),它能告诉你上游到底返回了什么。如果上游返回了 200 而客户端看到 502,说明问题出在 Nginx 读响应阶段;如果上游压根没有状态记录,就是连接根本没建立。掌握这个字段,比只看客户端看到的状态码要精确得多。
二、413:请求体太大
413 最常见于文件上传。Nginx 默认的请求体大小限制是 1MB(client_max_body_size 1m),超过就返回 413。很多人第一次传大于 1MB 的图片就中招。
根因通常有三层限制,要逐层放开:
- Nginx 层:
client_max_body_size。 - 后端应用层:如 PHP 的
upload_max_filesize、post_max_size,Java 的spring.servlet.multipart.max-file-size等。 - 中间层:CDN、云负载均衡、WAF 往往也有请求体限制,需要同步调整。
server {
listen 80;
server_name upload.example.com;
# 允许最大 100MB 请求体(经验值,按业务定)
client_max_body_size 100m;
# 大文件上传时相应放宽超时,避免传到一半被掐
client_body_timeout 120s;
location /upload/ {
proxy_pass http://backend;
proxy_request_buffering off; # 边收边转,减少磁盘缓冲,适合大文件
}
}
风险提示:client_max_body_size 一把开太大,会让恶意客户端用超大请求耗尽内存/磁盘。建议按业务最大值设,并配合 client_body_buffer_size、client_body_temp_path 控制缓冲。改完先 nginx -t 校验再 reload,保留旧配置以便回滚。
排查 413 的要点:
# 1. 确认是不是 Nginx 报的(看 error.log)
sudo tail -f /var/log/nginx/error.log
# 典型:client intended to send too large body: 5242880 bytes
# 2. 顺手确认返回码和 Server 头
curl -I -X POST --data-binary @bigfile.bin http://upload.example.com/upload/
# 看 HTTP/1.1 413 与 Server: nginx
如果 Nginx 放开了还是 413,就去看 CDN/WAF 的配置,以及后端应用自身的上传限制。
三、502:网关连不上后端
502 的语义是"网关没法从上游拿到有效响应"。常见原因按出现频率排:
- 后端进程真的挂了:应用崩溃、被 OOM Killer 杀掉、容器退出。
- 端口或地址配错:
proxy_pass http://127.0.0.1:8080但后端监听在8081。 - 后端还没来得及启动:发布重启期间短暂 502。
- SELinux/防火墙拦截:RHEL 系 SELinux 默认禁止
httpd/nginx往外连,需要httpd_can_network_connect。 - 后端响应头不合法:后端返回了畸形响应,Nginx 判定为无效。
# 1. 看 Nginx 错误日志,最关键是这一行
sudo tail -f /var/log/nginx/error.log
# 典型:connect() failed (111: Connection refused) while connecting to upstream
# 或:upstream prematurely closed connection while reading response header
# 2. 直接从 Nginx 所在机器 curl 后端,验证后端是否活着
curl -v http://127.0.0.1:8080/health
# 3. 看后端进程和端口是否在
sudo ss -lntp | grep 8080
ps -ef | grep -i java | grep -v grep
# 4. RHEL 系若有 SELinux,查是否被拦
sudo ausearch -m avc -ts recent
变更风险提示:如果是"SELinux 拦截"导致的 502,正确的处理是 sudo setsebool -P httpd_can_network_connect on,而不是直接 setenforce 0 关闭 SELinux。关闭 SELinux 会让系统失去一层重要防护,属于典型的"用消除警报代替解决问题"。若确实临时关闭排查,务必记得 setenforce 1 恢复。
四、504:网关等后端超时
504 表示网关和后端之间的连接建立了,但后端在规定时间内没返回。根因分两类:后端真的慢,或超时阈值设得太短。
location /api/ {
proxy_pass http://backend;
proxy_connect_timeout 5s; # 与后端建立连接的超时
proxy_send_timeout 60s; # 向后端发送请求的超时
proxy_read_timeout 60s; # 等待后端响应的超时(504 最常和它相关)
send_timeout 60s; # 向客户端发送响应的超时
}
四个超时的分工要记牢:connect 管建连,send 管发请求,read 管等响应,send_timeout 管回给客户端。504 多数是 proxy_read_timeout 触发的。
排查 504 的顺序:
# 1. 确认是超时(error.log 里会有 timed out)
sudo tail -f /var/log/nginx/error.log
# 典型:upstream timed out (110: Connection timed out) while reading response header
# 2. 直接量后端接口耗时,判断是后端慢还是阈值短
time curl -o /dev/null -s http://127.0.0.1:8080/api/slow
# 3. 若后端是数据库驱动,查慢查询
# MySQL 示例:看慢日志开关与最近的慢 SQL
# SHOW VARIABLES LIKE 'slow_query_log';
如果后端确实慢(比如某个接口要 90s),你有两个方向:优化后端(首选,加索引、异步化、缓存),或适度调大 proxy_read_timeout(治标)。注意:把超时调到 600s 以上只是在掩盖问题,还可能让 Nginx 的连接被长期占用,反而拖垮整体,一般建议调超时不超过 120s(经验值),同步去优化后端。
五、三步定位法:先分层,再定位
三种错误都要遵循"从外到内、从上到下"的排查思路,别一上来就改代码。
第一步,看 Nginx 错误日志。 这是信息量最大的一步,90% 的线索在 error.log 里:
# 实时看错误日志
sudo tail -f /var/log/nginx/error.log
# 统计一段时间内各类上游错误出现次数
sudo grep -E "upstream|too large" /var/log/nginx/error.log | \
awk '{print $NF}' | sort | uniq -c | sort -rn | head
第二步,看后端应用日志。 如果 Nginx 日志说"连接被拒",就去后端看进程在不在、日志有没有启动报错;如果说"读响应超时",就去后端看是不是在处理某个请求时卡住。
第三步,验证链路每一跳。 从 Nginx 机器 curl 后端端口、从后端 curl 数据库/下游,逐跳确认。用 curl -v 关注连接阶段和响应阶段分别卡在哪:
# 分阶段计时,定位是连接慢还是响应慢
curl -w "连接: %{time_connect}s 首字节: %{time_starttransfer}s 总计: %{time_total}s\n" \
-o /dev/null -s http://127.0.0.1:8080/api/test
六、易混点与预防
易混点一:502 和 504 都可能"看起来像服务挂了",但 502 是连不上,504 是等不到。 用 error.log 里的 connection refused(502)和 timed out(504)区分,一目了然。
易混点二:应用重启期间会有短暂 502。 这是正常现象,但如果持续 502,就说明后端没起来,去看启动日志。
易混点三:413 不一定是上传。 一些客户端把大 JSON 放在 POST 体里提交,也会触发 413,不只是文件上传。
预防:给后端加健康检查、配置 proxy_next_upstream 做多实例故障转移、发布用优雅停机和滚动更新减少 502、给关键接口设合理的超时和重试(注意重试要幂等)。这些措施能显著降低线上出现 502/504 的频率。
还有一点常被忽略:这三种错误码在浏览器里的表现会"骗人"。有些站点用自定义错误页把 5xx 包装成"页面走丢了",用户截图给你时看不出到底是哪个码;还有些 CDN 会把上游的 504 改成自己的 502 返回。所以排查时不要只信用户截图,一定要落到服务器日志和 curl 的真实返回码上。另外,如果同一个接口偶尔 502、偶尔 504,说明后端处于"半死"状态——进程还在、端口还在监听,但被某些慢请求占满了工作线程,新连接要么排队超时(504)、要么被拒绝(502),这种情况优先查后端的线程池/连接池配置和慢查询,而不是反复调 Nginx 超时。
常见问题
Q1:502 和 504 到底哪个是"后端挂了"?
502 更接近"后端不可达"(进程没了、端口不通、连接被拒);504 是"后端可达但太慢"。后端进程挂掉通常报 502,后端卡死通常报 504。
Q2:为什么上线新版本时总出现 502?
应用停止/启动期间端口短暂不可用。用优雅停机、多实例滚动发布、或在 Nginx 配置 proxy_next_upstream 把请求转给健康实例,都能减少。
Q3:413 改了 Nginx 还是报错,怎么回事?
前面可能还有 CDN/WAF/云负载均衡,它们也有请求体上限,需要一并调整;同时确认后端应用自身的上传限制(如 PHP 的 post_max_size)是否放开。
Q4:把 proxy_read_timeout 调很大能解决 504 吗?
只能掩盖问题。超时调大会让慢请求长期占用连接,建议先优化后端(索引、缓存、异步),超时作为兜底,一般不超过 120s(经验值)。
Q5:怎么快速判断错误是 Nginx 还是后端返回的?
看响应头 Server,并查 Nginx error.log。如果 error.log 里有对应的 upstream 记录,基本就是网关侧产生并返回的。
总结
- 413 是请求体过大,改
client_max_body_size并同步放开 CDN/WAF 和后端的上传限制;三层都要看,别只改一处。 - 502 是网关连不上或拿不到后端有效响应,优先查后端进程、端口、SELinux/防火墙,
error.log里的connection refused是关键线索。 - 504 是网关等后端超时,区分"后端真慢"和"超时设太短",超时调大是治标、优化后端才是治本。
- 统一排查顺序:看 Nginx
error.log→ 看后端应用日志 → 逐跳curl验证;curl -w的分阶段计时能快速定位卡在哪。 - 改任何代理配置都要先备份、
nginx -t校验、reload生效;发布侧用优雅停机和滚动更新,能从源头减少 502。
企业QQ咨询




