原创 rayh4c 2025-11-10 19:14 北京
在现代软件交付体系中,运行环境的标准化是加速交付、提升可维护性的关键环节。
Runtime 镜像的职责:
提供稳定、轻量、无构建工具的运行环境,用于执行外部磁盘上的 Python 应用代码。
核心目标:
- 1. 不包含构建工具:
uv、pip、setuptools、wheel等全部剔除。 - 2. 不包含源码或脚本:应用逻辑完全通过挂载卷加载。
- 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. 锁定依赖版本
在构建阶段使用uv.lock,确保结果可复现。
版本号建议包含时间戳:
company/python-runtime:uv-2025.03 - 2. 保持最小基镜像
推荐python:<version>-slim-bookworm或更轻量的distrolessPython 镜像。 - 3. 禁止安装额外系统工具
除非确有需要,不应在 runtime 层安装bash、curl、vim等工具。 - 4. 定期重建
通过--no-cache --pull拉取最新安全补丁:
docker build --no-cache --pull -t company/python-runtime:uv-2025.04 .
一个合格的现代化 Python Runtime 镜像应当:
- • 不包含 uv、pip、setuptools、wheel;
- • 仅保留执行所需依赖;
- • 通过外部挂载脚本动态加载应用逻辑;
- • 安全、轻量、可复用、易维护。
通过这种方式,镜像不再是“代码容器”,而是一个标准化的执行环境载体(Runtime Environment Image),
能够在 CI/CD 或多项目环境中灵活运行任何 Python 应用。