FastAPI+Poetry项目在Digital Ocean部署失败求助

核心问题定位 #

你的问题本质是容器环境与本地开发环境的路径、依赖安装逻辑差异，导致自项目包导入失败、容器挂起，进而触发健康检查错误。以下是针对性的解决方案：

1. 修正Poetry包配置与Docker安装逻辑 #

调整pyproject.toml包配置 #

确保包路径声明准确，覆盖src目录下的humblapi包：

[tool.poetry]
name = "humblapi"
version = "0.1.0"
packages = [{ include = "humblapi", from = "src" }]

[tool.poetry.dependencies]
python = "^3.10"
fastapi = "^0.104.1"
# 其他生产依赖...

[tool.poetry.dev-dependencies]
# 仅保留开发环境依赖，生产安装时会跳过

优化Dockerfile的安装步骤 #

避免虚拟环境路径冲突，同时解决pywry的系统依赖问题：

FROM python:3.10-slim

# 安装系统依赖（解决libsoup-2.4缺失、pywry编译问题）
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    libsoup2.4-dev \
    libwebkit2gtk-4.0-dev \
    && rm -rf /var/lib/apt/lists/*

# 安装Poetry并禁用虚拟环境（直接使用系统Python路径）
RUN pip install --no-cache-dir poetry
RUN poetry config virtualenvs.create false

WORKDIR /app

# 先复制依赖配置文件，利用Docker缓存
COPY pyproject.toml poetry.lock ./
# 复制完整的src目录
COPY src/ ./src/

# 安装生产依赖与项目包（跳过开发依赖）
RUN poetry install --no-dev

# 强制FastAPI监听0.0.0.0和DO默认端口8080
CMD ["uvicorn", "humblapi.main:app", "--host", "0.0.0.0", "--port", "8080"]

2. 验证包安装状态 #

在Dockerfile中添加调试步骤，确认humblapi包是否被正确安装到Python的site-packages目录：

# 在poetry install之后添加
RUN python -c "import humblapi; print('包路径:', humblapi.__file__)"

如果运行时输出包路径（如/usr/local/lib/python3.10/site-packages/humblapi/__init__.py），说明安装正常；若报错ModuleNotFoundError，则需检查pyproject.toml的packages配置或src目录结构。

3. 修复健康检查失败问题 #

Digital Ocean App Platform默认会访问容器的/路径做健康检查，需确保你的FastAPI应用有对应路由：

# 在humblapi/main.py中添加健康检查路由
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def health_check():
    return {"status": "running"}

# 其他业务路由...

若你使用自定义健康端点（如/health），需在DO App Platform的部署设置中修改健康检查的目标路径。

4. 多阶段构建优化（可选） #

如果需要更小的镜像体积，可采用多阶段构建，将编译依赖与运行依赖分离：

# 构建阶段：处理编译依赖与包构建
FROM python:3.10-slim AS builder

RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    libsoup2.4-dev \
    libwebkit2gtk-4.0-dev \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir poetry
RUN poetry config virtualenvs.create false

WORKDIR /app
COPY pyproject.toml poetry.lock ./
COPY src/ ./src/

# 构建wheel包
RUN poetry build

# 运行阶段：仅保留运行依赖
FROM python:3.10-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    libwebkit2gtk-4.0-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=builder /app/dist/*.whl ./
# 安装构建好的wheel包
RUN pip install --no-cache-dir *.whl

CMD ["uvicorn", "humblapi.main:app", "--host", "0.0.0.0", "--port", "8080"]

5. 排查容器启动日志 #

在Digital Ocean App Platform的部署控制台中查看完整容器启动日志，不要只依赖表面的错误提示：

• 若日志显示ModuleNotFoundError: No module named 'humblapi'：检查src目录是否被完整复制、pyproject.toml的packages配置是否正确；
• 若日志显示导入子模块失败：确认humblapi/core/等子目录下存在__init__.py文件（即使是空文件，也需存在以标记为Python包）。

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