第4章镜像管理实战

4、镜像管理实战：内置镜像解析、自定义镜像构建、将镜像推送到私有仓库

镜像管理，说白了就是 Notebook 的「吃饭家伙」。你想想看，没有合适的镜像，你的代码跑不起来，依赖装不上，环境一塌糊涂。我在做 Kubeflow 落地的时候，遇到过最头疼的问题就是镜像管理混乱——团队里每个人都在用自己的镜像，版本五花八门，最后部署的时候全崩了。

所以这一章，咱们就好好聊聊镜像管理。我会从内置镜像讲起，再到自定义构建，最后推到私有仓库。一条龙走通。

4.1 内置镜像解析：Kubeflow 给你准备了什么？

Kubeflow Notebook 默认带了一批内置镜像。我个人习惯先看看这些镜像里有什么，再决定要不要自己造轮子。

打开 Kubeflow Dashboard，创建 Notebook 的时候，你会看到类似这样的镜像列表：

镜像名称	基础环境	适用场景
jupyter-tensorflow-full	TensorFlow 2.x + Jupyter	深度学习、模型训练
jupyter-pytorch-full	PyTorch 1.x + Jupyter	PyTorch 项目、研究实验
jupyter-scipy	NumPy, Pandas, Scikit-learn	数据分析、传统 ML
rstudio-tidyverse	R 语言 + Tidyverse	统计分析、可视化

这些镜像都是官方维护的，质量有保障。但我得提醒你一句：内置镜像的包版本可能比较旧。我记得有一次，团队用内置的 TensorFlow 镜像跑新模型，结果发现 tf.data 的某个 API 已经 deprecated 了。嗯，这时候就得考虑自定义镜像了。

我的建议： 如果只是做快速验证或学习，直接用内置镜像就行。如果是生产环境，或者有特定版本需求，建议走自定义路线。

4.2 自定义镜像构建：从零开始搭一个 Notebook 镜像

为什么要自己构建镜像？说白了就两个原因：版本控制和依赖管理。你想想看，项目里用到的 Python 包、系统库、甚至 CUDA 版本，都需要精确锁定。不然今天能跑，明天就崩了。

我一般用 Dockerfile 来构建。下面是一个典型的 Notebook 镜像 Dockerfile：

# 基于官方 Jupyter 镜像
FROM jupyter/base-notebook:python-3.9

# 设置环境变量
ENV NB_USER=jovyan
ENV HOME=/home/${NB_USER}

# 切换到 root 安装系统依赖
USER root
RUN apt-get update && apt-get install -y \
    build-essential \
    libssl-dev \
    libffi-dev \
    && rm -rf /var/lib/apt/lists/*

# 安装 Python 依赖
COPY requirements.txt /tmp/
RUN pip install --no-cache-dir -r /tmp/requirements.txt

# 切换回普通用户
USER ${NB_USER}

# 设置工作目录
WORKDIR ${HOME}

这里有个细节：一定要切换回普通用户。Kubeflow Notebook 默认用非 root 用户运行，如果你用 root 装了东西，后面权限会出问题。我曾经因为这个踩过坑，Notebook 启动后写不了文件，排查了半天才发现是用户权限没切回来。

注意： 构建镜像时，尽量把 requirements.txt 里的包版本写死。比如 numpy==1.21.0，而不是 numpy>=1.21.0。这样可以避免意外升级导致的不兼容。

4.3 将镜像推送到私有仓库

镜像构建好了，接下来就是推送。我个人习惯用 Harbor 作为私有仓库，当然 Docker Registry、AWS ECR、阿里云 ACR 也都行。关键是流程要标准化。

推送步骤其实就三步：

打标签：给镜像打上仓库地址的标签
登录：认证到私有仓库
推送：把镜像推上去

具体命令如下：

# 1. 打标签
docker tag my-notebook:latest harbor.mycompany.com/kubeflow/my-notebook:v1.0

# 2. 登录
docker login harbor.mycompany.com -u admin -p yourpassword

# 3. 推送
docker push harbor.mycompany.com/kubeflow/my-notebook:v1.0

嗯，这里要注意一点：镜像命名规范。我建议统一用 项目名/镜像名:版本号 的格式。比如 ml-platform/training-notebook:v1.2。这样在 Kubeflow 里选择镜像的时候，一眼就能看出来是哪个项目的。

  避坑指南： 我曾经遇到过推送成功后，Kubeflow 里却拉不下来镜像。后来发现是私有仓库的证书问题。Kubeflow 默认用 HTTPS 拉镜像，如果你的仓库是自签名证书，需要在 Kubeflow 的配置里加上 insecure-registries。或者，更省事的办法——用 HTTP 协议，但仅限于内网环境。

4.4 知识体系总览

为了让你更直观地理解镜像管理的全流程，我画了一张图：

4.5 实战小贴士

最后，分享几个我在项目中积累的经验：

镜像大小控制：别一股脑把所有包都装进去。我一般只装项目必需的依赖，其他按需安装。镜像太大，拉取和启动都慢。
多阶段构建：如果镜像里有编译步骤，用多阶段构建可以大幅减小最终镜像体积。比如先在一个阶段编译 C 扩展，再把编译产物复制到最终镜像。
版本号管理：别用 latest 标签。我见过太多因为 latest 指向不同版本导致的问题。每次构建都打上明确的版本号，比如 v1.0.0、v1.0.1。
自动化构建：用 CI/CD 流水线自动构建和推送镜像。我习惯在 Git 仓库里放 Dockerfile，每次合并到主分支就自动触发构建。

额外提醒： 如果你用的是 GPU 镜像，记得在 Dockerfile 里安装对应版本的 CUDA 和 cuDNN。Kubeflow 的 GPU Notebook 需要这些底层库才能正常工作。我当初漏装了 cuDNN，结果模型训练速度慢得离谱，排查了半天才发现是 GPU 没真正用上。

好了，镜像管理这块就聊到这儿。记住一句话：镜像管理做得好，环境问题少一半。下一章咱们会深入 Notebook 的存储管理，看看怎么把数据卷和代码仓库挂载进来。嗯，到时候再细聊。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

4、镜像管理实战：内置镜像解析、自定义镜像构建、将镜像推送到私有仓库

4.1 内置镜像解析：Kubeflow 给你准备了什么？

4.2 自定义镜像构建：从零开始搭一个 Notebook 镜像

4.3 将镜像推送到私有仓库

4.4 知识体系总览

4.5 实战小贴士