Nginx 反向代理配置备忘：从入门到避坑

Nginx 作为反向代理是日常运维中最常用的功能之一。看似简单的几行配置，实际藏着不少坑。本文整理我在项目中反复踩过的几个关键点。

proxy_pass 的斜杠陷阱

这是最容易出错的配置。关键区别在于 proxy_pass 的 URI 是否带路径：

# 情况 A：proxy_pass 带路径 /api/
location /api/ {
    proxy_pass http://backend/api/;
}
# 请求 /api/user → 转发到 http://backend/api/user

# 情况 B：proxy_pass 不带路径
location /api/ {
    proxy_pass http://backend;
}
# 请求 /api/user → 转发到 http://backend/api/user

简单记法：带路径就替换前缀，不带路径就原样转发。搞反了就会 404 排半天。

超时参数调优

默认的 proxy_read_timeout 是 60 秒，对于长时间处理的接口（如导出报表）可能不够。但不要一刀切设成 300 秒——应该根据接口类型分层配置。核心接口短超时 + 熔断，慢接口单独加大并用队列异步化。

WebSocket 代理

WebSocket 代理需要额外设置 Upgrade 和 Connection 头，否则握手会失败。标准配置如下：

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

真实 IP 传递

经过代理后，后端拿到的 $_SERVER['REMOTE_ADDR'] 是代理服务器的 IP，需要配置：

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

并在后端从 X-Forwarded-For 头中取真实 IP（注意取最左边第一个）。