基于 Docker 环境的 JupyterHub 详细部署手册
本文详细介绍基于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:latestrestart: alwaysports:- "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 有写入权限