Nginx 中 proxy_pass 的变量使用与动态反向代理配置-Nginx-PHP中文网

proxy_pass支持变量但需满足至少两个部分静态，仅一个变量且运行时可解析；推荐map+upstream组合实现安全动态代理，禁用全变量拼接。

nginx 中 proxy_pass 的变量使用与动态反向代理配置

proxy_pass 支持变量，但必须满足特定条件才能动态生效。直接写成 proxy_pass http://$host:$port 会报错，因为 Nginx 在启动时就校验 upstream 地址是否合法，而未解析的变量不被视为有效目标。

proxy_pass 变量使用的硬性限制

Nginx 要求 proxy_pass 的协议、主机名（或 IP）、端口三者中，至少有两个是静态确定的。只允许一个部分使用变量，且该变量必须能被 Nginx 在运行时安全解析并拼接为完整 URL。

✅ 允许：proxy_pass http://backend$uri（变量仅出现在 URI 部分）
✅ 允许：proxy_pass http://$host:8080（主机名动态，端口固定）
❌ 禁止：proxy_pass http://$host:$port（主机和端口都动态，启动校验失败）
❌ 禁止：proxy_pass $scheme://$host:$port$request_uri（协议、主机、端口全变量，Nginx 不支持）

实现动态反向代理的常用方式

真正需要根据请求头、参数或路径动态决定后端地址时，不能仅靠 proxy_pass 变量，得配合其他机制：

CPA Update - Secure CLI Proxy API Maintenance

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

下载

用 map 指令预定义映射关系：将 Host、URL 路径或请求头值映射为上游名称或地址字符串，再在 proxy_pass 中引用该变量
借助 upstream 动态解析（需 resolver）：当后端域名需 DNS 查询时，必须配置 resolver，并确保 proxy_pass 使用变量指向域名（如 proxy_pass http://$upstream_host），且该变量不含端口或带固定端口
用 rewrite + if（慎用）：先重写请求路径或设置变量，再在 location 中调用 proxy_pass；但 if 在 location 中行为受限，易出逻辑偏差，不推荐复杂判断

典型安全动态代理配置示例

以下是一个基于 Host 头选择上游服务的可靠做法：

resolver 8.8.8.8 valid=30s;
map $http_host $backend {
    ~^app1\.example\.com$ app1_backend;
    ~^api\.example\.com$ api_backend;
    default default_backend;
}

upstream app1_backend { server 192.168.1.10:3000; }
upstream api_backend  { server 192.168.1.11:8000; }
upstream default_backend { server 127.0.0.1:8080; }

server {
    listen 80;
    location / {
        proxy_pass http://$backend;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

注意：resolver 必须存在，且 $backend 值对应的是 upstream 名称，不是原始域名——这是避免变量拼接风险的关键设计。