基于Docker部署FastAPI+Uvicorn+Gunicorn+Nginx启动失败求助

一、先解决FastAPI容器（web服务）exit code 0的问题 #

Exit code 0不是进程崩溃，是进程正常执行完毕后就退出了——核心原因是容器里没有持续运行的前台进程，大概率是supervisord配置或启动命令有误。

1. 修正supervisord.conf关键配置 #

必须让supervisord保持前台运行，同时确保Gunicorn绑定正确地址：

• 添加nodaemon=true（Docker容器需要前台进程才能存活，禁止supervisord后台运行）
• Gunicorn命令要绑定0.0.0.0:8000（仅绑定127.0.0.1的话，容器外部包括Nginx都无法访问）
• 指定Uvicorn专属worker类，命令中需包含--worker-class uvicorn.workers.UvicornWorker

参考配置片段：

[supervisord]
nodaemon=true
logfile=/var/log/supervisord.log
pidfile=/var/run/supervisord.pid

[program:gunicorn]
command=/opt/venv/bin/gunicorn main:app --workers 2 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
directory=/app
autostart=true
autorestart=true
stdout_logfile=/var/log/gunicorn.out.log
stderr_logfile=/var/log/gunicorn.err.log

2. 调整Dockerfile的启动命令 #

Dockerfile中的CMD必须直接启动supervisord，不能使用后台运行参数：

• 错误示例：CMD ["supervisord", "-c", "/etc/supervisord.conf", "-d"]（-d会让supervisord后台运行，容器直接退出）
• 正确示例：CMD ["supervisord", "-c", "/etc/supervisord.conf"]（依赖配置中的nodaemon=true保持前台运行）
• 或强制前台启动：CMD ["supervisord", "-c", "/etc/supervisord.conf", "-n"]

3. 验证依赖与应用入口 #

• 确认requirements.txt包含fastapi、uvicorn[standard]、gunicorn三个核心包
• 检查main.py中是否有app = FastAPI()的实例定义，确保Gunicorn命令中的main:app与实际文件、实例名对应

二、解决Nginx"host not found in upstream 'web:8000'"问题 #

这个报错是连锁反应——web容器未启动成功，导致Nginx启动时无法解析到web服务域名。搞定web容器后，补充以下配置：

1. 给Nginx添加DNS解析与重试逻辑 #

在app.conf中配置Docker内置DNS和重试规则，避免启动顺序导致的解析失败：

http {
    resolver 127.0.0.11 valid=30s; # Docker内置DNS服务器，必须添加
    upstream web {
        server web:8000;
    }

    server {
        listen 80;
        server_name localhost;

        location / {
            proxy_pass http://web;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            # 允许重试，避免web未启动时的报错
            proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
        }
    }
}

2. 调整docker-compose启动规则 #

给Nginx添加依赖和自动重启配置，确保它等待web服务启动或自动重试：

services:
  web:
    build: .
    restart: always # 服务挂掉自动重启
    volumes:
      - ./app:/app # 挂载代码目录方便调试
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./app.conf:/etc/nginx/nginx.conf # 挂载Nginx配置文件
    depends_on:
      - web # 依赖web服务，优先启动web
    restart: always # 即使初始无法连接web，自动重启直到连通
  mongo:
    image: mongo:latest
    restart: always
    volumes:
      - mongo_data:/data/db # 持久化数据库数据
volumes:
  mongo_data:

三、调试步骤（若问题仍存在） #

1. 查看web容器日志：docker-compose logs web，排查supervisord或Gunicorn的启动报错
2. 手动进入web容器测试：docker-compose run web bash，手动执行Gunicorn启动命令，验证是否能正常运行
3. 测试网络连通性：docker-compose exec nginx ping web，确认Nginx能解析并ping通web容器

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