使用Docker構建Python FastAPI鏡像的最佳實踐

更新時間：2026年02月03日 08:26:22 作者：展菲

本文分享了優(yōu)化Python FastAPI應用Docker部署的關鍵技巧：使用slim基礎鏡像減小體積,通過多階段構建分離編譯與運行環(huán)境,利用.dockerignore排除無關文件,推薦采用非root用戶運行增強安全性,需要的朋友可以參考下

前言

用 Docker 部署 Python FastAPI 應用時，鏡像過大會拖慢拉取和部署，依賴或權限不當又容易帶來安全與可維護性問題。通過多階段構建、精簡基礎鏡像、非 root 運行等方式，可以在保證功能的前提下減小體積并提升安全性。

本文只講 Dockerfile 的關鍵寫法和注意點，不貼完整可運行項目。

基礎 Dockerfile 示例

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

要點：

python:3.11-slim：相比默認 python:3.11 體積小很多，一般已夠用；若依賴 C 庫，再考慮 slim 或 alpine 的取舍。
WORKDIR /app：后續(xù) COPY、RUN 都在此目錄，便于路徑統(tǒng)一。
先 COPY requirements.txt 再 COPY .：利用層緩存，依賴不變時不會重復 pip install。
–no-cache-dir：不保留 pip 緩存，減小鏡像體積。
CMD 用數(shù)組形式：避免通過 shell 解析，信號能正確傳到 uvicorn。

多階段構建減小體積

若構建階段需要編譯或額外工具，可用多階段：第一階段裝依賴、編譯，第二階段只保留運行時需要的文件。

# 構建階段（可選：需要編譯時用）
FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt

# 運行階段
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
ENV PATH=/root/.local/bin:$PATH
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

這里把 pip install --user 的結果從 builder 拷到最終鏡像，避免把構建工具、臨時文件帶進去。若依賴全是 wheel，也可以不用 builder，只在最終階段裝依賴。

.dockerignore 減少上下文與層

在項目根目錄建 .dockerignore，避免把無關文件打進鏡像、拉長構建時間：

__pycache__
*.pyc
.git
.venv
venv
.env
*.md
tests
.pytest_cache
.coverage
htmlcov

這樣 COPY . . 不會包含上述內容，鏡像更干凈，構建更快。

非 root 運行（可選但推薦）

在 Dockerfile 中新建用戶并用該用戶運行進程，降低容器內權限風險：

FROM python:3.11-slim

RUN groupadd -r app && useradd -r -g app app

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY --chown=app:app . .

USER app
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

注意：若應用要寫當前目錄（如日志、上傳），需保證 WORKDIR 對 app 可寫；掛載卷時也要注意宿主目錄權限。

環(huán)境變量與配置

敏感信息（如 DB 地址、密鑰）不要寫進鏡像，運行時通過環(huán)境變量或掛載注入：

ENV PYTHONUNBUFFERED=1
# 不在這里寫 DATABASE_URL、SECRET_KEY 等

在 docker run 或 docker-compose.yml 中傳：

environment:
  - DATABASE_URL=postgresql://...
  - SECRET_KEY=...

應用內用 os.getenv('DATABASE_URL') 或 pydantic Settings 讀取即可。

健康檢查

在 Dockerfile 或 compose 中加健康檢查，便于編排系統(tǒng)判斷容器是否就緒：

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')" || exit 1

前提是應用提供 /health 等輕量接口；若沒有，可先用 curl 或 wget 測根路徑，或暫時去掉 HEALTHCHECK。