基于 Docker 环境的 JupyterHub 详细部署手册_docker 安装jupyter hub

本文详细介绍基于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-deploymkdir 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/simplepip 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.pyln -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://:18000 用 admin 登录
• 进入 File > Hub Control Panel > Admin > Add Users（输入用户名如 test）

2. 设置用户密码

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

四、访问服务

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

五、维护命令

六、故障排除

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