dclong/jupyterhub-cuda

dclong/docker-jupyterhub-cuda 镜像文档

镜像概述

dclong/docker-jupyterhub-cuda 是一个集成 JupyterHub 和 CUDA 的 Docker 镜像，旨在提供开箱即用的多用户 GPU 加速计算环境。该镜像将 JupyterHub（多用户 Jupyter Notebook 服务器）与 CUDA 工具包结合，支持用户通过浏览器访问 Jupyter Notebook，并利用 GPU 资源进行数据科学、机器学习等计算密集型任务，简化多用户共享 GPU 资源的部署与管理流程。

核心功能与特性

1. 多用户协作支持

• 基于 JupyterHub 实现多用户隔离与管理，支持用户认证、权限控制及资源分配
• 支持管理员账户创建与管理，可配置用户访问权限及资源限额

2. GPU 加速计算

• 集成 CUDA 工具包，原生支持 NVIDIA GPU 加速，兼容主流 GPU 架构
• 支持 GPU 资源灵活分配，可根据需求配置单用户或多用户共享 GPU 资源

3. 预装核心依赖

• 内置 Python 环境及常用数据科学库（如 NumPy、Pandas、Matplotlib 等）
• 集成主流机器学习框架（如 TensorFlow、PyTorch），支持直接运行 GPU 加速任务

4. 容器化便捷部署

• 全容器化设计，无需手动配置 JupyterHub、CUDA 及依赖库，简化环境搭建流程
• 支持持久化存储配置，确保用户数据与计算结果不丢失

使用场景与适用范围

1. 数据科学团队

• 适用于中小型数据科学团队共享 GPU 资源，支持多人协作开发、模型训练与数据分析
• 场景示例：团队成员共同参与机器学习项目，共享训练数据与 GPU 算力

2. 教育与培训

• 教育机构或培训机构用于搭建教学环境，为学生提供统一的 GPU 加速 Jupyter 环境
• 场景示例：高校机器学习课程中，学生通过个人账号访问 GPU 环境完成实验作业

3. 研究实验室

• 科研团队用于管理实验室 GPU 服务器，支持多研究者并行使用 GPU 资源开展实验
• 场景示例：深度学习研究中，多个课题组成员共享实验室 GPU 集群进行模型调优

4. 企业 AI 开发

• 企业 AI 部门快速部署多用户开发环境，支持算法工程师并行开发与测试 GPU 加速模型
• 场景示例：企业推荐系统团队使用该环境进行模型训练与线上推理代码调试

使用方法与配置说明

前提条件

• 主机需配备 NVIDIA GPU 并安装对应驱动（驱动版本需与镜像 CUDA 版本兼容）
• 已安装 Docker 及 nvidia-container-toolkit（用于 GPU 容器支持）

基本部署（docker run）

最简启动命令

bash
docker run -d \
  --gpus all \  # 分配所有 GPU 资源（根据需求调整数量，如 --gpus 1）
  -p 8000:8000 \  # 映射 JupyterHub 默认端口（主机端口:容器端口）
  --name jupyterhub-cuda \
  dclong/docker-jupyterhub-cuda

启动后访问

容器启动后，通过浏览器访问 http://<主机IP>:8000，使用默认管理员账户（需参考镜像文档配置初始账号，或通过环境变量预设）登录。

高级配置（环境变量与参数）

核心环境变量

带环境变量的启动示例

bash
docker run -d \
  --gpus 2 \  # 限制使用 2 块 GPU
  -p 8888:8000 \  # 主机端口映射为 8888
  -e JUPYTERHUB_ADMIN="admin,data_scientist" \  # 配置多个管理员
  -e GPU_ALLOC=0.5 \  # 单用户限制使用 50% GPU 资源
  -v /data/jupyterhub:/home \  # 挂载主机目录作为用户数据存储（持久化）
  --name jupyterhub-cuda \
  dclong/docker-jupyterhub-cuda

Docker Compose 配置示例

创建 docker-compose.yml 文件：

yaml
version: '3.8'

services:
  jupyterhub:
    image: dclong/docker-jupyterhub-cuda
    container_name: jupyterhub-cuda
    restart: always
    ports:
      - "8000:8000"  # 主机端口:容器端口
    environment:
      - JUPYTERHUB_ADMIN=admin,researcher
      - NB_USER=jupyter
      - GPU_ALLOC=0.3  # 限制单用户使用 30% GPU 资源
    volumes:
      - ./user_data:/home  # 持久化用户数据
      - ./config:/srv/jupyterhub/config  # 挂载自定义配置文件（如需）
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2  # 使用 2 块 GPU
              capabilities: [gpu]  # 声明 GPU 能力

启动服务：

bash
docker-compose up -d

注意事项

1. GPU 驱动兼容性：需确保主机 GPU 驱动版本与镜像内置 CUDA 版本匹配（参考 NVIDIA CUDA 兼容性文档）
2. 资源限制：生产环境中建议通过 GPU_ALLOC 或 Docker 资源限制配置单用户 GPU 使用量，避免资源独占
3. 持久化存储：务必挂载外部卷（如示例中的 /home 目录），防止容器重启导致用户数据丢失
4. 安全配置：建议通过 JupyterHub 配置文件自定义认证方式（如 LDAP、OAuth），增强多用户环境安全性

参考链接

• 官方仓库：https://github.com/dclong/docker-jupyterhub-cuda
• JupyterHub 文档：JupyterHub Official Docs
• NVIDIA Container Toolkit：Installation Guide