基于 Docker 环境的 JupyterHub 详细部署手册-EW帮帮网

本文详细介绍基于Docker Compose的单机版JupyterHub部署方案，通过容器化技术实现多用户Notebook环境的快速搭建。方案采用官方JupyterHub镜像，配置11个端口映射（18000-18010）支持用户并发，通过数据卷挂载（./data、./home）保障配置与用户数据持久化。核心步骤包括：升级核心组件及安装中文支持/Git集成等扩展；通过配置文件设定管理员权限与用户白名单；结合Web控制台与Linux命令实现用户可视化管理和密码初始化。该方案显著降低多用户协作环境运维成本，支持资源共享与隔离，适用于教学、科研及团队开发场景，实测可稳定承载20+用户并发。

一、环境要求

系统：Linux/Windows/macOS（需安装 Docker）
依赖软件：Docker 20.10+和Docker Compose 2.0+
网络：开放端口 18000-18010（可通过防火墙配置）

二、部署步骤

1. 创建项目目录

mkdir jupyterhub-deploy && cd jupyterhub-deploy
mkdir data home  # 创建数据持久化目录

2. 创建 Docker Compose 文件

创建 docker-compose.yml：

version: '3.5'
services:
  jupyterhub:
    image: jupyterhub/jupyterhub:latest
    restart: always
    ports:
      - "18000:8000"   # JupyterHub 主端口
      - "18001:8001"   # 预留扩展端口
      - "18002:8002"   # 预留扩展端口
      - "18003:8003"   # 预留扩展端口
      - "18004:8004"   # 预留扩展端口
      - "18005:8005"   # 预留扩展端口
      - "18006:8006"   # 预留扩展端口
      - "18007:8007"   # 预留扩展端口
      - "18008:8008"   # 预留扩展端口
      - "18009:8009"   # 预留扩展端口
      - "18010:8010"   # 预留扩展端口
    volumes:
      - ./data:/data    # 配置持久化
      - ./home:/home    # 用户数据持久化

端口说明：

18000：Web 访问端口
18001-18010：预留给 JupyterLab 的 Kernel 连接

3. 启动容器

docker-compose up -d  # 后台启动服务

4. 进入容器终端

docker-compose exec jupyterhub /bin/bash

5. 安装基础工具（在容器内执行）

apt-get update && \
apt-get install -y telnet iputils-ping nano git curl wget

6. 升级核心组件（在容器内执行）

pip install jupyterhub --upgrade -i https://mirrors.aliyun.com/pypi/simple
pip install notebook --upgrade -i https://mirrors.aliyun.com/pypi/simple

7. 安装扩展插件

pip install jupyterlab-language-pack-zh-CN -i https://mirrors.aliyun.com/pypi/simple # 中文语言包
pip install jupyterlab-git -i https://mirrors.aliyun.com/pypi/simple # Git 集成
pip install xeus-python -i https://mirrors.aliyun.com/pypi/simple # 增强Python内核
pip install debugpy -i https://mirrors.aliyun.com/pypi/simple # 调试支持
pip install ipdb -i https://mirrors.aliyun.com/pypi/simple # 交互式调试

8. 生成配置文件

jupyterhub --generate-config -f /data/jupyterhub_config.py
ln -s /data/jupyterhub_config.py .

配置说明：配置文件保存在主机 ./data 目录，容器重启不丢失

9. 修改配置文件

编辑 /data/jupyterhub_config.py：

c.JupyterHub.cookie_secret_file = "/data/jupyterhub_cookie_secret"
c.Authenticator.allowed_users = {"admin"}    # 允许访问的用户
c.Authenticator.admin_users = {"admin"}      # 管理员账号
c.LocalAuthenticator.create_system_users = True

10. 创建管理员账户

adduser admin  # 设置密码（示例：123456），其他信息按回车跳过

11. 重启服务

exit # 退出容器
docker-compose restart # 重启容器

三、用户管理

1. 添加新用户

访问 http://<服务器IP>:18000 用 admin 登录
进入 File > Hub Control Panel > Admin > Add Users（输入用户名如 test）

2. 设置用户密码

docker-compose exec jupyterhub  passwd test  # 为 test 用户设置密码

四、访问服务

管理员登录：http://<服务器IP>:18000 → 用户 admin + 密码
工作区：登录后自动进入 JupyterLab 环境
语言切换：Settings → Language → 简体中文

五、维护命令

功能	命令
启动服务	docker-compose up -d
停止服务	docker-compose down
查看日志	docker-compose logs -f

六、故障排除

端口冲突：修改 docker-compose.yml 中的端口映射
登录失败：检查 jupyterhub_config.py 中的用户配置
插件未生效：在容器内重新执行 pip install 命令
数据持久化：确保主机目录 ./home 和 ./data 有写入权限

基于 Docker 环境的 JupyterHub 详细部署手册