容器化Nginx代理Flask+Gunicorn报502 Bad Gateway故障排查

持续返回502 Bad Gateway是两个配置错误共同导致的：

• 容器间访问端口配置错误
  同一Docker自定义网络内的容器互访，直接走容器内部网络，与ports字段配置的宿主机端口映射无关。当前app服务的端口映射为4000:5000，代表宿主机4000端口转发到app容器内部的5000端口，但Nginx和app同属mynet网络，互访时应该直接访问容器内部监听的端口，你在nginx.conf中配置的proxy_pass http://app:4000指向的端口无任何服务监听，必然连接失败。
• Gunicorn启动参数缺失，服务未监听可被跨容器访问的地址
  app的Dockerfile中仅配置了CMD gunicorn，无任何启动参数：
  1. Gunicorn默认绑定127.0.0.1:8000，绑定本地回环地址时只有容器内部进程能访问，同网络的Nginx容器无法建立连接
  2. 默认监听的8000端口与配置预期的5000端口不匹配，即使修改绑定地址，端口不匹配也无法连通

1. 修正Nginx反向代理端口配置
   修改nginx.conf中的代理目标地址，指向app容器内部的正确端口：

server {
    listen 80;
    server_name localhost; 
    
    location / {
        proxy_pass http://app:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        client_max_body_size 20M;
      } 
    }

2. 修正Gunicorn启动命令
   修改app目录下Dockerfile的CMD字段，指定Gunicorn绑定0.0.0.0地址（允许跨容器访问）、监听5000端口，同时指定Flask应用入口：

FROM python:3.8-slim-buster
RUN apt-get update \
  && apt-get install -y build-essential netcat\
  && apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false \
  && rm -rf /var/lib/apt/lists/*
RUN adduser --home /app --system --group kr1p
WORKDIR /app
COPY --chown=kr1p:kr1p app .
RUN pip install -r requirements.txt 
USER kr1p
ENV PYTHONUNBUFFERED=1
# 替换原有的CMD gunicorn，后面的app:app替换为你实际的Flask实例路径：<入口文件名>:<应用实例名>
CMD ["gunicorn", "-b", "0.0.0.0:5000", "app:app"]

3. （可选优化）补全服务就绪检查
   默认的depends_on仅等待app容器启动，不会等待Gunicorn服务完成初始化，可能出现Nginx启动时服务未就绪导致的短暂502，可以修改docker-compose.yml增加健康检查：

---
version: '3.7'
services:
  nginx:
    build:
      context: .
      dockerfile: ./nginx/Dockerfile
    restart: always
    ports:
      - 80:80
    depends_on:
      app:
        condition: service_healthy
    networks:
      - mynet
  app:
    container_name: app
    build:
      context: .
      dockerfile: ./app/Dockerfile
    volumes:
      - app:/app
    ports:
      - 4000:5000
    networks:
      - mynet
    healthcheck:
      test: ["CMD", "nc", "-zv", "127.0.0.1", "5000"]
      interval: 3s
      timeout: 2s
      retries: 10

volumes:
  app:
    name: app
networks:
  mynet:

所有配置修改完成后，执行docker compose down -v清理旧容器与网络，再执行docker compose up --build -d重新构建启动服务即可恢复正常。

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