Nginx upstream中实现resolve动态解析需满足三条件:全局resolver置于http块顶层并带valid参数、server行用域名+端口+resolve关键字、Nginx版本≥1.19.0;缺一则仍为静态解析。

要在 Nginx 的 upstream 块中真正实现 resolve 动态监听后端域名解析变化,必须满足三个硬性条件:全局 resolver 已声明、upstream 中 server 行使用域名并显式加 resolve、Nginx 版本 ≥ 1.19.0。缺一不可,否则仍为静态解析。
resolver 必须放在 http 块顶层,且带 valid 参数
这是基础前提。Nginx 不会从 server 或 location 继承 resolver,更不允许写在 upstream 内部——否则直接报错 "resolver" directive is not allowed here。
- ✅ 正确写法:http { resolver 114.114.114.114 8.8.8.8 valid=20s; }
- ❌ 错误写法:
upstream { resolver ... }或location { resolver ... } -
valid=20s是核心:它强制 Nginx 每 20 秒检查 DNS 是否更新;不加该参数,缓存永不刷新,等于没配 - 建议配置至少两个 DNS 地址(空格分隔),并加
resolver_timeout 3s;防止单次查询阻塞 worker
upstream 中 server 必须写域名 + resolve + 明确端口
仅声明 resolver 不足以激活动态行为,upstream 内每条 server 必须同时满足三项:
- 域名不能是 IP(如
server 10.1.2.3:8080;会忽略 resolve) - 必须带端口号(
server api.example.com resolve;会报invalid port in upstream) -
resolve必须紧贴在端口后,中间无换行或空格(server api.example.com:8080 resolve;) - 可单独为该域名设 TTL:
server api.example.com:8080 resolve valid=15s;,覆盖全局 valid
需确保 proxy_pass 引用该 upstream,且 Nginx 版本达标
即使 upstream 配置正确,若外部未调用或版本过低,resolve 也不会生效。
- 在 server 或 location 中使用:
proxy_pass http://dynamic_backend;(名称需与 upstream 一致) - 必须使用 Nginx ≥ 1.19.0(开源版已原生支持);1.18.x 及更早版本会静默忽略
resolve关键字 - 若需健康检查,可叠加:
max_fails=2 fail_timeout=15s和proxy_next_upstream error timeout http_502;
验证是否真正在动态更新
别依赖 nginx -t,它只校验语法。真实效果看运行时日志和行为:
- 修改 DNS 记录(如将
api.example.com解析到新 IP),等待超过valid时间(如 20 秒) - 检查
error.log:出现resolved api.example.com to 10.244.3.7或resolving api.example.com...才算成功 - 若频繁报
getaddrinfo() failed,先确认 DNS 地址可达、UDP 53 端口未被拦截、resolver_timeout是否设得太短


















