反向代理是什么：Nginx 配置与排障指南

反向代理位于用户与应用服务之间：用户只访问代理地址，代理再把请求转发给 Next.js、Node.js、Strapi 等上游。它常用于统一 HTTPS、域名、负载均衡、缓存、限流和访问日志，但不会自动修复后端性能或权限问题。

目录

• 正向代理与反向代理
• 最小 Nginx 配置
• proxy_pass 末尾斜杠
• WebSocket 与长连接
• 超时不是越大越好
• 常见状态码排查
• 安全与真实 IP
• 参考资料

正向代理与反向代理

浏览器 → Nginx :443 → Next.js :3000
                    └→ Strapi :1337

最小 Nginx 配置

server {
    listen 80;
    server_name 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;
    }
}

修改后先检查再重载：

sudo nginx -t
sudo systemctl reload nginx

proxy_pass 末尾斜杠

proxy_pass 是否带 URI 会影响路径改写：

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

这里 /api/users 匹配的 /api/ 部分会被 / 替换，上游可能收到 /users。若写成不带 URI 的 proxy_pass http://127.0.0.1:1337;，请求 URI 通常按原样传递。配置路径代理时必须用 curl -v 实测，而不是凭斜杠感觉判断。

WebSocket 与长连接

需要 WebSocket 升级时：

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    location /socket/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

不要给所有普通请求无条件写死 Connection upgrade。

超时不是越大越好

location /api/ {
    proxy_pass http://127.0.0.1:1337;
    proxy_connect_timeout 5s;
    proxy_read_timeout 60s;
    proxy_send_timeout 60s;
}

proxy_read_timeout 主要约束两次读取之间的等待，不是整个响应的绝对总时长。大量 504 应先检查上游耗时、连接池和日志，而不是直接把超时改成十分钟。

常见状态码排查

• 502 Bad Gateway：上游未启动、端口错误、连接被拒绝或协议不匹配。
• 504 Gateway Timeout：代理等待上游响应超时。
• 413 Request Entity Too Large：上传大小超过 client_max_body_size。
• 301/302 循环：代理与应用对 HTTPS、Host 或基础路径判断不一致。
• 静态资源 404：proxy_pass 路径改写或应用 base path 不正确。

检查顺序：

curl -v http://127.0.0.1:3000/
curl -vk https://example.com/
sudo tail -f /var/log/nginx/error.log

先确认上游本身可访问，再检查 Nginx。Docker 场景中，127.0.0.1 指当前容器自身；不同容器通常通过自定义网络和服务名访问。相关命令见 Docker 常用命令。

安全与真实 IP

转发 X-Forwarded-* 只是传递信息。应用是否信任这些头、信任哪一层代理必须明确配置，否则攻击者可能伪造客户端 IP 或协议。TLS 证书、限流和认证也需要结合实际威胁模型设计。

参考资料

• Nginx ngx_http_proxy_module
• Nginx WebSocket proxying