把 Python 镜像从 1.2 GB 压到 190 MB:一次 Docker 多阶段构建的完整复盘

举报
yd_214121775 发表于 2026/11/11 16:24:02 2026/11/11
【摘要】 不改一行业务代码,只调整 Dockerfile 的构建方式,把 FastAPI 服务镜像从 1.2 GB 压到 190 MB。记录了多阶段构建写法、.dockerignore、非 root 运行三个实战细节。

为什么镜像会越做越大

很多 Python 项目的 Dockerfile 第一版都是这样写的:拉一个完整的 python:3.12 基础镜像,pip install 所有依赖,再把源码 COPY 进去。本地跑没问题,一上 CI 就发现镜像 1 GB 起步,拉取一次要几分钟,漏洞扫描还报一堆由于编译工具链带进来的 CVE。

我最近把一个 FastAPI 服务的镜像从 1.2 GB 压到 190 MB,整个过程没有改一行业务代码,只调整了 Dockerfile 的构建方式和几个工程细节。下面把过程和踩过的坑记录下来。

改造前的单阶段构建

FROM python:3.12
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

问题很直观:python:3.12 本身带着 gcc、g++、头文件等编译工具;pip 下载的 wheel 缓存和源码 tar 包也都留在了镜像层里;再加上 COPY . . 把 .git、测试数据、虚拟环境目录一起打了进去。最终镜像 1.2 GB 并不奇怪。

多阶段构建怎么切

多阶段构建的核心思路是:编译和安装在一个"胖"阶段完成,运行时只拷贝产物。

# 阶段一:构建依赖
FROM python:3.12-slim AS builder
WORKDIR /build
ENV PIP_NO_CACHE_DIR=1 PIP_DISABLE_PIP_VERSION_CHECK=1
COPY requirements.txt .
RUN python -m venv /opt/venv \
    && /opt/venv/bin/pip install -r requirements.txt

# 阶段二:运行时
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY app ./app
RUN useradd -r -u 10001 appuser
USER appuser
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request;urllib.request.urlopen('http://127.0.0.1:8000/health')"
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

第一阶段安装依赖,第二阶段只拷贝虚拟环境目录 site-packages 和业务代码。slim 基础镜像去掉了大部分编译工具和文档,体积本身就从 1 GB 降到了 130 MB 左右。

三个容易忽略的细节

第一,用 venv 而不是把包装进系统 Python。 直接 pip install 到系统目录,第二阶段很难只拷贝"依赖产物",容易把 __pycache__、bin 下的脚本、dist-info 一起带过去。建一个独立 venv 再整目录拷贝,路径清晰、可回滚。

第二,.dockerignore 比想象中重要。

.git
.venv
__pycache__
*.pyc
tests/
data/

我第一版忘了写,COPY . . 把 400 MB 的测试数据一起塞进了镜像,白折腾一场。

第三,运行时不要用 root。 加一个 uid 10001 的非 root 用户,并在 EXPOSE 后加 HEALTHCHECK。前者是安全基线要求,后者能让编排平台真正判断容器是否存活,而不是只看进程在不在。

效果对比

改造后镜像从 1.2 GB 降到 190 MB,CI 拉取时间从约 90 秒降到 15 秒左右,漏洞扫描的高危项也从两位数降到个位数。构建时间因为分成两层,非依赖变更时还能命中缓存,日常迭代反而更快。

小结

多阶段构建不是"高级技巧",而是容器化 Python 服务的基本功。真正决定镜像体积的往往不是基础镜像,而是构建过程中有没有把编译期的东西留在运行期。先想清楚"运行时到底需要什么",再决定每个 COPY 和 RUN 放在哪个阶段,镜像体积自然会下来。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。