Docker容器间Nginx代理访问后端报Connection refused（502）问题

在Docker Compose环境中配置Nginx反向代理，前端容器访问正常，但访问后端/api路径时出现502错误，错误日志显示connect() failed (111: Connection refused) while connecting to upstream。已确认后端单独运行时可通过localhost:8000访问，前端可通过localhost:3000访问。

相关配置文件 #

docker-compose.yml #

version: "3.1"

services:
  backend:
    image: backend_image
    container_name: backend_container
  frontend:
    container_name: frontend_container
    image: frontend_image
  proxy:
    container_name: proxy_container
    image: nginx
    restart: unless-stopped
    ports:
      - "8080:80"
    depends_on:
      - website
      - frontend

docker-compose-development.yml #

version: "3.1"

services:
  backend:
    container_name: backend_container_development
  frontend:
    build:
      context: ./site/public_html/frontend
      target: runner
    volumes:
      - ./site/public_html/frontend:/app
    command: npm run dev
    ports:
      - "3000:80"
    environment:
      NODE_ENV: development
  proxy:
    volumes:
      - ./nginx/local.conf:/etc/nginx/nginx.conf
      - ./logs:/var/logs

nginx local.conf #

events {
    worker_connections 1024;
}

http {
    server {
        listen 80 default_server;

        location / {
            proxy_pass http://frontend:3000;
            error_log /var/log/frontend_errors.log;
        }

        location /api {
            proxy_pass http://backend:8000;
            error_log /var/log/backend_errors.log;
        }
    }
}

错误日志 #

[error] 29#29: *2 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.48.1, server: , request: "GET /api HTTP/1.1", upstream: "http://192.168.48.3:8000/api", host: "localhost:8080"

排查与修复步骤 #

1. 修正Docker Compose依赖错误 #

主配置文件docker-compose.yml中，proxy服务的depends_on字段写错了服务名，将website改为backend：

proxy:
  # ...其他配置
  depends_on:
    - backend
    - frontend

depends_on仅控制启动顺序，不保证服务就绪，但错误的服务名会导致配置逻辑错误，修正后确保proxy服务依赖正确的后端服务。

2. 确认后端容器内部服务监听地址 #

容器内的后端服务必须监听0.0.0.0:8000，而不是127.0.0.1:8000。如果服务仅监听本地回环地址，其他容器无法通过容器IP或服务名访问：

• 进入后端容器执行：curl localhost:8000，确认服务正常响应
• 检查后端服务的配置，确保绑定地址为0.0.0.0

3. 检查Nginx反向代理路径匹配 #

当前location /api的proxy_pass会将请求转发到http://backend:8000/api，如果后端服务的接口前缀不是/api，需要调整路径：

• 如果后端接口直接使用根路径（如/），将proxy_pass改为http://backend:8000/（末尾加斜杠）：

location /api {
    proxy_pass http://backend:8000/;
    error_log /var/log/backend_errors.log;
}

这样请求/api/xxx会被转发到http://backend:8000/xxx。

4. 确保Docker Compose配置正确合并 #

运行容器时需同时加载两个配置文件，确保开发配置覆盖主配置：

docker-compose -f docker-compose.yml -f docker-compose-development.yml up -d

检查后端容器是否正常启动：

docker-compose logs backend

确认后端服务在容器内已启动并监听8000端口。

5. 验证容器间网络连通性 #

进入proxy容器，测试与backend容器的连通性：

docker exec -it proxy_container curl http://backend:8000

如果无法连通，检查Docker网络配置：

• 查看服务所在网络：docker network ls
• 检查backend容器的网络归属：docker inspect backend_container_development | grep Networks

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