Nginx教程

Appearance

代理请求头设置 ​

正确设置代理请求头对于反向代理的正常运行至关重要。

常用请求头 ​

Host头 ​

nginx
location / {
    proxy_pass http://backend;
    proxy_set_header Host $host;
}

说明：

  • 设置请求的主机名
  • 后端服务器根据Host头识别虚拟主机
  • $host变量包含客户端请求的主机名

X-Real-IP头 ​

nginx
location / {
    proxy_pass http://backend;
    proxy_set_header X-Real-IP $remote_addr;
}

说明：

  • 传递真实客户端IP
  • 后端服务器可以获取真实客户端IP
  • $remote_addr变量包含客户端IP

X-Forwarded-For头 ​

nginx
location / {
    proxy_pass http://backend;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

说明：

  • 记录请求经过的所有代理服务器
  • $proxy_add_x_forwarded_for变量自动追加IP
  • 格式：客户端IP, 代理1IP, 代理2IP

X-Forwarded-Proto头 ​

nginx
location / {
    proxy_pass http://backend;
    proxy_set_header X-Forwarded-Proto $scheme;
}

说明：

  • 传递原始协议（http/https）
  • 后端服务器可以判断原始协议
  • $scheme变量包含协议类型

完整请求头配置 ​

标准配置 ​

nginx
location / {
    proxy_pass http://backend;

    # 标准请求头
    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;
}

扩展配置 ​

nginx
location / {
    proxy_pass http://backend;

    # 标准请求头
    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;

    # 扩展请求头
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header X-Forwarded-Server $host;
}

自定义请求头 ​

添加自定义头 ​

nginx
location / {
    proxy_pass http://backend;

    # 添加自定义头
    proxy_set_header X-Custom-Header "custom-value";
    proxy_set_header X-Request-ID $request_id;
    proxy_set_header X-User-Agent $http_user_agent;
}

使用变量 ​

nginx
location / {
    proxy_pass http://backend;

    # 使用变量
    proxy_set_header X-Request-Time $time_local;
    proxy_set_header X-Request-Method $request_method;
    proxy_set_header X-Request-URI $request_uri;
}

传递原始请求头 ​

传递所有原始头 ​

nginx
location / {
    proxy_pass http://backend;

    # 传递所有原始请求头
    proxy_pass_request_headers on;
}

不传递某些头 ​

nginx
location / {
    proxy_pass http://backend;

    # 不传递某些头
    proxy_set_header Accept-Encoding "";
}

隐藏后端响应头 ​

隐藏特定响应头 ​

nginx
location / {
    proxy_pass http://backend;

    # 隐藏后端响应头
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;
    proxy_hide_header X-AspNet-Version;
}

修改响应头 ​

nginx
location / {
    proxy_pass http://backend;

    # 修改响应头
    proxy_hide_header Server;
    add_header Server "nginx";
}

WebSocket请求头 ​

WebSocket配置 ​

nginx
location /ws/ {
    proxy_pass http://backend;

    # WebSocket请求头
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

HTTPS请求头 ​

SSL终端配置 ​

nginx
server {
    listen 443 ssl;
    server_name proxy.example.com;

    ssl_certificate /etc/nginx/ssl/proxy.crt;
    ssl_certificate_key /etc/nginx/ssl/proxy.key;

    location / {
        proxy_pass http://backend;

        # HTTPS请求头
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-SSL on;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

认证请求头 ​

Basic认证 ​

nginx
location / {
    proxy_pass http://backend;

    # Basic认证
    proxy_set_header Authorization $http_authorization;
}

Token认证 ​

nginx
location / {
    proxy_pass http://backend;

    # Token认证
    proxy_set_header X-Auth-Token $http_x_auth_token;
}

CORS请求头 ​

CORS配置 ​

nginx
location / {
    proxy_pass http://backend;

    # CORS请求头
    proxy_set_header Origin $http_origin;
    proxy_set_header Access-Control-Request-Method $http_access_control_request_method;
    proxy_set_header Access-Control-Request-Headers $http_access_control_request_headers;
}

日志记录 ​

记录请求头 ​

nginx
log_format proxy '$remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$http_x_forwarded_for" '
                  '"$http_authorization"';

access_log /var/log/nginx/proxy.access.log proxy;

完整示例 ​

生产环境配置 ​

nginx
server {
    listen 80;
    server_name proxy.example.com;

    access_log /var/log/nginx/proxy.access.log;
    error_log /var/log/nginx/proxy.error.log;

    location / {
        proxy_pass http://backend;

        # 标准请求头
        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;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;

        # 性能相关
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;

        # 缓冲设置
        proxy_buffering on;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
        proxy_busy_buffers_size 8k;

        # 隐藏后端信息
        proxy_hide_header X-Powered-By;
        proxy_hide_header Server;
    }
}

常见问题 ​

后端获取不到真实IP ​

原因： 未设置X-Real-IP或X-Forwarded-For头

解决：

nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

后端无法识别HTTPS ​

原因： 未设置X-Forwarded-Proto头

解决：

nginx
proxy_set_header X-Forwarded-Proto $scheme;

WebSocket连接失败 ​

原因： 未正确设置Upgrade和Connection头

解决：

nginx
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

总结 ​

代理请求头设置的关键点：

  • Host：传递主机名
  • X-Real-IP：传递真实客户端IP
  • X-Forwarded-For：记录代理链
  • X-Forwarded-Proto：传递原始协议
  • 自定义头：根据需求添加
  • 隐藏头：隐藏后端敏感信息
  • WebSocket：特殊配置支持

正确设置代理请求头，确保反向代理正常工作。

Copyright © 2025-2026 京公网安备 11010102000001号 京ICP备2024078128号-1