Nginx 反向代理配置详解与常见坑
发布时间：2026-01-15 12:41
更新时间：2026-01-15 20:39
把跑在 3000 端口的 Node 应用挂到 80 端口域名下，标准做法是让 Nginx 做反向代理（reverse proxy，替后端接收请求再转发的中间层）。配置本身五行，坑全藏在细节里，尤其是尾斜线和请求头。
一、基础配置
在 conf.d 或 sites-enabled 里新建配置：
```
server {
listen 80;
server_name app.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
```
改完 nginx -t 检查，nginx -s reload 生效。这几个头各有用处：Host 告诉后端访问的是哪个域名；X-Real-IP 与 X-Forwarded-For 把真实客户端 IP 层层带过去。应用侧还要声明信任这些头，例如 Express 里设 app.set('trust proxy', true)，否则拿到的仍是代理地址。
二、尾斜线的差异
proxy_pass 结尾带不带斜线，行为完全不同，这是第一大坑：
- 无斜线 http://127.0.0.1:3000：location 匹配到的路径原样拼接，请求 /api/user 转给后端还是 /api/user。
- 有斜线 http://127.0.0.1:3000/：location 部分被剥掉，/api/user 变成 /user。
location / 时两者等价；location /api/ 时选错，后端会莫名 404。记忆口诀：有斜线等于路径重写。拿不准就把前后端路径对照画一遍再定。
三、header 透传漏了会怎样
漏配真实 IP 头，后端日志里全是 127.0.0.1，限速、审计、防刷功能全废。漏配 Host 头，虚拟主机型的后端会路由到默认站点，页面错乱却查不出原因，十有八九是这里。排查反向代理问题的第一步，永远是抓一条后端实际收到的请求，看头齐不齐，再谈别的。抓的办法很朴素：在后端框架里临时打印收到的头，或用 nc 监听一个端口直接看原始报文。
四、超时三件套
后端处理慢时，默认 60 秒就断开：
```
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 120s;
```
三件套各管一段：connect_timeout 管 TCP 建连，5 秒足够；send_timeout 管向上游发送请求；read_timeout 管等响应，长查询接口报 504 多数是它不够。三个值按最慢接口的实际耗时放大即可，别一刀切调成 600 秒，连接堆积反而拖垮 Nginx 自己。
配置完用 curl 看响应头确认链路。排查纪律：先分清是代理到后端断了，还是后端本身出错——绕过代理直接访问后端端口对比，两步就能定位故障在哪一侧。