Docker容器部署FastAPI遇Uvicorn端口与路由NotFound问题排查

问题原因及解决步骤 #

1. 容器内端口占用问题 #

容器启动时，Dockerfile中的CMD指令已经启动了gunicorn服务并绑定8000端口，此时手动执行uvicorn命令必然提示端口被占用。无需在容器内重复启动服务，gunicorn已负责运行FastAPI应用。

2. 访问返回"Not Found"的问题 #

核心原因是镜像未重新构建，容器内代码并非最新版本，或Dockerfile路径逻辑存在潜在混乱，具体解决步骤如下：

步骤1：重新构建镜像并启动容器

执行以下命令，确保容器使用最新代码和配置：

docker-compose up --build

步骤2：验证容器内代码正确性

进入容器检查app.py的路由是否正确：

# 查看容器ID
docker ps
# 进入容器
docker exec -it <容器ID> /bin/bash
# 检查app.py内容
cd /app && cat app.py

确认@app.get("/home")路由存在且代码无误。

步骤3：优化Dockerfile路径逻辑（可选但推荐）

将所有操作统一在/app目录下进行，避免路径混乱：

FROM python:3.8-slim

EXPOSE 8000

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

# 先设置工作目录
WORKDIR /app

# 复制依赖文件到工作目录并安装
COPY requirements.txt .
RUN python -m pip install -r requirements.txt

# 复制项目代码到工作目录
COPY . /app

RUN adduser -u nnnn --disabled-password --gecos "" appuser && chown -R appuser /app
USER appuser

CMD ["gunicorn", "--bind", "0.0.0.0:8000", "-k", "uvicorn.workers.UvicornWorker", "app:app"]

步骤4：验证容器内服务监听状态

在容器内安装工具并检查端口监听：

apt-get update && apt-get install -y net-tools
netstat -tulpn

确认gunicorn进程正在监听0.0.0.0:8000。

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