AI摘要

用两个 Docker 容器搭一个小网站,逐步看清 Nginx 反向代理里的地址和端口。附完整配置、真实截图,以及 127.0.0.1、端口填错、healthy 仍然 502 等问题的排查过程。

打开网站,浏览器只显示 502 Bad Gateway。回到服务器一看,容器明明还在运行,Nginx 的配置检查也通过了。这种情况很容易让人开始反复重启,却不知道应该改哪一行。

先从 Nginx 要访问的地址查起。尤其是用 Docker 部署时,127.0.0.1 指向谁、该填哪个端口,经常和直觉不一样。

下面搭一个能正常打开的小网站,再故意改错几处配置。每次都看一下日志,找到原因后恢复。遇到自己的 502 问题,可以直接从“地址写成 127.0.0.1”那一节开始对照。

先把这三个端口分清

这次用两个容器:app 保存网页,gateway 负责接收访问,再去 app 取网页。这里说的“反向代理”,做的就是后面这件事。

位置端口用在哪里
服务器18980浏览器或 curl 访问的入口
gateway 容器80gateway 自己接收请求的端口
app 容器8080网页实际所在的端口

请求会按这个顺序走:浏览器 → 服务器的 18980 → gateway 的 80 → app 的 8080。

所以稍后配置 proxy_pass,要写的是 app:8080。服务器的 18980 是留给外面访问的,不用填到这里。

下面的文件创建命令在 Linux 终端里执行,Windows 可以用 WSL。先确认 Docker、Compose 和 curl 已经能用:

docker version
docker compose version
curl --version

docker version 应当同时显示 Client 和 Server。没有 Server,说明还没连上 Docker 服务,先处理这个问题。提示 Docker socket 权限不足时,可以使用有权限的账号,或在下文的 Docker 命令前加 sudo。

建好四个文件

新建一个演示目录,后面的命令都在这里执行:

mkdir -p ~/nginx-502-demo/site ~/nginx-502-demo/nginx
cd ~/nginx-502-demo
pwd

pwd 显示的路径应当以 nginx-502-demo 结尾。中途断开 SSH,再登录时记得先回到这个目录。

网页:site/index.html

把下面整段复制到终端,最后一行 EOF 也一起复制:

cat > site/index.html <<'EOF'
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>Docker 反向代理演示</title>
<h1>页面来自 app 容器</h1>
<p>gateway → app:8080 → index.html</p>
</html>
EOF

网页里特意写了“页面来自 app 容器”。稍后看到这句话,就知道打开的是这份文件。如果出现 Nginx 欢迎页,就需要检查是不是访问错了入口,或挂载没有生效。

app 的配置:nginx/app.conf

cat > nginx/app.conf <<'EOF'
server {
    listen 8080;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;
    location / {
        try_files $uri $uri/ =404;
    }
}
EOF

这里先看两行:listen 8080 表示 app 在容器里的 8080 端口接收请求;root 是容器里的网页目录。稍后会把刚建的 site 文件夹放到这个目录下。

try_files 用来找网页文件,找不到就返回 404。<<'EOF' 里的引号要保留,这样 $uri 才会原样写进文件。

gateway 的配置:nginx/gateway.conf

cat > nginx/gateway.conf <<'EOF'
server {
    listen 80;
    server_name _;
    location / {
        proxy_pass http://app:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
EOF

proxy_pass http://app:8080; 是这份配置的重点。app 是接下来 Compose 文件里的服务名,两个容器加入同一个 Docker 网络后,就能用这个名字互相访问。

它不需要绑定域名,也不用去域名服务商添加一条叫 app 的解析。后面的 proxy_set_header 则把原来的域名和访问者地址传给 app,暂时保持上面的写法即可。

容器配置:compose.yaml

cat > compose.yaml <<'EOF'
name: nginx502-demo

services:
  app:
    image: nginx:alpine
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/"]
      interval: 5s
      timeout: 2s
      retries: 10
      start_period: 3s
    volumes:
      - ./site:/usr/share/nginx/html:ro
      - ./nginx/app.conf:/etc/nginx/conf.d/default.conf:ro
    networks:
      - webnet

  gateway:
    image: nginx:alpine
    depends_on:
      app:
        condition: service_healthy
    ports:
      - "127.0.0.1:18980:80"
    volumes:
      - ./nginx/gateway.conf:/etc/nginx/conf.d/default.conf:ro
    networks:
      - webnet

networks:
  webnet:
EOF

这份文件把前面几样东西接了起来:

  • volumes 左边是服务器上的文件或目录,右边是它在容器里的位置。末尾的 ro 表示容器只读,我们在服务器上改文件就行。
  • ports 把服务器的 18980 接到 gateway 的 80。app 没写 ports,gateway 仍然能通过 webnet 访问它。
  • healthcheck 会在 app 里面试着请求网页。gateway 等这项检查通过再启动,减少“后台还没准备好,入口已经开始转发”的情况。

这里把网页入口绑在 127.0.0.1,先从服务器本机访问。稍后会说明怎样在自己的电脑上打开。

name 是演示项目名。如果这台机器已经有同名项目,先换一个名字,以免影响原来的容器。

四份文件写完后检查一下:

ls -l compose.yaml site/index.html nginx/app.conf nginx/gateway.conf
cat nginx/gateway.conf
docker compose config -q

最后一条没有输出,一般就表示 Compose 语法检查通过。它只检查 Compose 文件,Nginx 里面的地址和端口还要靠实际访问确认。

检查网页和 Nginx 配置文件

四份文件已经创建好,gateway 指向 app 的 8080 端口。截图中的临时目录名与正文不同,文件内容相同。

如果后面启动时提示 not a directory,先回头检查这几个文件。挂载路径写错时,Docker 可能创建一个同名目录,结果把目录当成了配置文件。

启动后,先在服务器上访问

docker compose up -d
docker compose ps -a

等 app 显示 healthy,gateway 显示运行,再继续。第一次需要下载镜像;如果卡在 Pulling 或下载超时,先解决镜像下载问题。

app 一直没有变成 healthy 时,查看日志,并在 app 里访问它自己的网页:

docker compose logs --tail=50 app
docker compose exec app wget -S -O - http://127.0.0.1:8080/

第二条能看到“页面来自 app 容器”,说明 app 自己能提供网页。如果容器已经退出,第二条进不去,先看第一条的日志。

然后换到 gateway 里访问 app:

docker compose exec gateway wget -S -O - http://app:8080/

正常会返回类似内容:

Connecting to app:8080 (172.22.0.2:8080)
  HTTP/1.1 200 OK
  Server: nginx/1.31.6
...
<h1>页面来自 app 容器</h1>
<p>gateway → app:8080 → index.html</p>

其中的 IP 由 Docker 分配,你的可能不同。重点是出现了 200 OK,正文也是刚写的网页。这样就确认了 gateway 能找到 app,也能连上它的 8080。

最后在服务器上请求整个入口:

curl -i --max-time 5 http://127.0.0.1:18980/

返回结果中应当有:

HTTP/1.1 200 OK
Content-Type: text/html
...
<h1>页面来自 app 容器</h1>

经过 gateway 打开 app 中的网页

页面打开后,能看到刚才写入的两行文字。

如果这里返回 502,继续往下查。连 HTTP 响应都没有时,先确认 gateway 是否启动,以及端口是否发布正确:

docker compose port gateway 80
docker compose logs --tail=50 gateway

第一条应当显示 127.0.0.1:18980。命令中的 80 是 gateway 的容器端口。

Docker 在云服务器上,电脑怎么打开网页

按本文配置,直接访问 http://服务器IP:18980 会打不开,因为我们只让服务器本机访问这个端口。

可以用 SSH 把网页转到自己的电脑上。在电脑的终端执行下面这行,Windows 用 PowerShell 也可以:

ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:18981:127.0.0.1:18980 your_user@203.0.113.10

把 your_user 换成 SSH 用户名,203.0.113.10 换成服务器 IP。SSH 端口不是 22 的,再加上 -p 端口号。

登录完成后,终端会停在那里,没有新的命令提示符,这是正常的。保持它打开,然后在电脑浏览器访问:

http://127.0.0.1:18981/

这时访问电脑的 18981,实际上会连到服务器的 18980。如果提示 Address already in use,把命令里的第一个 18981 换成空闲端口,浏览器地址也跟着改;后面的 18980 保持不动。

如果 Docker 就运行在自己的电脑上,可以跳过 SSH,直接打开 http://127.0.0.1:18980/。

地址写成 127.0.0.1,为什么会 502

接下来故意改错配置。先备份正确文件,后面每个例子做完都恢复:

cp nginx/gateway.conf nginx/gateway.conf.good
cp nginx/app.conf nginx/app.conf.good

打开服务器上的 nginx/gateway.conf,把这一行:

proxy_pass http://app:8080;

改成:

proxy_pass http://127.0.0.1:8080;

保存后检查配置,通过了再重新加载。命令中的 && 表示前一条成功,才执行后一条:

docker compose exec gateway nginx -t && docker compose exec gateway nginx -s reload
curl -i --max-time 5 http://127.0.0.1:18980/
docker compose logs --tail=30 gateway

这时配置检查能通过,网页却变成了 502。

把代理地址改错后出现的 502 页面

浏览器只告诉我们访问失败。具体连错了哪里,要看 gateway 的日志。

日志中能找到:

connect() failed (111: Connection refused) while connecting to upstream
upstream: "http://127.0.0.1:8080/"

这里的 upstream,就是 Nginx 准备去取网页的地址。它现在访问的是 127.0.0.1:8080。

问题在于,Nginx 运行在 gateway 容器里。对它来说,127.0.0.1 指的是 gateway 自己。网页明明放在 app 容器里,它却在自己这里找,当然连不上。

改回 app 就能恢复:

cp nginx/gateway.conf.good nginx/gateway.conf
docker compose exec gateway nginx -t && docker compose exec gateway nginx -s reload
curl -i --max-time 5 http://127.0.0.1:18980/

确认重新返回 200,再做下一个例子。

用 1Panel 配反向代理时也要留意这一点:先看面板的 Nginx 或 OpenResty 运行在哪里。它如果在另一个普通 Docker 容器里,127.0.0.1 同样指向那个容器。服务器终端里能打开的地址,放进代理配置后未必还能打开。

服务名填对了,端口也可能填错

这次把 gateway 配置中的地址改成:

proxy_pass http://app:80;

检查、重新加载,然后访问:

docker compose exec gateway nginx -t && docker compose exec gateway nginx -s reload
curl -i --max-time 5 http://127.0.0.1:18980/
docker compose logs --tail=30 gateway

日志仍然提示连接被拒绝,不过这次地址变了:

connect() failed (111: Connection refused) while connecting to upstream
upstream: "http://172.22.0.2:80/"

IP 已经是 app 的地址,问题出在最后的 80。app 的配置写的是 listen 8080,80 上没有网页服务。

可以在 gateway 里分别试一下:

docker compose exec gateway wget -S -O - http://app:80/
docker compose exec gateway wget -S -O - http://app:8080/

第一条连接失败,第二条返回网页。这比只看 Docker 的端口列表更直接。

docker compose ps 有时会在 app 的 PORTS 栏显示 80/tcp,那可能只是镜像附带的端口声明。要看这个 app 实际监听哪里,可以执行:

docker compose exec app netstat -lnt

本例显示:

tcp  0  0  0.0.0.0:8080  0.0.0.0:*  LISTEN

所以代理地址应当恢复为 app:8080:

cp nginx/gateway.conf.good nginx/gateway.conf
docker compose exec gateway nginx -t && docker compose exec gateway nginx -s reload
curl -i --max-time 5 http://127.0.0.1:18980/

app 是 healthy,为什么 gateway 还是连不上

这次让 gateway 保持正确,只改 nginx/app.conf。把:

listen 8080;

改成:

listen 127.0.0.1:8080;

检查后重启 app,等它重新显示 healthy:

docker compose exec app nginx -t && docker compose restart app
docker compose ps -a

再分别从两个容器访问:

# 在 app 容器里访问自己
docker compose exec app wget -S -O - http://127.0.0.1:8080/

# 在 gateway 容器里访问 app
docker compose exec gateway wget -S -O - http://app:8080/

第一条能打开网页,第二条连接失败,外面访问也会变成 502。

listen 127.0.0.1:8080 的意思是:只接收从 app 自己内部发来的连接。健康检查正好就在 app 里面执行,所以它仍然通过;gateway 从另一个容器过来,就连不上了。

Python、Node.js 等程序也有类似的监听地址设置。遇到“程序内部能访问,其他容器访问不了”,可以检查程序是不是只监听了 127.0.0.1,具体参数按程序的文档修改。

把 app 恢复后,再试一次:

cp nginx/app.conf.good nginx/app.conf
docker compose exec app nginx -t && docker compose restart app
docker compose exec gateway wget -S -O - http://app:8080/
curl -i --max-time 5 http://127.0.0.1:18980/

如果报 host not found,先核对服务名

把 gateway 的代理地址改成一个不存在的名字:

proxy_pass http://not-a-service:8080;

这次只执行配置检查:

docker compose exec gateway nginx -t

就会报错:

host not found in upstream "not-a-service"
nginx: configuration file /etc/nginx/nginx.conf test failed

not-a-service 找不到了。先对照 Compose 里的名称,看有没有拼错,再检查两个容器是否加入同一个网络:

docker compose exec gateway nslookup app
docker network inspect nginx502-demo_webnet

第二条会列出 webnet 里的容器,应该能看到 app 和 gateway。前面改过项目名的话,网络名也要跟着改。

如果自己的 Nginx 和后台分别由两份 Compose 启动,它们很可能各在各的网络里。这时即使服务名拼写正确,也需要先让它们共享一个网络。

配置检查失败时,先修文件。直接重启会让 Nginx 带着错误配置重新启动,原本还能打开的页面也可能停掉。恢复命令如下:

cp nginx/gateway.conf.good nginx/gateway.conf
docker compose exec gateway nginx -t && docker compose exec gateway nginx -s reload
curl -i --max-time 5 http://127.0.0.1:18980/

改完文件,用哪个命令生效

这几个命令用途不同,记住自己改了什么就比较好选:

改了什么接下来怎么做
site/index.html 的网页内容保存后刷新页面
gateway 的 Nginx 配置先 nginx -t,通过后 nginx -s reload
Compose 里的端口、挂载或网络先 docker compose config -q,再 docker compose up -d

只执行 docker compose restart,不会把 Compose 文件里新写的端口映射应用进去。另一个容易碰到的情况是 app 重建后 IP 变了:确认 app 已能访问,再检查并重新加载 gateway,让它重新读取服务地址。

做完以后

在演示目录执行:

cd ~/nginx-502-demo
docker compose down

它会移除这套演示容器和网络,四份文件还留在原目录。用了 SSH 转发的,再关闭电脑上的那个终端。

排查自己的项目时,可以先保留现场。最有用的三样信息是:docker compose ps -a 的结果、gateway 的错误日志,以及在 gateway 里面直接访问 app 的结果。日志中失败的地址和端口,通常已经把下一步要查哪里写出来了。

本文在 Docker Desktop 的 Linux 容器中验证过,使用 Docker Engine 29.7.2、Compose 5.3.1、Nginx 1.31.6。不同精简镜像可能没有 wget、netstat,提示命令不存在时,需要换用镜像里可用的工具。

参考:Docker Compose 网络、服务启动顺序、Nginx proxy_pass、Nginx 重新加载配置、Docker 端口发布。

最后修改:2026 年 10 月 16 日
如果觉得我的文章对你有用,请随意赞赏
本文作者:
文章标题:Docker Compose 配置 Nginx 反向代理,以及 502 的排查方法
本文地址:https://www.xiaotiewinner.com/2026/docker-compose-nginx-reverse-proxy-502.html
版权说明:若无注明,本文皆为 小铁的博客 原创,转载请保留文章出处。