Nginx 反向代理模板

基础反向代理与 WebSocket

proxy_pass 的 URI 拼接规则容易出错：location 和 proxy_pass 是否带尾部斜杠会影响转发路径。修改前先用一个明确的请求路径验证后端实际收到的 URI。

location /api/ {
  proxy_pass http://backend/;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

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

静态资源

预先压缩好的 .gz 文件可用 gzip_static on 直接提供；它与动态 gzip 不是同一件事。部署时要确保压缩产物和源文件同版本。

• 代理超时应按接口特性配置，流式响应不能照搬普通 API 的 read timeout。
• 不要盲目把所有响应缓存；带 Cookie 或鉴权的内容需要明确绕过。
• 改配置后先执行 nginx -t，再 reload，避免中断现有连接。

为真实客户端 IP 配置 real_ip 相关指令前，要先限定可信代理网段，不能直接信任任意 X-Forwarded-For。

上线新 location 前用 curl -I 和 WebSocket 客户端分别验证缓存头、重定向和升级握手，避免只测普通 GET。