企业官网建设流程全解析

• 云原生
• 开发工具
• 数据科学

本篇以 Jupyter Docker Stacks 官方文档的 FAQ（docs/using/faq.md）为主线，系统讲解容器化运行 Jupyter 应用时最常被问到的四个问题：如何持久化环境与用户数据、为什么官方镜像不预装所有包、默认用户jovyan的来源与结构，以及如何安全地授予容器内用户 root（sudo）权限。读完本文，你能够独立完成子镜像打包来固化依赖、用 bind mount 持久化工作文件，并从 docker-stacks-foundation 入口脚本 的源码层面理解用户与权限机制的工作原理。

一、如何持久化用户数据

FAQ 开篇就把"持久化"拆成两种截然不同、处理方式完全不同的数据类型：

1. 环境数据：你通过mamba、conda、pip、apt-get等工具安装的包；
2. 用户数据：你自己创建的文件，如 Python 脚本、notebook、文本文件等。

1.1 环境持久化：必须在构建期安装，而非运行期安装

在运行中的容器里安装包（例如在容器终端执行pip install <package>）是 FAQ 中特别强调的常见误区：容器停止后，这类变更不会保留到下一次运行。其原因是容器文件系统基于不可变镜像层，运行期的写入发生在可写层，容器销毁即丢失。

正确的做法是：创建一个继承自官方镜像的子镜像（inherited image），在构建 Dockerfile 时一次性安装包。官方文档给出的标准做法（来自 docs/using/recipes.md 的配方）如下。

使用mamba install（官方推荐）：

ARG BASE_IMAGE=quay.io/jupyter/base-notebook FROM $BASE_IMAGE RUN mamba install --yes 'flake8' && \ mamba clean --all -f -y && \ fix-permissions "${CONDA_DIR}" && \ fix-permissions "/home/${NB_USER}" # Install from the requirements.txt file COPY --chown=${NB_UID}:${NB_GID} requirements.txt /tmp/ RUN mamba install --yes --file /tmp/requirements.txt && \ mamba clean --all -f -y && \ fix-permissions "${CONDA_DIR}" && \ fix-permissions "/home/${NB_USER}"

该示例源文件位于 docs/using/recipe_code/mamba_install.dockerfile。pip用法完全类似（docs/using/recipe_code/pip_install.dockerfile）：

ARG BASE_IMAGE=quay.io/jupyter/base-notebook FROM $BASE_IMAGE # Install in the default python3 environment RUN pip install --no-cache-dir 'flake8' && \ fix-permissions "${CONDA_DIR}" && \ fix-permissions "/home/${NB_USER}" # Install from the requirements.txt file COPY --chown=${NB_UID}:${NB_GID} requirements.txt /tmp/ RUN pip install --no-cache-dir --requirement /tmp/requirements.txt && \ fix-permissions "${CONDA_DIR}" && \ fix-permissions "/home/${NB_USER}"

构建并运行子镜像：

docker build --rm --tag my-custom-image . docker run -it --rm \ -p 8888:8888 \ my-custom-image

源码级补充——fix-permissions为何必不可少：构建期安装发生在 root 上下文中，装完必须修正权限，否则运行期以非特权用户启动时无法读写。fix-permissions 脚本对传入目录执行两件事：用find筛选出组不是${NB_GID}或缺少组读写权限的文件，批量chgrp+chmod g+rwX；再对目录单独设置 setgid 位（chmod g+s），使新建文件自动继承${NB_GID}组。该设计用find跳过已符合权限的文件，避免"图像膨胀"（massive image explosion），这一点在脚本头部注释中有明确说明。基础镜像 Dockerfile 在构建阶段就安装了这个脚本。

1.2 用户数据持久化：bind mount 或 Docker Volume

对于脚本、notebook 等用户文件，FAQ 的答案是使用Docker bind mount或Docker Volume。官方运行文档 docs/using/running.md 的 Example 2 给出了可直接复制的 bind mount 示例：

docker run -it --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work quay.io/jupyter/r-notebook:2026-07-28

• -v "${PWD}":/home/jovyan/work把宿主机当前目录挂到容器内/home/jovyan/work；
• 按Ctrl-C两次后容器被--rm销毁，但挂载目录中的新文件和改动会保留在宿主机上，容器内其他位置的改动全部丢失。

需要注意的一个细节：Jupyter 的root_dir默认是/home/jovyan，新 notebook 会默认保存到这里而不是work子目录。若要改变默认目录，可在启动命令中追加参数：

start-notebook.py --ServerApp.root_dir=/home/jovyan/work

如果挂载时遇到Permission denied（典型场景：宿主机目录属主是root，而容器内jovyan用户无法写入），官方文档在 docs/using/troubleshooting.md 的 "Permission denied when mounting volumes" 一节给出了两套方案：

1. 运行时修正挂载目录属主：以 root 启动容器并设置CHOWN_EXTRA环境变量，入口脚本会在运行前执行chown：

   docker run --detach \ -v <my-vol>:<container-dir> \ -p 8888:8888 \ --user root \ -e CHOWN_EXTRA="<container-dir>" \ -e CHOWN_EXTRA_OPTS="-R" \ quay.io/jupyter/minimal-notebook

   若挂载点在/home/之内，也可以改用-e CHOWN_HOME=yes和CHOWN_HOME_OPTS="-R"。

2. 让容器内 UID/GID 与宿主机用户一致：bind mount 会把宿主机权限原样带入容器，因此可显式指定NB_UID/NB_GID（同样需要--user root）：

   docker run -it --rm \ --user root \ -p 8888:8888 \ -e NB_UID=1234 \ -e NB_GID=5678 \ -v "${PWD}"/test:/home/jovyan/work \ quay.io/jupyter/minimal-notebook:latest

   从 start.sh 的源码可以看到其实现：当容器以 root 启动且NB_UID/NB_GID与当前用户不一致时，脚本会用groupadd/useradd重建该用户并打印Update ${NB_USER}'s UID:GID to ...日志；测试用例 test_uid_change 验证了NB_UID=1010后id输出为uid=1010(jovyan)。

二、为什么官方镜像不会预装你"最喜欢"的包

FAQ 对这一问题的回答很直接：用户群体庞大且需求各异，把所有想要的包都装进去是不可能的。因此项目提供了多个镜像层级供选择，策略是：

1. 挑选与你需求最接近的镜像；
2. 在该镜像之上用mamba/pip添加你自己的包（即上文 1.1 的子镜像做法）。

"挑选最接近的镜像"这一步可以借助 docs/using/selecting.md 中的核心镜像族（Core Stacks）。从各 Dockerfile 的FROM语句看，构建依赖树大致为：

docker-stacks-foundation (conda/mamba + jovyan 用户 + tini/start.sh) └── base-notebook (JupyterLab / Notebook / JupyterHub singleuser) └── minimal-notebook (git、curl、TeX Live 等工具) ├── r-notebook ├── julia-notebook └── scipy-notebook ├── tensorflow-notebook (含 CUDA 变体) ├── pytorch-notebook (含 CUDA 变体) ├── datascience-notebook └── pyspark-notebook └── all-spark-notebook

例如 base-notebook 的 Dockerfile 显式继承docker-stacks-foundation；pyspark-notebook 继承 scipy-notebook，all-spark-notebook 再继承 pyspark-notebook。任何一个镜像都完整继承其所有祖先镜像的内容，因此选"更高层级"的镜像意味着获得更多预装包，但镜像也更大。对于 CI 或组织级定制，官方建议优先拉取现成镜像，确有系统级定制需求时再走自建镜像路线（参见 docs/using/custom-images.md）。

三、jovyan用户是谁

FAQ 给出了jovyan名称的出处（源自 Jupyter 社区对该术语的定义，最初在项目的 GitHub issue #358 的评论中被引用）：

Jo·vy·an /ˈjōvēən/ noun – an inhabitant of Jupyter（Jupyter 的居民）

Jovyan是 Jupyter 社区成员的一个特殊称谓，同时被用作 Jupyter Docker Stacks 容器内的默认非特权用户 ID。

源码中的实际定义。jovyan及其 UID/GID 在 images/docker-stacks-foundation/Dockerfile 中通过构建参数固化：

ARG NB_USER="jovyan" ARG NB_UID="1000" ARG NB_GID="100"

随后 Dockerfile 第 83-93 行 创建该用户：useradd --no-log-init --create-home --shell /bin/bash --uid "${NB_UID}" --no-user-group "${NB_USER}"，并把/opt/conda与/home/jovyan的属主设给jovyan:users（GID 100）。相关环境变量在 第 55-65 行 写入镜像：NB_USER、NB_UID、NB_GID、CONDA_DIR=/opt/conda、HOME=/home/jovyan。

理解jovyan对日常操作的三个直接影响：

• 挂载路径：bind mount 的容器侧路径通常写/home/jovyan/work；
• UID 匹配：宿主机用户 UID 与 1000 不一致时会出现权限错误，需按上文 1.2 的NB_UID/NB_GID方案对齐；
• 可重命名：入口脚本 start.sh 在 root 启动时会把jovyan重命名为NB_USER指定的名字，并尽力把家目录内容复制或符号链接过去；test_nb_user_change 验证了把用户改名为nayvoj后uid=1000(nayvoj)且家目录属主正确。

四、如何给容器内用户授予 root（sudo）权限

FAQ 对这一问题的答案是：项目提供了一个"启用 sudo"的官方配方（docs/using/recipes.md 的 "Usingsudowithin a container" 一节）。背景是：镜像默认禁用了NB_USER的密码认证，这是刻意的设计，避免镜像带着一个容易被遗忘的弱默认密码跑到公开主机上。

授予容器内用户免密 sudo的方法，是在 docker 命令行加上--user root与-e GRANT_SUDO=yes：

docker run -it --rm \ --user root \ -e GRANT_SUDO=yes \ quay.io/jupyter/base-notebook

官方明确警告：只在信任该用户、或容器运行在隔离主机上时才应启用 sudo，并建议阅读 Docker 官方文档中关于以 root 运行容器与用户命名空间重映射的安全说明。

源码级实现。GRANT_SUDO的处理逻辑在 start.sh 第 137-140 行：

if [[ "${GRANT_SUDO}" == "1" || "${GRANT_SUDO}" == "yes" ]]; then _log_info "Granting ${NB_USER} passwordless sudo rights!" echo "${NB_USER} ALL=(ALL) NOPASSWD:ALL" >/etc/sudoers.d/added-by-start-script fi

这段代码只有在容器以 root 身份启动（脚本第 49 行的id -u == 0分支）时才会执行；若非 root 启动却设置了GRANT_SUDO，脚本会打印警告container must be started as root to grant sudo permissions!（第 189-191 行）。此外，第 134 行 还会把${CONDA_DIR}/bin前置写入 sudo 的secure_path，保证sudo jupyter调用的是 conda 中的 Jupyter 而非系统版本——这由 test_sudo（断言sudo id输出uid=0(root)）和 test_sudo_path（断言sudo which jupyter指向/opt/conda/bin/jupyter）两个测试用例共同验证。

总结

• 云原生
• 开发工具
• 数据科学