Nginx 反向代理配置教程：proxy_pass 转发设置步骤与 502/404 常见问题排查-速维云

什么是 Nginx 反向代理？适用场景说明

反向代理是指由 Nginx 接收用户的访问请求，再把请求转发给后端的实际服务（比如运行在 3000 端口的 Node 应用、8080 端口的 Java 服务或其他内部服务器），并把后端的响应返回给用户。对用户来说，访问的始终是 Nginx 所在的域名和端口，后端服务的真实地址完全被隐藏。

这个功能在实际运维中使用频率非常高：给前后端分离的网站做接口转发、把多个子域名或路径路由到不同的服务、为 WebSocket 应用做长连接转发、以及在只有一台服务器的情况下让多个服务共用 80/443 端口等。相比直接暴露后端端口，反向代理还能统一做 HTTPS、限流和访问控制，是站长和中小团队最实用的 Nginx 技能之一。

开始之前请确认：服务器上已安装 Nginx（nginx -v 可查看版本），后端服务已启动并能在本机访问，同时建议先备份现有的 Nginx 配置文件（cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak），避免改错配置后无法快速恢复。

第一步：创建反向代理配置文件

推荐为每个站点单独建一个配置文件，而不是直接改主配置。在 /etc/nginx/conf.d/ 目录下新建文件（Debian/Ubuntu 也可放在 /etc/nginx/sites-available/ 下再做软链接）：

sudo nano /etc/nginx/conf.d/app.conf

写入以下最基础的转发配置：

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;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

逐项说明：listen 80 表示监听 80 端口；server_name 填你的域名，需要先在域名服务商处把该域名解析到这台服务器的 IP；proxy_pass 指向后端服务地址，这里假设应用跑在本机 3000 端口，如果后端在其他服务器，就写对方的内网 IP 和端口；四条 proxy_set_header 用于把用户的真实 IP、访问协议等信息传给后端，很多应用（如登录日志、CDN 场景）依赖这些头，建议默认都加上。

第二步：检查配置并重载 Nginx

配置写完后，先执行语法检查，确认没有写错：

sudo nginx -t

如果输出 syntax is ok 和 test is successful，说明配置无误，再执行重载让新配置生效：

sudo systemctl reload nginx

这里建议用 reload 而不是 restart：reload 是平滑重载，不会中断正在处理的请求，业务影响更小。如果 nginx -t 报错，根据提示的行号回到配置文件修正，不要带着错误配置重载。重载后用浏览器访问你的域名，正常情况下应该能看到后端应用的页面。

第三步：按路径转发到不同后端（可选）

一个常见需求是：主站走一个服务，接口或管理后台走另一个服务。利用多个 location 块即可实现按路径分流：

server {
    listen 80;
    server_name app.example.com;

    location /api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

注意 proxy_pass 末尾斜杠的区别，这是最容易踩的坑：写 http://127.0.0.1:8080/（带斜杠）时，访问 /api/user 会被转发为后端的 /user，即去掉 /api 前缀；不带斜杠写 http://127.0.0.1:8080 时，后端收到的路径是完整的 /api/user。选哪种取决于后端应用的路由设计，如果配完发现接口 404，首先检查这里。

第四步：为反向代理配置 HTTPS（可选）

如果站点已部署 SSL 证书，可以在同一个 server 块中监听 443 端口，让转发走加密通道：

server {
    listen 443 ssl;
    server_name app.example.com;
    ssl_certificate     /etc/nginx/ssl/app.example.com.pem;
    ssl_certificate_key /etc/nginx/ssl/app.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

证书路径以你实际部署的位置为准，可参考证书服务商或宝塔面板的部署说明。由于后端在本机内网，proxy_pass 用 http 即可，用户到 Nginx 之间是 HTTPS。证书续期后记得执行 sudo nginx -t && sudo systemctl reload nginx 让新证书生效。如果没有现成证书，可先用 Let's Encrypt 等免费证书工具签发，具体以官方文档为准。

常见问题（FAQ）

1. 访问域名返回 502 Bad Gateway 怎么办？502 表示 Nginx 无法连接到后端服务。按顺序排查：后端服务是否在运行（systemctl status 你的应用 或 curl http://127.0.0.1:3000 测试）；proxy_pass 里的 IP 和端口是否写对；后端是否只监听了 127.0.0.1 而 Nginx 走了别的地址。如果后端在其他服务器，还要确认两台机器之间的内网端口连通性以及防火墙规则放行。

2. 页面能打开但接口报 404 或路径异常？大概率是 proxy_pass 末尾斜杠问题导致路径前缀处理不符合预期，回看第三步的说明调整写法。另外检查后端应用是否有 base path 配置需要同步修改。

3. WebSocket 连接不上或频繁断开怎么办？WebSocket 需要额外的升级头配置，在对应的 location 中加入：proxy_http_version 1.1;、proxy_set_header Upgrade $http_upgrade;、proxy_set_header Connection "upgrade";，并适当调大 proxy_read_timeout（如 300s 以上），避免长连接被默认超时切断。

4. 上传大文件时报 413 错误？这是 Nginx 默认的请求体大小限制（通常 1MB）导致的。在 server 或 http 块中加入 client_max_body_size 50m;（按需调整大小），重载配置即可。

5. 改完配置重载后没有生效？先确认 nginx -t 通过且执行了 reload；再检查是否有多个配置文件里定义了相同的 server_name，Nginx 只会使用先加载的那个；浏览器端可用无痕模式或强制刷新（Ctrl+F5）排除缓存干扰。