Nginx之proxy_set_header参数总结

目录

1. proxy_set_header 的基本语法

2. 核心参数解析

2.1 设置Host 头

 2.2 客户端真实 IP 传递

2.2.1 X-Real-IP​​

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 头冲突

2.6.3 WebSocket 协议升级

 2.7 自定义头传递​

 2.8 缓存控制​

2.9 请求头删除 

3 注意事项 

3.1 下划线

​​​​​​3.2 指令位置

3.3 空值处理 

---

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 头，否则握手失败。

 2.7 自定义头传递​

proxy_set_header X-Custom-Header "DynamicValue";

• ​​​​作用：传递业务标识、灰度发布标记等自定义信。

 2.8 缓存控制​

proxy_set_header Cache-Control "no-cache, no-store";

• ​​作用​​：强制后端禁用缓存，适用于动态内容。

2.9 请求头删除 

proxy_set_header Accept-Encoding "";  # 禁用后端压缩

• 优点：
  避免后端服务器进行压缩处理，减少 CPU 开销。
• 缺点：
  响应内容未压缩，可能导致传输数据量增加，影响网络性能（尤其对大文件或高并发场景）。

3 注意事项 

3.1 下划线

  若自定义头含下划线（如 X-My_Header），需在配置中开启：

underscores_in_headers on;

​​​​​​3.2 指令位置

 proxy_set_header 必须放在 location 或 server 块中，否则无效。

3.3 空值处理 

• 设置 proxy_set_header field ""; 会从请求中移除该头。
• 若值包含变量且变量为空，头字段会被移除，这样就能阻止它们被传递。

下面是一个完整的配置示例，它会禁用所有默认头，仅传递必要的客户端信息：

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://backend;
        
        # 禁用默认传递的头
        proxy_set_header Host "";
        proxy_set_header Connection "";
        proxy_set_header User-Agent "";
        proxy_set_header Accept "";
        proxy_set_header Accept-Encoding "";
        
        # 仅传递必要的头
        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;
        
        # 若需要授权头
        proxy_set_header Authorization $http_authorization;
    }
}