前言

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

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

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

多階段構(gòu)建減小體積

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

# 構(gòu)建階段（可選：需要編譯時用）
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 的結(jié)果從 builder 拷到最終鏡像，避免把構(gòu)建工具、臨時文件帶進去。若依賴全是 wheel，也可以不用 builder，只在最終階段裝依賴。

.dockerignore 減少上下文與層

在項目根目錄建 .dockerignore，避免把無關(guān)文件打進鏡像、拉長構(gòu)建時間：

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

這樣 COPY . . 不會包含上述內(nèi)容，鏡像更干凈，構(gòu)建更快。

非 root 運行（可選但推薦）

在 Dockerfile 中新建用戶并用該用戶運行進程，降低容器內(nèi)權(quán)限風(fēng)險：

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"]

注意：若應(yīng)用要寫當(dāng)前目錄（如日志、上傳），需保證 WORKDIR 對 app 可寫；掛載卷時也要注意宿主目錄權(quán)限。

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

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

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

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

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

應(yīng)用內(nèi)用 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

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

總結(jié)

• 基礎(chǔ)鏡像選 slim，先 COPY requirements 再 COPY 代碼，用 --no-cache-dir，CMD 用數(shù)組。
• 需要時用多階段構(gòu)建和 .dockerignore 減小體積、加快構(gòu)建。
• 推薦非 root 用戶運行，敏感配置用環(huán)境變量注入，按需加 HEALTHCHECK。

按上述方式構(gòu)建的 FastAPI 鏡像更小、更安全、更利于 CI/CD 與生產(chǎn)部署。

到此這篇關(guān)于使用Docker構(gòu)建Python FastAPI鏡像的最佳實踐的文章就介紹到這了,更多相關(guān)Docker構(gòu)建Python FastAPI鏡像內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！