打开网站,浏览器只显示 502 Bad Gateway。回到服务器一看,容器明明还在运行,Nginx 的配置检查也通过了。这种情况很容易让人开始反复重启,却不知道应该改哪一行。
先从 Nginx 要访问的地址查起。尤其是用 Docker 部署时,127.0.0.1 指向谁、该填哪个端口,经常和直觉不一样。
下面搭一个能正常打开的小网站,再故意改错几处配置。每次都看一下日志,找到原因后恢复。遇到自己的 502 问题,可以直接从“地址写成 127.0.0.1”那一节开始对照。
先把这三个端口分清
这次用两个容器:app 保存网页,gateway 负责接收访问,再去 app 取网页。这里说的“反向代理”,做的就是后面这件事。
| 位置 | 端口 | 用在哪里 |
|---|---|---|
| 服务器 | 18980 | 浏览器或 curl 访问的入口 |
| gateway 容器 | 80 | gateway 自己接收请求的端口 |
| app 容器 | 8080 | 网页实际所在的端口 |
请求会按这个顺序走:浏览器 → 服务器的 18980 → gateway 的 80 → app 的 8080。
所以稍后配置 proxy_pass,要写的是 app:8080。服务器的 18980 是留给外面访问的,不用填到这里。
下面的文件创建命令在 Linux 终端里执行,Windows 可以用 WSL。先确认 Docker、Compose 和 curl 已经能用:
docker version
docker compose version
curl --versiondocker version 应当同时显示 Client 和 Server。没有 Server,说明还没连上 Docker 服务,先处理这个问题。提示 Docker socket 权限不足时,可以使用有权限的账号,或在下文的 Docker 命令前加 sudo。
建好四个文件
新建一个演示目录,后面的命令都在这里执行:
mkdir -p ~/nginx-502-demo/site ~/nginx-502-demo/nginx
cd ~/nginx-502-demo
pwdpwd 显示的路径应当以 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;
}
}
EOFproxy_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 里面的地址和端口还要靠实际访问确认。

四份文件已经创建好,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>
页面打开后,能看到刚才写入的两行文字。
如果这里返回 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。

浏览器只告诉我们访问失败。具体连错了哪里,要看 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 failednot-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 端口发布。