如何根据 upstream_addr 动态设置 Nginx 变量？

Question

在 Nginx 反向代理场景中，如何基于 `$upstream_addr`（即实际被选中的上游服务器地址，如 `10.0.1.5:8080` 或 `unix:/var/run/backend.sock`）动态提取并设置自定义变量（例如 `$upstream_host`、`$upstream_port` 或 `$upstream_type`），常面临核心限制：`$upstream_addr` 是**仅在 `log_format` 和 `proxy_set_header` 等少数上下文中可用的“后期变量”**，无法在 `set`、`map` 或 `if` 中直接引用。开发者尝试用 `map` 解析时会发现变量为空；使用 `set_by_lua` 也因执行阶段早于 upstream 分配而取不到值。这导致无法在请求处理早期（如 rewrite 阶段）依据真实后端做条件路由、日志标记或 header 注入。如何在不依赖 Lua 模块的前提下，安全、高效地实现基于实际 upstream_addr 的变量派生？这是高可用架构中精细化流量治理的关键痛点。

Answer 1

```html

一、认知层：理解 Nginx 变量生命周期与 $upstream_addr 的“晚期性”

在 Nginx 请求处理流水线中，变量按执行阶段分为三类：编译期（如 $server_name）、配置期（如 $arg_x）和运行期（如 $upstream_addr）。后者仅在 proxy_pass 后的 upstream 分配完成阶段（即 NGX_HTTP_CONTENT_PHASE 末尾）才被赋值，早于该阶段的 set、map、if 均无法访问其真实值——这是所有失败尝试的根源。

二、验证层：复现问题并定位阶段鸿沟

以下配置将清晰暴露限制：

map $upstream_addr $upstream_host {
    ~^([^:]+):(\d+)  $1;
    ~^unix:/         "unix";
    default          "unknown";
}
# 实际日志中 $upstream_host 恒为 "unknown" —— 因 map 在 server{} 加载时静态解析，此时 $upstream_addr 尚未生成

三、架构层：Nginx 原生机制的阶段适配策略

不依赖 Lua 的核心破局思路是：放弃“提前提取”，转向“就地注入”与“延迟透传”。Nginx 提供两类原生通道：

• proxy_set_header：可在 upstream 选定后向后端注入含 $upstream_addr 的头（支持正则捕获）
• log_format：唯一可安全使用 $upstream_addr 的上下文，支持嵌套变量与条件格式化

四、实践层：基于 proxy_set_header 的变量派生方案

利用 Nginx 1.19.0+ 支持的 proxy_set_header 正则捕获语法，实现无 Lua 的动态解析：

location /api/ {
    # 使用内置正则提取 host/port/type 并注入 Header
    proxy_set_header X-Upstream-Host $upstream_addr;
    proxy_set_header X-Upstream-Port $upstream_addr;
    proxy_set_header X-Upstream-Type $upstream_addr;

    # 关键：Nginx 会自动对 $upstream_addr 执行正则匹配（需启用 regex support）
    # 注意：实际需配合 map + proxy_set_header 的组合技巧（见下表）
}

五、进阶层：双 map 协同模式（推荐生产部署）

通过预定义 upstream 名称与地址映射，绕过 $upstream_addr 不可用问题：

上游名称	地址列表	语义标签
backend-v1	10.0.1.5:8080, 10.0.1.6:8080	v1-http
backend-unix	unix:/var/run/backend.sock	unix-socket

六、工程层：完整可运行配置示例

# 定义语义化 upstream 块（显式绑定类型）
upstream backend_v1_http {
    server 10.0.1.5:8080 max_fails=3 fail_timeout=30s;
    server 10.0.1.6:8080 max_fails=3 fail_timeout=30s;
}

upstream backend_unix_socket {
    server unix:/var/run/backend.sock;
}

# 利用 upstream 名称作为代理依据（rewrite 阶段可用！）
map $host $target_upstream {
    default backend_v1_http;
    ~^unix\.example\.com$ backend_unix_socket;
}

# 动态设置 header（upstream_addr 在此阶段已就绪）
proxy_set_header X-Real-Upstream $target_upstream;
proxy_set_header X-Upstream-Type $target_upstream;
proxy_set_header X-Upstream-Addr $upstream_addr;

七、可观测层：log_format 中的深度解析能力

在 access_log 中实现字段级拆解（无需外部工具）：

log_format upstream_detail 
  '$remote_addr - $remote_user [$time_local] '
  '"$request" $status $body_bytes_sent '
  'upstream:"$upstream_addr" '
  'host:"$upstream_addr~^(?P<h>[^:]+):(?P<p>\d+)$h" '
  'port:"$upstream_addr~^(?P<h>[^:]+):(?P<p>\d+)$p" '
  'type:"$upstream_addr~^unix:/.*$unix"';

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

八、边界层：关键限制与规避清单

• ❌ set $x $upstream_addr → 永远为空（rewrite 阶段早于 upstream 分配）
• ❌ if ($upstream_addr ~ "10\.0\.1\.5") → 语法错误（if 不支持 late variable）
• ✅ proxy_set_header X-Backend $upstream_addr → 安全有效
• ✅ log_format ... "$upstream_addr" → 唯一可靠消费点

九、演进层：Nginx Plus 与 OpenResty 的对比启示

虽本方案禁用 Lua，但需明确：OpenResty 的 balancer_by_lua* 阶段可真正实现 upstream 决策前的变量计算；而 Nginx OSS 的演进方向（如 1.25+ 的 proxy_next_upstream_tries 增强）仍聚焦于故障转移而非变量派生——这印证了原生方案的长期必要性。

十、决策层：技术选型决策树

graph TD
    A[是否允许 Lua?] -->|Yes| B[balancer_by_lua* + set_by_lua*]
    A -->|No| C[采用双 map + upstream name 语义化]
    C --> D{是否需 rewrite 阶段路由?}
    D -->|Yes| E[基于 $upstream_name 或 $server_name 分流]
    D -->|No| F[用 log_format + proxy_set_header 满足审计/透传]
    E --> G[配置示例：map $upstream_name $route_type]
    F --> H[日志字段：$upstream_addr~^(?P<h>[^:]+):(?P<p>\d+)$h]

```