请求头与超时

约 560 字大约 2 分钟

布欧-Lewyon

2026-05-15

proxy_set_header

将客户端的原始请求信息传递给后端应用：

location /api/ {
    proxy_pass http://backend:3000;

    # 必须：传递原始 Host
    proxy_set_header Host $host;

    # 传递客户端真实 IP
    proxy_set_header X-Real-IP $remote_addr;

    # 传递代理链 IP（逗号分隔）
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # 传递协议类型
    proxy_set_header X-Forwarded-Proto $scheme;

    # 传递 HTTPS 标识
    proxy_set_header X-Forwarded-Https $https;
}

变量说明

变量	值	说明
`$host`	`example.com`	客户端请求的 Host
`$remote_addr`	`203.0.113.5`	客户端真实 IP
`$proxy_add_x_forwarded_for`	`203.0.113.5, 10.0.0.1`	追加当前代理 IP
`$scheme`	`http` / `https`	客户端请求协议

添加/删除自定义头

# 添加自定义头
proxy_set_header X-Custom-Header "my-value";

# 清除一个头（设为空字符串）
proxy_set_header Accept-Encoding "";

# 传递特定的 Cookie
proxy_set_header Cookie $http_cookie;

超时配置

location /api/ {
    proxy_pass http://backend:3000;

    # 连接超时：与后端建立 TCP 连接的超时时间
    proxy_connect_timeout 30s;

    # 读取超时：从后端接收到数据的间隔时间（非总时间）
    proxy_read_timeout 60s;

    # 发送超时：向后端发送数据的间隔时间
    proxy_send_timeout 60s;
}

指令	默认值	说明
`proxy_connect_timeout`	60s	连接后端超时（通常设 5~30s）
`proxy_read_timeout`	60s	两次读取之间的最大间隔
`proxy_send_timeout`	60s	两次写入之间的最大间隔

场景化配置

# 通用 API（快速超时）
location /api/ {
    proxy_pass http://api-backend;
    proxy_connect_timeout 5s;
    proxy_read_timeout 30s;
    proxy_send_timeout 10s;
}

# 长连接/大文件（长超时）
location /export/ {
    proxy_pass http://report-service;
    proxy_read_timeout 300s;       # 5 分钟
    proxy_send_timeout 120s;       # 2 分钟
}

# SSE / Event Stream（禁用缓冲并设长超时）
location /events/ {
    proxy_pass http://event-server;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 3600s;
}

忽略请求头

# 忽略客户端的 Accept-Encoding（让后端决定压缩）
proxy_set_header Accept-Encoding "";

# 忽略客户端 Connection 头（由 Nginx 管理连接）
proxy_set_header Connection "";

小结

proxy_set_header Host $host 是标准反代的必需配置。
X-Real-IP、X-Forwarded-For、X-Forwarded-Proto 让后端知道客户端真实 IP 和协议。
超时时间根据后端延迟调整：内部 API 短超时（5~30s），文件导出长超时（300s）。
SSE/WebSocket 需设置更长的 proxy_read_timeout、关闭 proxy_buffering。
清除 Accept-Encoding 让 Nginx 或后端控制压缩，避免双层压缩。