Web 服务器与网关 / 系统课时
502 Bad Gateway 为什么出现
502 Bad Gateway 为什么出现
代理返回 502,常见原因是没能从上游得到有效响应,未必是代理配置语法错误。本篇先复现端口拒绝,再启动已知正常后端,并对照首部前断开与应用主动返回 500,沿实际地址和失败阶段缩小范围。
学习目标
- 检查代理地址、监听与运行环境是否一致。
- 区分连接失败、上游提前断开和合法的应用错误响应。
- 用直连与经过代理的对照验证修复。
配置能通过不代表端口有服务
实验需要 Linux、curl、Python 3、Nginx 1.28,以及空闲的回环 8080、9001。先保持 9001 没有监听,创建新的 /tmp/nginx-502-lab 日志目录,把以下片段示例放入 http:
server {
listen 127.0.0.1:8080;
server_name gateway.test;
error_log /tmp/nginx-502-lab/error.log error;
location / {
proxy_next_upstream off;
proxy_pass http://127.0.0.1:9001;
}
}检查并重载后运行:
curl --noproxy '*' --resolve gateway.test:8080:127.0.0.1 -sS -o /dev/null -w 'status=%{http_code}\n' http://gateway.test:8080/health预期为 status=502,错误日志包含连接拒绝及实际上游地址。此时 nginx -t 成功只证明可加载配置;它不会为每个请求预先保证后端可用。
启动三个结果可区分的后端
以下完整程序保存为 gateway_app.py,在另一个终端执行 python3 gateway_app.py,Ctrl+C 结束:
import socket
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
class App(BaseHTTPRequestHandler):
def do_GET(self):
if self.path == "/abort":
self.connection.shutdown(socket.SHUT_RDWR)
self.connection.close() # 故意不发送 HTTP 响应首部。
return
status = 500 if self.path == "/app-error" else 200
data = b"app-error\n" if status == 500 else b"backend-ok\n"
self.send_response(status)
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
if __name__ == "__main__":
ThreadingHTTPServer(("127.0.0.1", 9001), App).serve_forever()预期结果:程序监听本机 9001。先从与 Nginx 相同的网络环境直连 /health,应得到 backend-ok;再经过代理对照:
for path in /health /abort /app-error; do
curl --noproxy '*' --resolve gateway.test:8080:127.0.0.1 -sS -o /dev/null -w 'status=%{http_code}\n' "http://gateway.test:8080$path"
done预期输出:
status=200
status=502
status=500/abort 没有有效响应首部,日志应出现上游提前关闭;/app-error 返回的是合法 HTTP 500,本例正常转发为 500,不会自动变成 502。若已有 error_page 或拦截配置,实际表现可能变化,需要核对有效配置。
地址与进程要在同一环境检查
| 证据 | 下一步 |
|---|---|
| Connection refused | 核对端口监听、进程状态和监听地址 |
| 首部前提前关闭 | 查应用崩溃、异常退出、连接处理和请求标识 |
| 无效响应首部 | 核对上游实际协议与 HTTP 响应格式 |
| 只有部分节点失败 | 按 upstream_addr 与尝试状态逐个检查 |
容器里的 127.0.0.1 指向该容器或网络命名空间,不会自动指向宿主机的另一个服务。HTTP、HTTPS、FastCGI 也不能只改端口互换;确认代理使用的协议符合上游监听。
多个上游或自动重试可能掩盖单节点故障,应记录实际尝试地址与状态。重试行为见 Nginx proxy_next_upstream。
修复后保留正反对照
恢复后端监听后,经过代理的健康路径应为 200;真正的应用错误仍应按设计呈现。增加超时不会让拒绝连接的端口突然出现服务,也不能修复无效协议。
如果响应已经开始后上游才断开,客户端可能看到截断正文,而非一个新的完整 502 页面。排查时记录失败发生在首部前还是首部后,再关联应用日志,避免把不同阶段合并成同一种现象。