大家好，我是展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。
图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG
我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。
展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！
文章目录
- 前言
- 基础 Dockerfile 示例
- 多阶段构建减小体积
- .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：后续 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')或 pydanticSettings读取即可。
健康检查
在 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 与生产部署。
)
