Prevail Jupyter Docs

Appearance

阶段 2: JupyterHub 多用户环境 ​

代码地址：prevailna/02-jupyterhub at prevailna · prevailna/project-1-jupyter

项目说明 ​

基于 Docker 和 JupyterHub，搭建支持多用户、资源隔离、数据持久化的在线数据分析环境。

  • 多用户支持 (DockerSpawner)：每个用户独立容器、独立数据卷
    • 每个用户的工作目录自动挂载到独立的 Docker 卷（如 jupyterhub-user-admin, jupyterhub-user-prevailna）
    • JupyterHub 配置和数据库持久化在 jupyterhub-data 卷
  • 支持 NativeAuthenticator：开放注册/登录
  • 基本的系统测试脚本
  • 容器的资源限制配置（CPU/内存）

目录结构 ​

bash
02-jupyterhub
├── config
│   └── jupyterhub_config.py     # JupyterHub 配置文件
├── docker-compose.yml
├── Dockerfile.jupyterhub        # JupyterHub 主服务镜像
├── Dockerfile.user              # 用户容器镜像（含常用数据科学库）
├── Makefile
├── README.md
├── requirements.jupyterhub.txt   # JupyterHub 依赖
├── requirements.user.txt         # 用户容器依赖
└── test
    └── healthcheck.sh            # 系统测试脚本

使用指南 ​

功能描述Make 命令Docker 命令说明
一键启动（构建 + 启动）make allmake network && make build && make up创建网络、构建镜像、启动服务
构建镜像make builddocker build -f Dockerfile.user -t jupyter-user-image .
docker compose build		构建用户镜像和 JupyterHub 镜像
启动服务make updocker compose up -d后台启动所有服务
关闭服务make downdocker compose down停止并移除容器
重启服务make restartdocker compose down && docker compose up -d重启所有服务
查看实时日志make logsdocker compose logs -f查看所有服务的日志
进入 JupyterHub 容器环境make bashdocker exec -it jupyterhub bash进入主服务容器
查看用户数据卷make volumesdocker volume ls | grep jupyterhub-user查看所有用户的数据卷
清理环境make cleandocker compose down -v --remove-orphans停止服务并清理所有卷、网络
简单系统测试make testbash test/healthcheck.sh检测注册、登录页面可用性

常见问题 ​

  1. 启动服务后，注册的用户无法登录，提示 Invalid username or password。

    查看 jupyterhub_config.py 文件中的 c.Authenticator.allow_all 和 c.NativeAuthenticator.open_signup 配置，确保允许所有用户注册和登录。

    python
    c.Authenticator.allow_all = True
c.NativeAuthenticator.open_signup = True

  2. 容器重启后，之前创建的用户不能登录。

    查看数据卷中的用户数据没有被正确挂载。使用以下命令查看数据卷中内容：

    bash
    docker volume ls | grep 02-jupyterhub_jupyterhub-data
docker run --rm -v 02-jupyterhub_jupyterhub-data:/data busybox ls -l /data

    查看用户数据卷中内容：(有没有正确分配给用户)

    bash
    docker volume ls | grep jupyterhub-user
docker run --rm -v jupyterhub-user-<用户名>:/data busybox ls -l /data

  3. 进入 JupyterHub 容器环境后，无法正常启动用户容器。

    这是由于用户容器没有和 JupyterHub 容器在同一个网络中。使用以下命令查看网络信息：

    bash
    docker network ls
docker network inspect jupyterhub-net

    查看 jupyterhub_config.py 文件中的 network_name 配置，确保用户容器和 JupyterHub 容器在同一个网络中。

    python
    network_name = os.environ.get("DOCKER_NETWORK_NAME", "jupyterhub-net")
c.DockerSpawner.network_name = network_name
c.JupyterHub.hub_ip = "jupyterhub"

参考资料 ​