Nginx 反向代理踩坑记录

场景背景

最近在阿里云 ECS 上搭站点，后端用 Fastify 跑在 127.0.0.1:3000，前面套了一层 Nginx 做反向代理，统一处理 HTTPS、静态文件和路径转发。配置看着简单，上线后连踩三个坑，记录一下。

坑一：502 Bad Gateway

现象：浏览器访问站点，直接报 502 Bad Gateway，Nginx 错误日志：

connect() failed (111: Connection refused) while connecting to upstream

排查：curl http://127.0.0.1:3000 正常返回，说明后端没挂。问题出在 Nginx 怎么连的。

原因：我把 proxy_pass 写成了 http://localhost:3000。Nginx 里 localhost 在某些系统环境解析成了 IPv6 地址 ::1，而 Node.js 服务只监听了 IPv4 的 127.0.0.1。

修复：把 proxy_pass 改成 IP 地址：

location /api/ {
    proxy_pass http://127.0.0.1:3000;
}

坑二：文件上传 413 Request Entity Too Large

现象：前端上传图片到 OSS，走 Nginx 代理时报 413 Request Entity Too Large。

原因：Nginx 默认 client_max_body_size 是 1MB，超过就拒。

修复：在 server 或 location 块里加：

client_max_body_size 20m;

坑三：WebSocket 连接秒断

现象：配置了 WebSocket 代理，客户端连上后几秒就断开。

原因：忘配 Upgrade 和 Connection 头，Nginx 不会自动处理 WebSocket 协议升级。

修复：

location /ws/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

事后总结

三个坑本质上都是 Nginx 默认行为和安全策略导致的，不是什么复杂 bug。关键是：

1. proxy_pass 用 IP，别用 localhost；
2. 上传接口记得改 client_max_body_size；
3. WebSocket 必须声明 HTTP 1.1 和 Upgrade 头。

每次改完配置别忘 nginx -t && nginx -s reload，语法检查救过我很多次。