nginx 本身不会自动缓存域名解析结果:只有在 proxy_pass 里使用变量并配合 resolver 指令时,运行时 DNS 缓存才会生效;其余写法下,域名只在启动或 reload 时解析一次,后端 IP 变更后 nginx 仍会持续访问旧地址。
很多线上故障的根源就藏在这一句里,配置看起来没问题,reload 也做了,可流量就是打到了已经下线的机器上,下面把 nginx 域名缓存这件事拆开讲清楚。
nginx 域名缓存到底缓存在哪一层
默认行为:域名只在启动时解析一次
无论是写在 upstream 块里,还是直接写在 proxy_pass 后面,只要域名是静态字符串,nginx 就把它当成"一次性配置"处理:
- 启动或 reload 时调用系统解析器拿到 IP,之后写死在内存里;
- 后端扩容、迁移机房、切换可用区,nginx 完全无感;
- 唯一解法是重启或 reload,而这在生产环境往往不是你想做的事。
最常见的翻车场景是云上 RDS 或内网负载均衡的地址变更,运维改了 DNS,应用侧没重启,日志里就开始刷 502。
resolver 打开的是运行时解析
加一条 resolver 指令,情况才真正改变:
resolver 223.5.5.5 119.29.29.29 valid=30s ipv6=off; resolver_timeout 5s; set $backend "api.example.com"; proxy_pass http://$backend:8080;
nginx 会自己去发 DNS 查询,不走系统的 getaddrinfo,解析结果存在 worker 进程内的缓存字典里,valid 参数控制缓存时长,这里有个容易被忽略的点:nginx 的 resolver 不读 /etc/hosts,也不受 systemd-resolved、nscd 的缓存影响,它是一条独立的解析链路。
nginx resolver 和系统 DNS 缓存的区别在哪
这两个缓存在实际排查中经常被混为一谈,对比一下会清楚很多:
| 对比项 | nginx resolver 缓存 | 系统 DNS 缓存 |
|---|---|---|
| 缓存位置 | nginx worker 进程内存 | systemd-resolved / nscd / dnsmasq |
| 是否读 hosts | 默认不读 | 读 |
| TTL 来源 | valid 参数优先,未设则跟随记录 TTL |
跟随记录 TTL |
| 生效范围 | 只影响 nginx 自身 | 影响整台机器所有进程 |
| 更新方式 | 缓存过期后惰性重新解析 | 各缓存服务策略不同 |
所以会出现这种局面:机器上 dig 已经拿到新 IP,nginx 还在打旧 IP,原因就是两套缓存各自为政,谁也没等谁。
nginx 动态域名解析配置实战
最小可用配置
把 proxy_pass 里的域名换成变量,是触发动态解析的关键动作:
http {
resolver 223.5.5.5 valid=10s;
resolver_timeout 3s;
server {
listen 80;
location /api/ {
set $backend "api.example.com";
proxy_pass http://$backend:8080$request_uri;
}
}
}
注意 $request_uri 这一段,一旦 proxy_pass 里出现变量,nginx 就不再自动拼接 location 匹配到的 URI,路径要自己带上,否则请求会全部落到根路径上,接口集体 404。
upstream 里让 server 支持动态更新
较新的开源版本已经在 upstream 的 server 上支持 resolve 参数,配合 zone 使用:
http {
resolver 223.5.5.5 valid=10s ipv6=off;
upstream backend {
zone backend 64k;
server api.example.com:8080 resolve;
server api2.example.com:8080 resolve backup;
}
}
zone 是必需的,它提供共享内存用于保存解析结果和状态,业内专家指出,这种写法比在 proxy_pass 里塞变量更适合多后端负载均衡场景,因为健康检查和权重策略都能保留。
缓存过期后的更新是惰性的
valid 到期并不意味着 nginx 立刻去查一次 DNS,真实行为是:下一个请求进来时发现缓存过期,才同步发起解析,解析完成前该请求会等待,最长不超过 resolver_timeout。valid 设得太短,遇上 DNS 抖动,接口延迟会跟着一起抖。
nginx 域名缓存时间设置多少合适
这个问题没有标准答案,但有清晰的取舍逻辑。valid 会覆盖 DNS 记录本身的 TTL,所以它才是实际生效的那一个。
按场景取值
- 核心交易接口、主备切换要求快:
valid=5s~10s,配合proxy_next_upstream做失败重试; - 普通业务域名:
valid=30s~60s,兼顾响应速度和 DNS 查询压力; - CDN 回源、静态资源域名:
valid=300s以上,这类地址本身就不常变; - K8s Service 短域名:跟随集群 DNS 的短 TTL,
valid不要超过 10s。
别忘了上层也要配合
如果域名解析在云厂商的托管 DNS 里 TTL 是 600s,你把 nginx 的 valid 设成 5s 意义有限,权威 DNS 那一层的缓存依旧会把旧记录发给你,行业共识认为,域名缓存是分层生效的,任何一层拖后腿都会让整条链路变慢,调整前先确认权威记录的 TTL,再倒推 nginx 侧的取值。
nginx 域名缓存不生效怎么排查
三步定位法
- 确认配置结构:执行
nginx -T | grep -n resolver,看resolver是否在生效的上下文里,同时确认proxy_pass用的是变量而不是写死的域名; - 看错误日志:
tail -f /var/log/nginx/error.log,出现no resolver defined to resolve xxx就是变量写法缺了resolver; - 对照解析结果:用
dig @223.5.5.5 api.example.com +short和ss -tnp | grep nginx看实际连接的目标 IP,两边不一致基本可以锁定是缓存未过期或配置未 reload。
几个高频报错
no resolver defined to resolve:proxy_pass用了变量,但没配resolver;host not found in upstream:启动时静态域名解析失败,检查/etc/resolv.conf和网络连通性;resolver timed out:DNS 服务器不可达或resolver_timeout太短,内网环境优先指向本地 DNS。
容器与多地域环境下的注意点
容器里跑 nginx 是另一个坑区,Docker 内置 DNS 监听在 0.0.11,/etc/resolv.conf 里通常就写着它,但 nginx 默认不会去读这个文件,需要显式配置:
resolver 127.0.0.11 valid=10s ipv6=off;
在 K8s 里则是 kube-dns 的 ClusterIP 或者 kube-dns.kube-system.svc.cluster.local,OpenResty 用户可以用 resolver local=on 让它直接读系统 resolv.conf,省掉硬编码。
多地域部署时,各地 nginx 应指向本地区的 DNS 服务器,避免跨区查询带来的额外延迟,近年来跨可用区流量成本被反复提及,解析链路同样适用这个逻辑。
nginx 域名缓存常见疑问解答
nginx 会缓存 /etc/hosts 里的解析结果吗
不会,nginx 的 resolver 直接走 DNS 协议查询,不经过系统解析器,hosts 文件对它无效,如果确实需要走本地 hosts,只能用 OpenResty 的 resolver local=on,或者干脆把 IP 写进 upstream。
改了 valid 参数需要重启 nginx 吗
需要 reload。valid 属于配置项,nginx -s reload 后新的 worker 进程会按新值重建缓存,旧 worker 平滑退出,注意 reload 不会清空正在处理中的长连接。
多个 worker 之间的缓存是共享的吗
不是,nginx 的 resolver 缓存由每个 worker 进程各自维护一份,互不共享,因此实际 DNS 查询量约为 worker 数乘以过期频率,这也是 valid 不宜设得过短的原因之一,worker 数量多的时候,几十秒一次的解析请求乘以进程数,对内部 DNS 服务器是实打实的压力。