OpenResty + Docker 容器重建后出现 502 的原因与解决方案

在使用 OpenResty（基于 Nginx）作为网关，反向代理到 Docker 容器内服务时，常见一个问题：

容器重启或更新后，OpenResty 返回 502 Bad Gateway。

本文将从现象入手，分析原因，并给出最佳配置实践。

1. 问题描述#

示例配置如下：

1
location /api/ {
2
    proxy_pass http://backend-1/;
3
    proxy_set_header Host $host;
4
    proxy_set_header X-Real-IP $remote_addr;
5
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
6
}

其中 backend-1 是通过 Docker Compose 启动的服务名。

容器更新后出现如下错误：

1
502 Bad Gateway

日志输出可能如下：

1
"GET /api/login HTTP/1.1" 502 ...

2. 问题原因分析#

2.1 Nginx 默认行为#

默认情况下，proxy_pass http://backend-1/; 中的域名 backend-1 会在 Nginx 启动时解析一次
然后 Nginx 会缓存解析结果（即 IP 地址），后续请求都使用该 IP，不再重新解析。

2.2 Docker 容器 IP 动态变化#

Docker Compose 启动的容器每次重建时，IP 地址可能变化；
虽然服务名不变，但 IP 已失效； = Nginx 此时依然连接旧 IP，因此返回 502；

3. 正确解决方案：变量 + resolver 联用#

仅使用 resolver 127.0.0.11; 并不能使 Nginx 自动重新解析 proxy_pass 中的静态域名。要实现 每次请求动态解析域名，你需要将 proxy_pass 改写为变量形式：

1
set $backend_host http://backend-1;
2
proxy_pass $backend_host;

同时，在 http 区块中添加：

1
resolver 127.0.0.11 valid=10s;

解释如下：

使用变量触发每次请求时的动态域名解析；
127.0.0.11 是 Docker 的内置 DNS 服务器；
valid=10s 表示每 10 秒重新解析一次域名。

4. 完整示例配置#

1
http {
2
    resolver 127.0.0.11 valid=10s;
3

4
    server {
5
        listen 1010;
6
        server_name localhost;
7

8
        location /api/ {
9
            set $backend_host http://backend-1;
10
            proxy_pass $backend_host;
11

12
            proxy_set_header X-Real-IP $remote_addr;
13
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
14
        }
15

16
        location /desktop/ {
17
            proxy_pass http://192.168.0.80:4010/desktop/;
18
            proxy_set_header Host $host;
19
            proxy_set_header X-Real-IP $remote_addr;
20
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
21
            proxy_set_header Upgrade $http_upgrade;
22
            proxy_set_header Connection 'upgrade';
23
        }
24

25
        location / {
26
            proxy_pass http://192.168.0.80:4020/;
27
            proxy_set_header Host $host;
28
            proxy_set_header X-Real-IP $remote_addr;
29
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
30
            proxy_set_header Upgrade $http_upgrade;
31
            proxy_set_header Connection 'upgrade';
32
        }
33
    }
34
}

5. 验证方式#

5.1 DNS 解析测试#

1
docker exec -it openresty_container ping backend-1

5.2 接口可用性测试#

1
docker exec -it openresty_container curl http://doamin.com/api/health

6. Docker 网络建议#

确保容器处于同一网络，例如：

1
networks:
2
  net:
3
    driver: bridge
4

5
services:
6
  gateway:
7
    image: openresty
8
    networks:
9
      - net
10

11
  backend:
12
    image: your-backend-image
13
    networks:
14
      - net

7. 总结#

问题	解决方式
容器更新导致服务 IP 变化	使用 Docker 内置 DNS 动态解析
Nginx 默认缓存域名 IP 不变	使用 `resolver` + 变量方式实现请求级别动态解析
proxy_pass 无法解析新 IP	改写为 `set $backend_host http://服务名; proxy_pass $backend_host;`