JupyterHub 开发环境搭建指南

JupyterHub 开发环境搭建指南

jupyterhub Multi-user server for Jupyter notebooks 项目地址: https://gitcode.com/gh_mirrors/ju/jupyterhub

前言

JupyterHub 是一个多用户 Jupyter Notebook 服务器，允许团队共享计算资源。对于开发者而言，搭建本地开发环境是参与项目开发的第一步。本文将详细介绍如何在 macOS 或 Linux 系统上搭建 JupyterHub 的开发环境。

系统要求

操作系统

JupyterHub 仅支持在 macOS 或 Linux 操作系统上运行。Windows 用户可以通过虚拟化技术（如 VirtualBox）安装 Ubuntu Linux 等发行版来进行开发。

Python 环境

JupyterHub 使用 Python 语言开发，最低要求 Python {{python_min}} 版本。推荐使用 Miniforge 来管理 Python 环境，它提供了 conda 包管理器的社区版本。

Node.js 环境

由于 JupyterHub 的默认代理组件 configurable-http-proxy 是用 JavaScript 编写的，因此需要安装 NodeJS {{node_min}} 或更高版本。推荐通过 conda 安装：

conda install nodejs

对于需要管理多个 NodeJS 版本的用户，可以考虑使用 nvm 工具。

Git 版本控制

Git 是 JupyterHub 项目的版本控制工具，开发前需要确保系统已安装 Git。

开发环境搭建步骤

1. 获取源代码

首先需要克隆 JupyterHub 的代码仓库到本地：

git clone https://github.com/jupyterhub/jupyterhub
cd jupyterhub

2. 验证环境

确保 Python 和 npm 已正确安装并可用：

python -V  # 应显示 >= {{python_min}} 的版本
npm -v     # 应显示 >= 5.0 的版本

3. 安装代理组件

安装 configurable-http-proxy：

npm install -g configurable-http-proxy

如果遇到权限问题，可以使用 sudo 或采用本地安装方式：

npm install configurable-http-proxy
export PATH=$PATH:$(pwd)/node_modules/.bin

conda 用户也可以直接通过 conda 安装：

conda install configurable-http-proxy

4. 安装开发依赖

以可编辑模式安装 JupyterHub 及其测试依赖：

python3 -m pip install --editable ".[test]"

5. 启动 JupyterHub

完成安装后，可以启动开发服务器：

jupyterhub

访问 http://localhost:8000 即可看到运行中的 JupyterHub。

测试配置优化

为了简化开发测试，可以使用测试专用的配置：

jupyterhub -f testing/jupyterhub_config.py

这个配置启用了以下特性：

• 使用 DummyAuthenticator（允许任意用户名/密码登录）
• 使用 SimpleLocalProcessSpawner（无需为每个用户创建系统账户）
• 启用命名服务器功能
• 仅监听本地连接
• 预置 admin 用户为管理员
• 禁用静态文件缓存

前端开发

React 组件开发

如果需要修改管理员界面的 React 组件：

cd jsx
npm install
npm run build:watch  # 实时编译变更

SCSS 样式开发

如果需要修改样式文件：

npm install
npm run build:watch  # 实时编译 SCSS

常见问题排查

lessc 未找到错误

如果安装时出现 lessc 相关错误，需要先安装 JavaScript 依赖：

npm install

也可以手动更新前端资源：

python3 setup.py js    # 更新 JavaScript
python3 setup.py css   # 编译 LESS 到 CSS
python3 setup.py jsx   # 构建 React 应用

端口冲突问题

当出现端口绑定失败时，可以使用以下命令检查端口占用：

lsof -P -i TCP:<端口号> -sTCP:LISTEN

如需修改 JupyterHub 的端口配置，可以在配置文件中添加：

c.JupyterHub.hub_port = 9081  # 修改为可用端口

结语

通过以上步骤，您已经成功搭建了 JupyterHub 的开发环境。现在可以开始探索 JupyterHub 的源代码，进行功能开发和问题修复。开发过程中，建议充分利用测试配置简化验证流程，提高开发效率。

jupyterhub Multi-user server for Jupyter notebooks 项目地址: https://gitcode.com/gh_mirrors/ju/jupyterhub