使用Poetry与Gunicorn的Docker多阶段构建失败：Gunicorn未找到

问题根源 #

核心问题是虚拟环境路径硬编码：Builder阶段创建的虚拟环境/app/.venv里，Gunicorn等脚本的开头shebang（比如#!/app/.venv/bin/python）固定指向builder阶段的Python路径。当把虚拟环境复制到Runtime阶段的/app2/.venv后，这个路径在Runtime容器中不存在，系统找不到对应的Python解释器，所以即便文件存在、PATH也配置正确，还是会报错“gunicorn: not found”。

另外你使用了不同的基础镜像（Builder是slim-bookworm，Runtime是bookworm），slim镜像可能缺少部分系统依赖，也会导致复制过来的二进制文件无法正常执行。

解决方案 #

方案1：避免复制虚拟环境，用Poetry导出依赖后在Runtime安装（推荐） #

多阶段构建的最佳实践是不在阶段间复制虚拟环境，而是导出依赖清单，在Runtime直接安装，既避免路径问题，还能减少镜像体积。修改后的Dockerfile如下：

FROM python:3.12.2-slim-bookworm as builder

ENV POETRY_NO_INTERACTION=1 \
    POETRY_VIRTUALENVS_IN_PROJECT=true \
    POETRY_VIRTUALENVS_CREATE=1 \
    POETRY_CACHE_DIR=/tmp/poetry_cache

WORKDIR /app

RUN pip install poetry
COPY pyproject.toml poetry.lock ./

# 导出生产依赖到requirements.txt
RUN poetry export --without-hashes --format=requirements.txt > requirements.txt


# ######## RUNTIME ########
FROM python:3.12.2-slim-bookworm as runtime  # 和builder使用相同基础镜像，减少依赖差异

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

WORKDIR /app

# 复制依赖清单并安装
COPY --from=builder /app/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制你的应用代码（按需添加）
# COPY . .

# 直接执行gunicorn，无需配置虚拟环境PATH
CMD ["gunicorn", "your_app_module:app"]

方案2：保持虚拟环境路径一致 #

如果坚持要复制虚拟环境，需确保Builder和Runtime的虚拟环境路径完全相同，让shebang的路径在Runtime中有效：

FROM python:3.12.2-slim-bookworm as builder

ENV POETRY_NO_INTERACTION=1 \
    POETRY_VIRTUALENVS_IN_PROJECT=true \
    POETRY_VIRTUALENVS_CREATE=1 \
    POETRY_CACHE_DIR=/tmp/poetry_cache

WORKDIR /app

RUN pip install poetry
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root && rm -rf $POETRY_CACHE_DIR


# ######## RUNTIME ########
FROM python:3.12.2-slim-bookworm as runtime  # 与builder使用相同基础镜像

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

WORKDIR /app  # 和builder保持相同工作目录

COPY --from=builder /app/. /app

ENV PATH="/app/.venv/bin:$PATH"

CMD ["gunicorn", "your_app_module:app"]

额外检查点 #

• 补充系统依赖：如果Gunicorn依赖特定系统库（比如连接PostgreSQL需要libpq），需在Runtime阶段安装，例如slim镜像可执行apt-get install -y --no-install-recommends libpq-dev。
• 确认文件权限：复制后的Gunicorn脚本需保证可执行权限，可在Runtime阶段添加RUN chmod +x /app/.venv/bin/gunicorn（通常复制时会保留原有权限，按需添加）。

内容的提问来源于stack exchange，提问作者Richard de Weerd