网罗开发 （小红书、快手、视频号同名）

  大家好，我是 展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

前言

用 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：后续 COPY、RUN 都在此目录，便于路径统一。
• 先 COPY requirements.txt 再 COPY .：利用层缓存，依赖不变时不会重复 pip install。
• –no-cache-dir：不保留 pip 缓存，减小镜像体积。
• CMD 用数组形式：避免通过 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 可写；挂载卷时也要注意宿主目录权限。

环境变量与配置

敏感信息（如 DB 地址、密钥）不要写进镜像，运行时通过环境变量或挂载注入：

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 中加健康检查，便于编排系统判断容器是否就绪：

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。

总结

• 基础镜像选 slim，先 COPY requirements 再 COPY 代码，用 --no-cache-dir，CMD 用数组。
• 需要时用多阶段构建和 .dockerignore 减小体积、加快构建。
• 推荐非 root 用户运行，敏感配置用环境变量注入，按需加 HEALTHCHECK。

按上述方式构建的 FastAPI 镜像更小、更安全、更利于 CI/CD 与生产部署。