Nginx proxy_pass 怎么在代理过程中注入自定义请求头-Nginx-PHP中文网

nginx中proxy_set_header可自定义转发请求头，支持静态值、变量及组合；需与proxy_pass同级配置，可覆盖默认头（如host）、清除头（设为空），变量名大小写敏感且需注意作用域和引号使用。

nginx proxy_pass 怎么在代理过程中注入自定义请求头

在 Nginx 中使用 proxy_pass 时，可以通过 proxy_set_header 指令向后端服务器注入自定义请求头。默认情况下，Nginx 会过滤掉部分客户端原始头（如 Host、Connection），但你可以显式设置任意头字段，包括静态值、变量或组合内容。

基础写法：添加固定值的请求头

在 location 或 server 块中添加：

location /api/ {
    proxy_pass https://backend.example.com/;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Request-ID $request_id;  # 需启用 ngx_http_core_module 的 request_id 模块
    proxy_set_header X-Proxy-By "nginx";
}

注意：$request_id 是 Nginx 内置变量（需开启 random_index 或更常见的是依赖 ngx_http_core_module，实际可用需确认版本；较新版本（1.11.0+）默认支持 $request_id）。

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

动态注入：用变量构造请求头

可组合多个变量生成有意义的头，例如带时间戳的追踪标识：

map $time_iso8601 $trace_id {
    ~^(?<y>\d{4})-(?<m>\d{2})-(?<d>\d{2})T(?<h>\d{2}):(?<i>\d{2}) $y$m$d$h$i;
}
# 然后在 location 中：
proxy_set_header X-Trace-ID "$trace_id-$pid-$connection";
</i></h></d></m></y>

常用变量包括：$remote_addr、$http_user_agent、$host、$request_uri、$scheme 等。注意变量名大小写敏感，$http_x_custom 可读取客户端发送的小写 X-Custom 头（Nginx 自动转为小写下划线格式）。

覆盖或清除默认头

Nginx 默认会重写 Host 为 proxy_pass 指定的域名。若需保留原始 Host，显式设置：

proxy_set_header Host $host;（用客户端请求的 Host）
proxy_set_header Host $http_host;（含端口，更准确）
要彻底禁用某头（如不传 User-Agent），设为空：proxy_set_header User-Agent "";
若想阻止客户端头透传到后端，不声明对应 proxy_set_header 即可，默认不转发（除少数如 Host 被自动重写）

注意事项与常见陷阱

proxy_set_header 必须写在 proxy_pass 所在的同一配置块（location、server 或 http），继承规则有限，避免写在上层却期望子块生效
如果用了 rewrite 且带 break 或 last，确保 proxy_set_header 在最终执行的 location 内
头名称区分大小写，但 HTTP 协议本身不区分；建议用标准驼峰格式（如 X-Forwarded-For）保持兼容性
值中含空格或特殊字符时，用引号包裹（Nginx 1.19.3+ 支持双引号，旧版建议避免空格）