Nginx 反向代理实战：请求头透传与 WebSocket 支持

老涂 2026-11-08 09:18 13 ℃ 0 条

内容摘要Nginx 反向代理不只是填一个 proxy_pass。本文讲清 proxy_pass 与 upstream 的路径拼接规则，说明 Host、X-Real-IP 等请求头为何必须透传，给出静态缓存与 WebSocket 长连接配置，并整理 502/504 排查思路。

Nginx 反向代理把公网请求转发到后端，很多人配好 proxy_pass 就以为完事，上线后遇到后端拿不到真实 IP、静态资源回源、WebSocket 秒断。

一、基本原理与最小可用配置

反向代理在客户端与后端之间转发请求并回传响应，兼做 TLS 卸载与负载均衡。

1. proxy_pass 与 upstream

单后端把地址写进 proxy_pass；多实例用 upstream 定义后端池，max_fails 与 fail_timeout 控制摘除节奏。proxy_pass 末尾带不带斜杠会改变路径拼接：带斜杠替换 location 前缀，不带则原样拼接。

2. 必须传递的请求头

默认 Nginx 只向后端发 HTTP/1.0 且不带 Host。需显式补 proxy_set_header：Host 保持原域名，否则后端域名校验会失败；X-Real-IP 与 X-Forwarded-For 记录真实来源；X-Forwarded-Proto 告知原始协议。缺了这些，$_SERVER['HTTP_HOST'] 为空，跳转会拼成内网地址。

upstream app_pool { server 127.0.0.1:9000 max_fails=3 fail_timeout=30s; }
location / {
  proxy_pass http://app_pool; proxy_http_version 1.1;
  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;
}

二、缓存与 WebSocket 的场景化配置

1. 静态资源缓存

图片、CSS、JS 交给 Nginx 直接返回，减少回源。用 proxy_cache_path 定义缓存目录，proxy_cache_valid 按状态码设时长，缓存键带 $scheme$host$request_uri。

2. WebSocket 长连接

握手依赖 Upgrade 与 Connection，Nginx 需原样透传，否则后端无法升级协议；并把 proxy_read_timeout 从默认 60 秒调大。

map $http_upgrade $connection_upgrade { default upgrade; "" close; }
location /ws/ {
  proxy_pass http://127.0.0.1:9100; proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection $connection_upgrade;
  proxy_read_timeout 3600s;
}