Nginx 工程实践 -- 25. 动态 upstream 与服务发现

第 12 篇的 upstream 是静态的:地址写死在配置里,改一次要 reload。容器编排、DNS 轮询、服务实例频繁扩缩容的场景下,上游列表是动态的。这篇讲清楚"什么时候能静态、什么时候必须动态",以及动态化带来的代价。

flowchart TD
    A["请求"] --> B["resolver + 变量 proxy_pass"]
    B --> C["运行时 DNS 解析"]
    C --> D["选择上游"]
    E["服务发现 / DNS SRV"] --> C
    F["njs"] -->|"动态选址 / 权重"| D
    G["商业版 API"] -->|"动态增删上游"| D

一、静态 upstream 的边界

1
2
3
4
upstream backend {
server backend-1.example.com:8000;
server backend-2.example.com:8000;
}
  • upstream 块里的 server 在配置加载时解析 DNS,之后地址固定;
  • 想要 DNS 变化生效,只能 reload;
  • upstream 不支持变量(server $var; 不合法)。

所以:地址稳定(固定 IP、VIP)用静态;地址随实例变化(DNS 轮询、容器)用动态。

二、resolver + 变量 proxy_pass

把 proxy_pass 改成变量,Nginx 就会在运行时解析域名,此时必须配 resolver:

1
2
3
4
5
6
location /api/ {
resolver 127.0.0.11 valid=10s ipv6=off;
resolver_timeout 5s;
set $upstream "backend.internal:8000";
proxy_pass http://$upstream;
}
  • resolver 常用集群内 DNS(如 Docker Embedded DNS 127.0.0.11、CoreDNS 地址);
  • valid=10s 控制缓存时长,平衡新鲜度与解析开销;
  • 每次连接按最新 DNS 结果选址,DNS 轮询天然成为负载均衡;
  • 注意:变量化后 proxy_redirect default 可能失效,需要显式配置(见第 15 篇)。

三、DNS 轮询的局限

DNS 轮询是"多 A 记录随机返回",Nginx 每次解析拿到一组地址,但默认只用其中一个,不会自动在多个 A 记录间负载均衡。想要真正的多实例负载均衡,仍然需要:

  • 静态 upstream(地址相对固定);
  • 或借助服务发现生成配置并 reload;
  • 或商业版的动态 upstream API。

四、njs:运行时动态选址

njs(ngx_http_js_module)可以在请求阶段计算目标地址,实现更灵活的动态路由:

1
2
3
4
5
6
7
js_import /etc/nginx/router.js;
js_set $target router.pick;

location /api/ {
resolver 127.0.0.11 valid=10s;
proxy_pass http://$target;
}

router.js 里根据请求头、Cookie 或外部服务返回的地址列表选择目标。要点:

  • njs 是受限运行时,只能用官方 API;
  • 外部调用走 fetch(js_fetch 相关配置)或子请求;
  • 逻辑要快,避免阻塞请求阶段。

五、商业版动态 upstream API

NGINX Plus 提供 HTTP API 动态增删改 upstream:

1
2
GET  /api/version/upstreams/backend
POST /api/version/upstreams/backend/servers
  • 无需 reload 即可调整后端列表和权重;
  • 适合与控制面(Operator、自研平台)对接;
  • 开源版没有该 API,需要自己用配置生成 + reload 或 njs 方案替代。

六、常见坑

坑说明
upstream 里写变量不支持,server $var; 不合法
变量 proxy_pass 不配 resolver运行时无法解析,直接报错
期望 DNS 轮询在多 A 记录间均衡默认只用其一,需静态 upstream 或 API
valid= 设太大DNS 变化生效慢,实例下线仍被转发
njs 逻辑太重阻塞请求阶段,拖慢所有请求
动态化后 proxy_redirect default 失效显式配置替换规则
开源版找动态 API商业版功能,开源版用配置生成 + reload 或 njs

参考链接

  1. Nginx 官方文档:ngx_http_proxy_module(proxy_pass 与变量) —— 变量与 resolver 的关系;
  2. Nginx 官方文档:ngx_http_core_module(resolver) —— 运行时 DNS 解析;
  3. Nginx 官方文档:ngx_http_upstream_module —— 静态上游组;
  4. Nginx 官方文档:ngx_http_js_module —— njs 动态选址;
  5. NGINX Plus:Dynamic Upstream API —— 商业版动态增删上游。

小结

  • 静态 upstream 地址固定,DNS 变化要 reload;
  • 动态地址用 resolver + 变量化 proxy_pass,注意 valid 与 proxy_redirect;
  • DNS 轮询不等于多实例负载均衡;
  • 更灵活用 njs 运行时选址;商业版有动态 upstream API;
  • 开源版的折中方案是配置生成 + reload 或 njs。

系列导航


Nginx 工程实践 -- 25. 动态 upstream 与服务发现
https://bubao.github.io/posts/d5e6f7a8.html
作者
一念
发布于
2026年11月21日
许可协议