Prevail Jupyter Docs

Appearance

阶段 3: GitHub 认证集成 ​

代码地址：prevailna/03-jupyterhub-github-auth at prevailna · prevailna/project-1-jupyter

项目说明 ​

基于 Docker 部署 JupyterHub，集成 GitHub OAuth 认证，提高系统安全性和用户管理能力。用户通过 GitHub 登录，管理员可灵活配置允许和管理员用户列表，支持数据持久化、资源隔离和自定义用户镜像。

  • 管理员和允许用户通过环境变量 JUPYTERHUB_ADMIN_USERS、JUPYTERHUB_ALLOWED_USERS 配置（逗号分隔 GitHub 用户名）
  • 生产环境建议使用 docker-compose.prod.yml 并结合 Docker secrets 管理 OAuth 密钥
  • config/jupyterhub_config.py 支持自定义 Notebook 镜像、数据卷、资源限制、网络等

目录结构 ​

bash
./03-jupyterhub-github-auth
├── config
│   └── jupyterhub_config.py    # JupyterHub 配置文件，含 OAuth 认证与用户策略
├── docker-compose.prod.yml     # 生产环境编排（含 secrets）
├── docker-compose.yml          # 开发环境编排
├── Dockerfile.jupyterhub       # JupyterHub 主服务镜像
├── Dockerfile.user             # 用户 Notebook 镜像
├── Makefile
├── README.md
├── requirements.jupyterhub.txt # JupyterHub 服务端依赖
└── requirements.user.txt       # 用户 Notebook 镜像依赖

使用指南 ​

配置 GitHub OAuth 应用 ​

文档：创建 OAuth App

  1. 登录 GitHub Developer Settings 创建 OAuth App
  2. 填写 Application name（应用程序名称），Homepage URL（主页 URL），Authorization callback URL（授权回调 URL）
  3. 获取 Client ID 和 Client Secret

配置环境变量 ​

  • 复制 .env.example 为 .env

  • 填写以下内容（用你的实际值替换）：

    bash
    # 文档：https://docs.github.com/zh/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app
# Github OAuth App 上的 Client ID 和 Client Secret
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

# JupyterHub 回调地址，必须和 c.OAuthenticator.oauth_callback_url 一致
OAUTH_CALLBACK_URL=http://localhost:8000/hub/oauth_callback

# JupyterHub 管理员用户，为以逗号分隔的 Github 用户名
GITHUB_ADMIN_USERS=xxx
# 允许访问的用户，为以逗号分隔的 Github 用户名，如果为空则允许所有用户
GITHUB_WHITELIST_USERS=

生产环境下推荐使用 Docker Secrets 管理敏感信息

  • 使用 docker secret create 创建 secret
  • 使用 docker secret ls 查看 secret
  • 使用 docker secret inspect 查看 secret
  • 使用 docker secret rm 删除 secret
bash
echo "your-client-id" | docker secret create github_client_id -
echo "your-client-secret" | docker secret create github_client_secret -

构建并启动服务 ​

bash
make all
  • 启动后访问：http://localhost:8000
  • 首次登录需使用 GitHub 账号授权

用户与权限管理

  • 只有在 .env 文件 GITHUB_WHITELIST_USERS 中的 GitHub 用户可以登录
  • GITHUB_ADMIN_USERS 中的用户拥有管理员权限

其它命令 ​

功能描述Make 命令Docker 命令说明
一键启动（构建 + 启动）make allmake network && make build && make up创建网络、构建镜像、启动服务
构建镜像make builddocker build -f Dockerfile.user -t jupyter-user-image .
docker compose build		构建用户镜像和 JupyterHub 镜像
启动服务make updocker compose up -d后台启动所有服务
关闭服务make downdocker compose down停止并移除容器
重启服务make restartdocker compose down && docker compose up -d重启所有服务
停止服务make stopdocker compose stop停止容器但不移除
启动已存在的容器make startdocker compose start启动已存在的容器
查看实时日志make logsdocker compose logs -f查看所有服务的日志
进入 JupyterHub 容器环境make bashdocker exec -it jupyterhub-oauth bash进入主服务容器
查看项目容器状态make statusdocker compose ps查看 compose 管理的容器状态
查看用户数据卷make volumesdocker volume ls | grep jupyterhub-user查看所有用户的数据卷

使用 Github Oauth 登录成功后，会自动跳转到 http://localhost:8000/user/<Github 用户名>/lab 页面。

常见问题 ​

  1. OAuth 登录失败：点击 Sign in with GitHub 后，浏览器跳转到 http://localhost:8000/hub/oauth_callback?code=xxx&state=xxx，无法成功登录。

    原因：.env 文件中 GITHUB_CLIENT_ID，GITHUB_CLIENT_SECRET，OAUTH_CALLBACK_URL 没有填写正确。

    解决方法：在 https://github.com/settings/developers 页面选择创建的应用，仔细核对 Client ID 和 Client Secret 和 .env 文件中是否一致。本地开发环境下 OAUTH_CALLBACK_URL 为 http://localhost:8000/hub/oauth_callback。

  2. 用户无法访问：确认用户名已加入 GITHUB_WHITELIST_USERS 白名单。实验开发环境下可以设置为空，这样可以允许所有用户访问。

  3. 端口冲突：确保 8000 端口未被占用（上一个阶段的 JupyterHub 服务可能占用了该端口）

参考资源 ​