← 返回列表

如何构建现代化的Python Runtime工程镜像

单站 qz安全情报分析 发布 Mon, 10 Nov 2025 19:14:00 +0800 入库 2026-11-18T05:06:03

原创 rayh4c 2025-11-10 19:14 北京

在现代软件交付体系中,运行环境的标准化是加速交付、提升可维护性的关键环节。

Runtime 镜像的职责:

提供稳定、轻量、无构建工具的运行环境,用于执行外部磁盘上的 Python 应用代码。

核心目标:

  1. 1. 不包含构建工具:uv、pip、setuptools、wheel 等全部剔除。
  2. 2. 不包含源码或脚本:应用逻辑完全通过挂载卷加载。
  3. 3. 仅保留执行所需依赖:确保最小运行时体积与攻击面。

镜像采用典型的两阶段构建模型:

| 阶段 | 内容 | 是否保留 |
| Builder | 安装 uv、构建虚拟环境、安装依赖 | 否(中间产物) |
| Runtime | 仅复制虚拟环境中的可执行依赖与 Python | 是 |

# syntax=docker/dockerfile:1.13
########################
# 1. 构建阶段 (Builder)
########################
FROM python:3.13-slim-bookworm AS builder
RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates \
    && rm -rf /var/lib/apt/lists/*# 安装 uv 仅用于构建依赖
RUN pip install --no-cache-dir uv
WORKDIR /build
# 复制依赖定义文件
COPY pyproject.toml uv.lock ./
# 创建虚拟环境并安装依赖(含 pip、uv)
RUN uv venv /opt/venv \
    && /opt/venv/bin/uv pip install --locked --no-dev --compile# 彻底移除构建工具(保证纯运行时)
RUN /opt/venv/bin/python -m pip uninstall -y pip setuptools wheel uv build || true
########################
# 2. 运行阶段 (Runtime)
########################
FROM python:3.13-slim-bookworm
# 创建非 root 用户
RUN useradd --create-home appuser
USER appuser
WORKDIR /runtime
# 仅复制虚拟环境,不包含构建工具
COPY --from=builder /opt/venv /opt/venv
# 设置环境变量
ENV VIRTUAL_ENV=/opt/venv
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
# 运行时从环境变量指定脚本路径执行
ENV APP_ENTRY=/app/main.py
ENTRYPOINT ["sh", "-c", "python \"$APP_ENTRY\""]

docker run --rm company/python-runtime:uv-2025.03 python -m site
输出应仅包含 /opt/venv/lib/python3.13/site-packages。

docker run --rm company/python-runtime:uv-2025.03 which pip || echo"✅ pip removed"
docker run --rm company/python-runtime:uv-2025.03 which uv || echo"✅ uv removed"
docker run --rm \
  -v /srv/app:/app \
  -e APP_ENTRY=/app/main.py \
  company/python-runtime:uv-2025.03

镜像从外部加载 /srv/app/main.py 并执行。

无论代码更新与否,Runtime 镜像本身均无需重建。

| 原则 | 描述 |
| 构建环境与运行环境彻底分离 | 构建依赖仅存在于 builder 层 |
| 无构建工具残留 | 移除 pip、uv、setuptools 等构建器 |
| 只读运行环境 | 不包含源代码、构建脚本、测试文件 |
| 高安全性 | 运行镜像权限最小化,无 shell 工具链 |
| 多应用复用 | 通过挂载路径加载任意外部脚本执行 |

# 执行 APP1
docker run --rm \
  -v /srv/app1:/app \
  -e APP_ENTRY=/app/main.py \
  company/python-runtime:uv-2025.03
# 执行 APP2
docker run --rm \
  -v /srv/app2:/app \
  -e APP_ENTRY=/app/start_server.py \
  company/python-runtime:uv-2025.03

所有应用共享相同 Runtime 镜像,仅通过挂载和入口变量区分。

镜像本身无需修改,也不会包含任何业务数据。

  1. 1. 锁定依赖版本
    在构建阶段使用 uv.lock,确保结果可复现。
    版本号建议包含时间戳:
    company/python-runtime:uv-2025.03
  2. 2. 保持最小基镜像
    推荐 python:<version>-slim-bookworm 或更轻量的 distroless Python 镜像。
  3. 3. 禁止安装额外系统工具
    除非确有需要,不应在 runtime 层安装 bash、curl、vim 等工具。
  4. 4. 定期重建
    通过 --no-cache --pull 拉取最新安全补丁:
    docker build --no-cache --pull -t company/python-runtime:uv-2025.04 .

一个合格的现代化 Python Runtime 镜像应当:

通过这种方式,镜像不再是“代码容器”,而是一个标准化的执行环境载体(Runtime Environment Image),

能够在 CI/CD 或多项目环境中灵活运行任何 Python 应用。

原文链接:https://mp.weixin.qq.com/s?__biz=MzI1MDA1MjcxMw==&mid=2649908749&idx=1&sn=b39079556d8ba8c2168862d19a848987