使用PDM作为依赖管理器的多阶段构建FastAPI容器启动报错求助

问题重现 #

你的项目结构如下：

backend
|- src/backend
|  |- main.py
|- Dockerfile
|- pdm.lock
|- pyproject.toml
|- README.md

使用提供的Dockerfile构建并运行后，出现错误：exec /.venv/bin/uvicorn: no such file or directory，但进入容器执行which uvicorn却能返回/.venv/bin/uvicorn。

问题原因 #

1. PATH环境变量配置错误：Dockerfile中ENV PATH="/.venv/bin:{$PATH}"的写法有误，{$PATH}会被当作字符串而非环境变量解析，导致虚拟环境的bin目录未正确加入系统路径。
2. 构建阶段虚拟环境创建不明确：PDM默认会在当前目录创建虚拟环境，但未明确指定路径时，可能出现依赖安装路径不一致的问题。
3. Python Slim镜像缺少系统依赖：Slim镜像剔除了很多系统库，部分Python包（即使是纯Python包）可能依赖基础系统组件才能正常执行。

修正后的Dockerfile #

ARG PYTHON_BASE=3.10-slim

# Build stage
FROM python:$PYTHON_BASE as build

# 设置工作目录，避免文件散落在根目录
WORKDIR /app

# 复制项目配置文件
COPY pyproject.toml pdm.lock README.md ./

# 安装系统依赖（用于编译可能的二进制包）
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# 安装PDM并升级pip
RUN python -m pip install --upgrade pip setuptools wheel \
    && pip install pdm

# 明确创建虚拟环境到指定路径，并安装依赖
RUN pdm venv create --name .venv --python python \
    && pdm install --no-lock --no-editable --venv /.venv

# Run stage
FROM python:$PYTHON_BASE

# 设置工作目录
WORKDIR /app

# 安装运行阶段必要的系统依赖（根据项目需求调整，比如如果用到数据库需要libpq-dev等）
RUN apt-get update && apt-get install -y --no-install-recommends \
    libgomp1 \
    && rm -rf /var/lib/apt/lists/*

# 复制应用代码和配置文件
COPY src /app/src
COPY logging_config.yaml /app/

# 从构建阶段复制虚拟环境
COPY --from=build /.venv /.venv

# 修正PATH环境变量配置
ENV PATH="/.venv/bin:$PATH"

EXPOSE 5000

# 使用绝对路径执行uvicorn，确保路径正确
CMD ["/.venv/bin/uvicorn", "src.backend.main:app", "--host", "0.0.0.0", "--port", "5000"]

关键修正点说明 #

• 设置工作目录：在构建和运行阶段都指定WORKDIR /app，让文件结构更清晰，避免路径混乱。
• 修正PATH变量：将{$PATH}改为$PATH，确保虚拟环境的bin目录被正确加入系统路径。
• 明确虚拟环境路径：使用pdm venv create指定虚拟环境位置为/.venv，确保依赖安装到统一路径。
• 添加系统依赖：在构建阶段安装编译工具（如gcc），运行阶段添加必要的系统库（如libgomp1），解决Slim镜像缺少组件的问题。
• 使用绝对路径执行uvicorn：直接调用/.venv/bin/uvicorn，绕过PATH可能存在的解析问题，确保执行正确的二进制文件。

验证步骤 #

1. 重新构建镜像：

sudo docker build -t backend:v0.1.0 .

2. 运行容器：

sudo docker run -p 5000:5000 backend:v0.1.0

3. 测试接口：访问http://localhost:5000/docs验证FastAPI应用是否正常运行。

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