Docker部署Nginx代理API报host not found in upstream错误 托管于AWS ECS

报错核心原理 #

这个emerg级别的报错本质来自Nginx的配置加载机制：Nginx在启动、执行配置重载的校验阶段，会直接对proxy_pass后紧跟的静态域名做DNS解析，如果这一步无法获取目标主机的IP，就会直接终止进程抛出错误，不会等到运行时收到实际API请求再做动态解析。

对于两个服务都托管在AWS ECS上的部署场景，常见触发原因包括：

• Nginx容器启动瞬间，ECS任务的网络与DNS配置还未完全初始化，导致解析流程拿不到正确的DNS响应
• 配置的上游域名拼写错误，或域名本身没有配置对应的DNS解析记录
• Nginx容器使用的DNS服务器和VPC内部服务发现的DNS地址不匹配，无法解析ECS内部托管的服务域名
• 原配置中proxy_pass直接硬编码域名的写法，触发了Nginx启动阶段的强制静态解析，没有适配ECS环境下的动态服务发现特性

可落地的解决方法 #

• 先做基础连通性排查：在同VPC、同子网下其他正常运行的ECS任务里执行nslookup www.api.test.example.net，确认域名本身可以被正常解析，排除域名写错、DNS记录缺失的基础问题
• 调整Nginx配置适配ECS动态解析能力，从根源上避免启动阶段强制解析报错：
  在你的/api/路由块内增加动态解析配置，示例写法如下：

  location /api/ {
      # 显式指定VPC内置链路本地DNS地址，关闭IPv6避免解析异常，设置短TTL适配ECS服务的动态IP变更
      resolver 169.254.169.253 valid=5s ipv6=off;
      # 将上游域名赋值给自定义变量，让Nginx跳过配置加载阶段的静态解析
      set $api_upstream www.api.test.example.net;
      proxy_pass http://$api_upstream:8080;
      # 常规代理头配置，不影响解析逻辑
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
  }
  

  这个写法的核心逻辑是：当proxy_pass后面跟的是Nginx自定义变量时，配置加载阶段不会对变量内容做强制域名解析，会等请求真正到达路由时，再通过指定的resolver做实时DNS查询，从根本上避免启动瞬间解析失败导致的进程退出。
• 补充检查项：如果Nginx容器使用bridge网络模式，不要在容器启动参数里硬编码公共DNS地址，保证容器可以正常访问VPC内置的169.254.169.253 DNS服务；如果是使用ECS服务发现的域名作为上游，要确认服务发现的命名空间、服务名拼写和控制台配置完全一致，避免因域名格式错误导致解析失败。

内容的提问来源于stack exchange，提问作者Erik Craigo