Nginx upstream块中直接写域名(如server api.example.com;)仅启动时解析一次且不响应resolver指令,导致IP变更后持续发往失效地址;真正动态解析需配合变量+proxy_pass+http块中resolver valid=参数。

在 Nginx 负载均衡场景中,若 upstream 块直接写域名(如 server api.example.com;),Nginx 启动时仅做一次 DNS 解析,并长期缓存结果——这会导致后端 IP 变更后流量持续发往失效地址,引发超时、404 或连接拒绝。官方明确说明:resolver 对 upstream 中的域名无效。真正能实现动态解析的,是配合变量与 resolver 的组合用法,而非 upstream 本身。
为什么 upstream + resolver 不生效?
Nginx 官方文档和实测均证实:upstream 块内的域名解析发生在配置加载阶段,且不响应 resolver 指令。即使你写了:
http {
resolver 8.8.8.8 valid=30s;
upstream backend {
server api.example.com:80;
}
}该配置中的 api.example.com 仍只在 nginx 启动或 reload 时解析一次,之后不再更新。所谓“resolve”参数(如 server api.example.com resolve;)属于第三方模块(如 nginx-upstream-dynamic-servers)的扩展语法,非 Nginx 开源版原生支持。
正确做法:proxy_pass + 变量 + resolver
让 DNS 解析在每次请求时按需触发,关键在于避免在 proxy_pass 中硬编码域名,改用变量,并在 location 或 server 块中声明 resolver:
- 在 location 内使用
set $host "api.example.com";定义目标域名 - 必须显式配置
resolver(推荐两个以上可信 DNS,如resolver 1.1.1.1 8.8.8.8 valid=30s;) - proxy_pass 使用变量形式:
proxy_pass https://$host;(注意不能带端口,端口需在变量里或通过 proxy_set_header Host 携带) - 添加
resolver_timeout 3s;防止卡顿,避免 fallback 到系统解析器
这样每次请求都会查缓存 → 命中则用;过期则重新发起 DNS 查询 → 更新缓存。valid 时间可根据后端变更频率设定(DDNS 推荐 10–30s,CDN 回源可设为 5m)。
补充:提升稳定性的实用配置
单靠 resolver + 变量还不够健壮,建议叠加以下设置:
- 启用 keepalive 连接池:定义 upstream 复用已解析的 IP 和 TCP 连接,避免重复握手。例如:
upstream keepalive_backend {
server 0.0.0.0:1; # 占位,实际由 proxy_pass 动态决定
keepalive 32;
}
并在 location 中用proxy_pass https://keepalive_backend;+proxy_http_version 1.1;+proxy_set_header Connection ''; - 禁用 IPv6 解析(如后端仅支持 IPv4):
resolver 8.8.8.8 ipv6=off;,减少冗余查询 - 避免在容器环境将 resolver 指向
127.0.0.11(Docker 默认 DNS),因其无缓存且转发链路长;应直连公网 DNS 或部署本地 dnsmasq
其他可行方案对比
若无法修改 proxy_pass 写法,或需 upstream 级别健康检查,可考虑:
-
nginx-upstream-dynamic-servers 模块:支持
server domain.com resolve;,按 TTL 自动刷新。但需自行编译,且高版本 Nginx 兼容性需验证 - Tengine 的 dynamic_resolve:阿里系分支已内置,语法简洁,适合 Tengine 用户
-
定期 reload nginx:最简单粗暴,适合变更低频场景。可用脚本结合
dig监控 IP 变化后自动触发nginx -s reload
不复杂但容易忽略。


















