Nginx之proxy_set_header参数总结

原创已于 2025-07-30 00:38:18 修改 · 2.1k 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#nginx #运维 #proxy #set_header #linux

于 2025-07-30 00:36:53 首次发布

1. proxy_set_header 的基本语法

2.2.2 X-Forwarded-For

2. 3 协议与安全头

2.3.1 X-Forwarded-Proto

2.3.2 安全头

2.4 禁用或修改特定请求头

2.4.1 禁用请求头：将值设为空字符串。

2.4.2 修改请求头：设置新的值。

2.5 支持 CORS（跨域资源共享）

2.6 连接控制

2.6.1 支持 HTTP/1.1 持久连接

2.6.2 避免 Connection 头冲突

`1. proxy_set_header` 的基本语法

proxy_set_header  <HeaderName>   <HeaderValue>;

• HeaderName：需设置的请求头名称（如 Host、X-Real-IP）。

• HeaderValue：请求头的值，可以是静态字符串、Nginx 内置变量（如 $host、$remote_addr）或两者的组合

2. 核心参数解析

2.1 设置Host 头

作用：指定后端服务器的主机名。确保后端服务器接收到的 Host 头与客户端请求一致，避免因 Host 不匹配导致的 400/404 错误。若未设置，默认传递代理服务器的主机名。
配置示例：

  proxy_set_header Host $host;          # 传递客户端请求的原始 Host
  proxy_set_header Host $http_host;     # 优先使用请求头中的 Host（若存在）
  proxy_set_header Host backend.example.com;    # 强制指定固定值

场景：当后端应用依赖 Host 头进行路由或生成绝对 URL 时需配置。
示例对比：

1）未设置 proxy_set_header Host

GET / HTTP/1.1
Host: backend.example.com  # 默认由 proxy_pass 决定

2）设置 proxy_set_header Host $host：

GET / HTTP/1.1
Host: nginx.example.com    # 与客户端请求的 Host 一致

2.2 客户端真实 IP 传递

2.2.1 X-Real-IP

proxy_set_header X-Real-IP $remote_addr;

作用：将客户端真实 IP 写入 X-Real-IP 头，供后端服务器读取。

2.2.2 X-Forwarded-For

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

作用：在原有 X-Forwarded-For 头的基础上追加客户端 IP（支持多级代理）

2. 3 协议与安全头

2.3.1 X-Forwarded-Proto

proxy_set_header X-Forwarded-Proto $scheme;

作用：传递原始请求协议（HTTP/HTTPS），用于后端生成正确链接。

2.3.2 安全头

proxy_set_header X-Frame-Options "SAMEORIGIN";  # 防点击劫持
proxy_set_header X-XSS-Protection "1; mode=block";  # 防 XSS 攻击

2.4 禁用或修改特定请求头

2.4.1 禁用请求头：将值设为空字符串。

proxy_set_header User-Agent "";  # 禁用 User-Agent 头

2.4.2 修改请求头：设置新的值。

proxy_set_header Authorization "Bearer <token>";  # 修改授权头

2.5 支持 CORS（跨域资源共享）

proxy_set_header Origin $http_origin;   # 直接传递客户端Origin值‌

作用：保留客户端原始 Origin 头（适用于动态域名场景）

2.6 连接控制

proxy_set_header Connection "";

2.6.1 支持 HTTP/1.1 持久连接

问题：默认情况下，Nginx 的 Connection: close 会强制关闭与后端的连接，导致每次请求都需要重新建立 TCP 连接，增加延迟。

解决方案：如果后端服务器支持 HTTP/1.1 的持久连接（Keep-Alive），可以通过以下配置启用：

proxy_set_header Connection "";
proxy_http_version 1.1;

2.6.2 避免 Connection 头冲突

问题：如果客户端请求中包含 Connection: keep-alive，而 Nginx 默认覆盖为 Connection: close，可能导致后端服务器行为异常。

解决方案：通过清空 Connection 头，保留客户端原始意图：

proxy_set_header Connection "";

2.6.3 WebSocket 协议升级

WebSocket 特殊需求：WebSocket 需要协议升级（Upgrade: websocket），此时必须设置 Connection: upgrade：

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

注意：此时不能清空 Connection 头，否则握手失败。