dclong/jupyterhub-pytorch

dclong/docker-jupyterhub-pytorch 镜像文档

1. 镜像概述

dclong/docker-jupyterhub-pytorch是一个集成JupyterHub多用户服务器与PyTorch深度学习框架的Docker镜像。该镜像预配置了完整的深度学习开发环境，允许多个用户通过Jupyter Notebook或Jupyter Lab进行模型开发、训练与实验，无需手动配置复杂的依赖关系，简化了团队协作和教学场景中的环境搭建流程。

2. 核心功能与特性

2.1 多用户协作支持

• 基于JupyterHub实现用户身份认证与权限管理
• 支持用户隔离的工作空间，数据与配置独立存储
• 可通过配置文件自定义用户访问规则与资源限制

2.2 深度学习环境预配置

• 集成PyTorch框架及其核心依赖库（torchvision、torchaudio等）
• 包含常用科学计算库（NumPy、Pandas、Matplotlib等）
• 支持CPU/GPU计算模式，自动适配硬件环境

2.3 灵活的开发工具链

• 内置Jupyter Notebook与Jupyter Lab双界面支持
• 集成代码补全、语法高亮、版本控制插件
• 支持终端访问与第三方库扩展安装

2.4 部署与扩展性

• 支持容器化快速部署，兼容Docker Compose与Kubernetes
• 提供数据持久化方案，支持外部存储卷挂载
• 可通过环境变量自定义服务端口、资源配置与用户参数

3. 使用场景与适用范围

3.1 团队深度学习开发

• 科研团队共享统一开发环境，避免"环境不一致"问题
• 支持多人并行实验，资源集中管理与分配

3.2 教学与培训场景

• 教师为学生提供标准化PyTorch学习环境
• 支持实时代码演示与交互式教学

3.3 科研与实验平台

• 快速搭建可复现的实验环境，便于论文成果验证
• 支持模型训练任务的分布式执行（需额外配置）

4. 使用方法与配置说明

4.1 基础部署（Docker Run）

bash
# 基本启动命令（CPU环境）
docker run -d \
  -p 8000:8000 \
  --name jupyterhub-pytorch \
  -v ./user_data:/srv/jupyterhub/data \
  dclong/docker-jupyterhub-pytorch

# GPU环境启动（需安装nvidia-docker）
docker run -d \
  -p 8000:8000 \
  --name jupyterhub-pytorch \
  --gpus all \
  -v ./user_data:/srv/jupyterhub/data \
  dclong/docker-jupyterhub-pytorch

4.2 Docker Compose配置示例

yaml
version: '3.8'
services:
  jupyterhub:
    image: dclong/docker-jupyterhub-pytorch
    container_name: jupyterhub-pytorch
    restart: always
    ports:
      - "8000:8000"  # JupyterHub服务端口
    volumes:
      - ./config:/srv/jupyterhub/config  # 配置文件目录
      - ./user_data:/srv/jupyterhub/data  # 用户数据持久化
      - ./notebooks:/srv/jupyterhub/shared  # 共享 notebooks 目录
    environment:
      - JUPYTERHUB_ADMIN=teacher,researcher  # 管理员账户（逗号分隔）
      - ENABLE_JUPYTER_LAB=true  # 默认启用Jupyter Lab
      - USER_DEFAULT_SPARK=false  # 禁用默认Spark集成
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1  # 分配1块GPU
              capabilities: [gpu]

4.3 核心环境变量配置

4.4 访问与用户管理

1. 服务启动后，通过浏览器访问 http://<服务器IP>:8000
2. 首次登录使用默认管理员账户（用户名：admin，密码：admin），登录后需立即修改密码
3. 通过管理员界面（Admin选项卡）添加/删除用户、配置资源配额
4. 普通用户使用分配的账户登录后，自动创建独立工作空间

5. 注意事项

• GPU支持：需确保主机已安装NVIDIA驱动与nvidia-docker运行时，启动命令中添加--gpus参数
• 数据安全：生产环境中建议启用HTTPS加密（可通过反向代理配置），并定期备份用户数据卷
• 资源优化：根据用户规模调整容器CPU/内存限制，避免资源竞争导致服务不稳定
• 版本控制：建议指定具体镜像标签（如:latest-py39-cuda117）而非默认latest，确保环境一致性