Nginx反向代理配置教程：proxy_pass、请求头与常见502问题

Nginx 反向代理是 Web 部署里非常常见的配置方式。前端用户访问 Nginx，Nginx 再把请求转发给后端应用，比如 PHP-FPM、Node.js、Java 服务、WordPress 容器或内部 API。这样可以统一入口、做 HTTPS、负载均衡、缓存和访问控制。

反向代理配置看起来只是一行 proxy_pass，但实际排查时经常遇到路径转发错乱、真实 IP 丢失、请求头不完整、502 Bad Gateway 等问题。本文从基础配置讲起，整理 proxy_pass、请求头和常见 502 排查思路。

反向代理是什么

反向代理位于客户端和后端服务之间。用户并不知道真正处理请求的是哪个后端服务，只访问 Nginx 暴露的域名和端口。

用户浏览器 → Nginx → 后端应用服务

这种结构可以隐藏后端服务地址，也方便在 Nginx 层统一配置证书、限流、压缩和安全策略。

基础 proxy_pass

最简单的反向代理配置如下：

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

当用户访问 /api/ 开头的路径时，Nginx 会把请求转发到本机 3000 端口的后端服务。

proxy_pass 路径细节

proxy_pass 末尾是否带斜杠，会影响路径转发结果。比如：

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

访问 /api/users 时，转发到后端可能变成 /users。如果写成：

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

后端收到的路径可能仍包含 /api/users。实际配置时要根据后端路由设计选择。

传递 Host

很多后端应用会根据 Host 判断站点、生成链接或做安全校验。建议显式传递 Host。

proxy_set_header Host $host;

如果后端需要知道原始访问域名，这一项很重要。WordPress、多站点应用和部分登录系统尤其常见。

传递真实 IP

经过反向代理后，后端直接看到的请求来源可能是 Nginx 的内网 IP，而不是真实用户 IP。可以传递以下请求头：

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

后端需要正确读取这些头，才能记录真实访问 IP、判断 HTTPS 状态或生成正确链接。

WebSocket 支持

如果后端使用 WebSocket，需要额外设置 Upgrade 相关请求头。

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

否则 WebSocket 连接可能无法正常建立，表现为实时消息、控制台终端或在线协作功能异常。

超时配置

后端接口耗时较长时，Nginx 默认超时可能不够。可以设置连接、发送和读取超时。

proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

但不要盲目把超时调得特别大。接口长期慢，根因通常还是后端逻辑或数据库查询需要优化。

502 是什么

502 Bad Gateway 表示 Nginx 作为网关或代理时，没有从上游服务拿到有效响应。它通常不是浏览器问题，而是 Nginx 到后端之间出了问题。

常见原因包括后端服务没启动、端口写错、连接被拒绝、后端崩溃、协议不匹配、权限或 socket 路径错误。

检查后端服务

遇到 502，先确认后端服务是否正在监听对应端口。

ss -lntp | grep 3000

如果后端没有监听端口，Nginx 无法代理成功。需要启动后端服务或修正端口。

检查 Nginx 错误日志

Nginx 错误日志通常会直接告诉你连接失败原因。

tail -f /var/log/nginx/error.log

如果看到 connect() failed，多半是后端不可达；如果是 upstream timed out，可能是后端响应太慢。

协议要匹配

如果后端是 HTTP 服务，proxy_pass 就写 http://；如果后端是 HTTPS，才写 https://。协议写错也可能导致代理失败。

proxy_pass http://127.0.0.1:3000;

不要因为前台网站启用了 HTTPS，就误以为 Nginx 到后端也必须使用 HTTPS。内网代理通常使用 HTTP 即可。

配置检查和重载

修改 Nginx 配置后，先检查语法，再重载服务。

nginx -t
systemctl reload nginx

不要直接重启前不检查配置。语法错误可能导致服务无法加载新配置。

WordPress 反代注意

WordPress 放在反向代理后面时，要特别注意站点 URL、HTTPS 判断和真实 IP。否则可能出现后台跳转异常、静态资源链接不对、无限重定向等问题。

如果代理层负责 HTTPS，后端 WordPress 需要正确识别 X-Forwarded-Proto，并保持站点地址与对外访问地址一致。

常见错误

第一种错误是 proxy_pass 末尾斜杠没理解，导致路径错乱。第二种错误是没有传 Host，后端生成链接异常。第三种错误是没传 X-Forwarded-Proto，HTTPS 判断错误。第四种错误是 502 时只改 Nginx，不检查后端服务状态。

实践建议

Nginx 反向代理配置建议按流程检查：先确认 location 匹配，再确认 proxy_pass 路径，再补齐 Host、真实 IP、协议头，最后通过错误日志排查 502。配置修改后先执行 nginx -t，确认无误再 reload。

反向代理不是简单转发请求，它承担着 Web 入口的关键职责。路径、请求头和后端健康状态配置清楚，线上问题会少很多。