4、vLLM镜像构建：Dockerfile编写、多阶段构建、CUDA与PyTorch版本兼容性、镜像瘦身与安全扫描

镜像构建这事儿，说简单也简单，说复杂能让你折腾一整天。我刚开始做vLLM部署时，就踩过不少坑。最惨的一次，镜像打出来3个多G，传到私有仓库花了快半小时，结果拉下来跑不起来——CUDA版本对不上。嗯，从那以后，我对镜像构建就格外上心。

今天咱们就把vLLM的镜像构建聊透。从Dockerfile怎么写，到多阶段构建怎么玩，再到版本兼容性怎么排查，最后聊聊镜像瘦身和安全扫描。这些都是我在生产环境里摸爬滚打出来的经验。

4.1 Dockerfile编写：从零开始

先看一个基础的Dockerfile。我个人习惯用nvidia/cuda作为基础镜像，而不是python:3.x。为什么？因为vLLM依赖CUDA运行时，用官方CUDA镜像能少很多麻烦。

# 基础镜像：CUDA 12.1 + cuDNN 8.9
FROM nvidia/cuda:12.1.0-cudnn8-devel-ubuntu22.04 AS base

# 设置环境变量
ENV PYTHONUNBUFFERED=1 \
    DEBIAN_FRONTEND=noninteractive \
    TZ=Asia/Shanghai

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    python3.10 \
    python3-pip \
    git \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# 设置Python软链接
RUN ln -sf /usr/bin/python3.10 /usr/bin/python

# 安装PyTorch（CUDA 12.1对应版本）
RUN pip install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu121

# 安装vLLM
RUN pip install vllm==0.4.2

# 工作目录
WORKDIR /app
COPY . .

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["python", "-m", "vllm.entrypoints.openai.api_server", "--model", "/model", "--port", "8000"]

这个Dockerfile能跑，但问题不少。你想想看，所有东西都塞在一个层里，镜像体积大，构建也慢。我在项目中遇到过，这种单阶段构建的镜像，动不动就4-5个G，传到K8s节点上，拉取时间够你喝杯咖啡的。

4.2 多阶段构建：瘦身的开始

多阶段构建，说白了就是把构建环境和运行环境分开。构建环境里装编译器、头文件、开发库，运行环境只保留可执行文件和运行时依赖。这样镜像能小很多。

# 第一阶段：构建环境
FROM nvidia/cuda:12.1.0-cudnn8-devel-ubuntu22.04 AS builder

ENV PYTHONUNBUFFERED=1 \
    DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y \
    python3.10 \
    python3-pip \
    git \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

RUN ln -sf /usr/bin/python3.10 /usr/bin/python

# 安装PyTorch和vLLM（带编译）
RUN pip install torch==2.1.2 --index-url https://download.pytorch.org/whl/cu121
RUN pip install vllm==0.4.2

# 第二阶段：运行环境
FROM nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04 AS runtime

ENV PYTHONUNBUFFERED=1 \
    DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y \
    python3.10 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

RUN ln -sf /usr/bin/python3.10 /usr/bin/python

# 从构建阶段复制依赖
COPY --from=builder /usr/local/lib/python3.10/dist-packages /usr/local/lib/python3.10/dist-packages
COPY --from=builder /usr/local/bin /usr/local/bin

WORKDIR /app
COPY . .

EXPOSE 8000
CMD ["python", "-m", "vllm.entrypoints.openai.api_server", "--model", "/model", "--port", "8000"]

看到区别了吗？第一阶段用devel镜像（带开发工具），第二阶段用runtime镜像（只带运行时）。我测试过，这样构建出来的镜像，体积能减少40%左右。从4.2G降到2.5G，效果很明显。

4.3 CUDA与PyTorch版本兼容性

版本兼容性这块，我吃过不少亏。有一次升级了CUDA驱动，忘了更新PyTorch，结果vLLM推理时直接报CUDA error: no kernel image is available for execution on the device。排查了半天，才发现是CUDA版本不匹配。

这里我整理了一个兼容性对照表，建议你保存下来：

怎么确认当前环境的CUDA版本？运行nvidia-smi看顶部信息，或者用nvcc --version。我建议两个都查一下，因为驱动版本和运行时版本可能不一致。

4.4 镜像瘦身：能省则省

镜像瘦身，说白了就是「断舍离」。哪些东西可以删？我总结了几条经验：

• 删除apt缓存：rm -rf /var/lib/apt/lists/*，这能省几十MB
• 删除pip缓存：rm -rf ~/.cache/pip，这能省几百MB
• 删除不必要的工具：比如git、build-essential，构建完就可以删了
• 合并RUN指令：减少镜像层数，但别过度合并，否则缓存失效
• 使用--no-install-recommends：apt安装时加上这个参数，避免安装推荐包

来看一个优化后的Dockerfile片段：

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.10 \
    python3-pip \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && pip install --no-cache-dir torch==2.1.2 --index-url https://download.pytorch.org/whl/cu121 \
    && pip install --no-cache-dir vllm==0.4.2 \
    && rm -rf ~/.cache/pip

这样优化后，镜像体积能再降20%左右。我有个项目，从最初的4.5G优化到了1.8G，部署速度提升了一倍多。

4.5 安全扫描：别留后门

镜像安全这事儿，很多人容易忽略。你想想看，一个带漏洞的镜像部署到生产环境，等于给黑客留了后门。我建议用trivy或grype做安全扫描。

安装trivy很简单：

# 安装trivy
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh

# 扫描镜像
trivy image vllm:latest

# 输出结果示例
# Total: 15 (UNKNOWN: 0, LOW: 8, MEDIUM: 5, HIGH: 2, CRITICAL: 0)

扫描结果会列出每个漏洞的CVE编号、严重等级和修复建议。我一般会重点关注HIGH和CRITICAL级别的漏洞，LOW和MEDIUM可以酌情处理。

另外，建议在CI/CD流程里集成安全扫描。比如在GitLab CI或Jenkins里，构建完镜像自动触发扫描，如果发现高危漏洞就阻断发布。这样能避免带病上线。

4.6 本章小结

镜像构建这块，核心就四点：

• Dockerfile编写：用CUDA基础镜像，注意版本对应
• 多阶段构建：构建环境和运行环境分离，体积能降40%
• 版本兼容性：CUDA、PyTorch、vLLM三者版本必须匹配
• 瘦身与安全：删缓存、删工具、做扫描，一个都不能少

说实话，镜像构建这事儿，看着简单，但细节特别多。我刚开始做的时候，光版本兼容性问题就折腾了两天。后来养成了习惯，每次构建前先查版本对照表，再也没出过问题。

下一节咱们聊聊K8s上的部署配置，包括资源限制、GPU调度、自动扩缩容这些实战内容。到时候我会分享一些我在生产环境里踩过的坑，保证让你少走弯路。