我最早接触JupyterHub是在实验室里。二十几台Linux服务器二十几个研究生和工程师每个人都在各自电脑上装环境、跑脚本、传数据结果就是环境越来越乱谁也不知道隔壁同事用的Python版本是多少哪台机器的CUDA版本能跑哪个模型。后来一台一台手动装Jupyter勉强能用但只要有人同时访问或者有人误操作重启了服务所有人都得跟着遭殃。JupyterHub这个组件的价值就在这里——它把多用户隔离、统一认证、独立工作空间变成了一套标准机制部署在通用Linux服务器上之后任何一台机器都可以变成一个真正意义上的小型计算平台团队里每个人通过浏览器登录看到的只有自己的notebook目录和运行环境互不干扰资源可管可控。这篇文章是我在通用Linux服务器上手动配置多用户JupyterHub的完整复盘。我这里说的通用指的是不依赖官方Docker镜像、不用Kubernetes就在一台裸金属Linux服务器上用conda、pip、systemd和nginx搭起来。这套方案适合学校实验室、中小团队、企业内部共享开发机也适合想在几台闲置服务器上搭一个公共计算环境的人。如果你正打算给多个人提供Jupyter服务但又不确定从哪一步开始配置比较稳妥这篇文章应该能帮你少走不少弯路。1. 方案选型与整体设计思路1.1 为什么选择手动部署而不是直接用DockerJupyterHub官方文档里最提倡的其实是Docker部署一条docker-compose up就能把hub、数据库、代理、单用户notebook容器全拉起来体验相当顺滑。但我在实际项目里踩过几次Docker方案的坑之后发现它对以下几种场景并不友好一是内网环境拉取镜像费劲官方镜像体积大不说某些内部网络还没有可靠的镜像源二是团队想接入统一的LDAP或AD认证Docker化的JupyterHub要把认证插件和配置文件一起打进去调试一次要反复重建容器三是共享存储的挂载比如所有用户都要能访问一个公共数据集目录或者模型仓库容器里的挂载点和权限控制比裸机要绕得多。所以针对通用Linux服务器这个场景手动安装的收益更高。使用conda创建的专用独立环境来安装JupyterHub一来不污染系统自带的Python二来所有依赖版本都能单独管理升级或者整体迁移都方便。真要出问题了直接在宿主机上就能排查不用进容器。用systemd把服务托底管起来开机自启、崩溃自动拉起、日志集中管理运维体验一点不比容器差。1.2 整体架构从浏览器到Notebook的完整链路先把整条请求链路理清楚。用户通过浏览器访问服务器的某一个端口比如默认的8000或者你自定义的8888端口最先接住请求的是JupyterHub的Hub进程它会负责处理登录页面的渲染、用户身份验证以及单用户服务器实例的调度。JupyterHub内部还有一个代理组件叫configurable-http-proxy它是用Node.js写的负责把路由到顶层Hub的请求按一定规则分发到各个用户专属的Jupyter Notebook服务上。比如用户alice登录成功后代理会把alice的所有请求转发到127.0.0.1:39572这个内部端口上这个端口是hub为alice动态启动的一个Jupyter Notebook实例端口号是随机分配的。整个体系可以拆成三个角色代理节点负责流量分发Hub节点负责认证和调度单用户Notebook节点负责具体的Python操作和代码运行。理解这个链路特别重要因为后面很多配置其实就是在调整这三个环节的参数。例如某个用户启动Notebook失败你得去查单用户日志而不是Hub日志页面能打开、登录请求发出去无响应多半是代理节点挂了或者hub跟代理之间的通信出了问题。手动部署的思路就是一层层把链路理顺再做加固。1.3 我做过的几种可行性方案对比在决定手动部署之前我把常见的几种方案都大致跑了一遍给它们在通用Linux服务器这个前提下的表现打过分。方案部署难度可定制性认证扩展性故障排查难度适合场景Docker Compose全家桶低低中中依赖容器日志快速体验、公网演示Kubernetes部署高高高高链路复杂大型集群、动态扩缩容systemd nginx手动部署中高高低原生日志中小团队、内网服务器、长期运维我的结论很明确通用Linux服务器上最稳妥的就是systemd加nginx手动部署。K8s方案不是说不好而是对大多数只有一两台服务器的团队来说运维成本远大于收益。Docker方案适合临时用不适合作为正式的共享计算平台长期运行。当然如果你以后要扩展到几十台机器再考虑K8s也不迟手动部署的思路在迁移时依然有很强的参考价值。2. 环境准备与核心依赖安装2.1 服务器基础环境检查与系统准备动手之前先把服务器状态摸清楚。我推荐使用Ubuntu 20.04及以上版本或CentOS 7以上的发行版实际上我的部署测试在Ubuntu 22.04 LTS上跑得最顺。拿到一台新服务器后先用下面几条命令确认基本状态cat /etc/os-release uname -m free -h df -h /home python3 --version这里重点看两件事系统架构是不是x86_64内存和磁盘是否充足。JupyterHub本身的资源占用并不高几十个用户在线时Hub和代理进程加起来占用内存大概在300到500MB左右。真正的资源大户是用户启动的Notebook后端进程每个内核进程根据所跑代码的不同占用内存从几百MB到几个GB都有可能。对于团队规模在十人以内的场景建议服务器内存至少16GB起步磁盘尽量给每个用户留出50GB以上的配额。系统里如果之前装过旧版的Python包或者有多个Python版本混在一起我建议先把环境清理干净再动手。我的习惯是安装miniconda把整个Python依赖栈和系统自带Python分开避免后续pip install时出现externally-managed-environment这种鬼问题。Miniconda的安装包大概也就几十MB比Anaconda轻量得多。2.2 安装conda并创建JupyterHub专用环境Miniconda装好之后创建一个名为jupyterhub的独立conda环境所有JupyterHub相关的依赖都放在这个环境里绝不污染系统Pythonwget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh -b -p /opt/miniconda3 /opt/miniconda3/bin/conda create -n jupyterhub python3.11 -y source /opt/miniconda3/bin/activate jupyterhub这一步不仅仅是环境隔离的问题更重要的是保证后面升级JupyterHub时不会影响到其他依赖conda环境运行的服务。我在生产服务器上吃过大意亏直接用系统Python装JupyterHub几个月后系统某次安全补丁升级了OpenSSL把所有JupyterHub服务直接搞崩排查了整整一个下午才定位到原因。用独立的conda环境之后升级系统和Python库的相互影响被完全隔绝了省心太多。环境创建完接下来安装JupyterHub本体、Notebook服务、身份认证插件和代理组件conda activate jupyterhub pip install jupyterhub notebook jupyterlab pip install jupyterhub-systemdspawner npm install -g configurable-http-proxy这里有一点需要特别注意。官方文档给出的最基础安装方式是只装jupyterhub和notebook但在手动部署场景下我强烈建议同时安装jupyterhub-systemdspawner这个插件。它的作用是让Hub通过systemd来启动和监控每一个用户的Notebook服务而不是默认的本地进程模式。这样每个用户的服务就变成了一个独立的systemd unit崩溃了能被自动拉起日志也能通过journalctl独立查看运维体验提升一个档次。2.3 Node.js与系统依赖的坑点记录configurable-http-proxy依赖Node.js环境这个代理组件是JupyterHub的流量入口必须提前装好。在Ubuntu上直接apt安装nodejs可能版本太老尤其是20.04及之前的版本自带Node版本还是v10或v12装上之后代理服务经常会出现TLS握手异常。我的建议是从NodeSource官方源安装Node.js LTS版本curl -fsSL https://deb.nodesource.com/setup_20.x | bash - apt-get install -y nodejs node -v npm -v装完之后先别急着启动JupyterHub先手动验证一下代理组件能不能跑起来configurable-http-proxy --port 8001 --ip 127.0.0.1如果这条命令能正常在前台运行且没有任何报错输出说明Node.js环境和代理组件都正常。如果在执行时提示找不到configurable-http-proxy那多半是npm全局安装目录没有写进PATH检查一下/usr/bin路径下是否生成了可执行文件或者用ln -s把npm全局bin目录软链到/usr/local/bin里。3. 核心配置与用户认证体系搭建3.1 JupyterHub主配置文件编写思路安装好依赖后真正的重头戏是编写JupyterHub的配置文件。JupyterHub的配置是一份Python文件默认路径是/etc/jupyterhub/jupyterhub_config.py运行时通过--config指定路径即可。它的本质就是一个Python脚本里面导入了jupyterhub模块然后为配置项赋值。我先给出一份可以落地的核心配置再逐行解释关键参数的含义# /etc/jupyterhub/jupyterhub_config.py import os # JupyterHub服务监听地址 c.JupyterHub.hub_ip 127.0.0.1 c.JupyterHub.hub_port 8081 # 对外服务地址由nginx反向代理转发 c.JupyterHub.bind_url http://127.0.0.1:8000 # 数据目录 c.JupyterHub.data_dir /srv/jupyterhub c.JupyterHub.cookie_secret_file /srv/jupyterhub/jupyterhub_cookie_secret # 认证方式使用系统PAM用户认证 c.JupyterHub.authenticator_class jupyterhub.auth.PAMAuthenticator c.PAMAuthenticator.admin_groups {hubadmin} c.PAMAuthenticator.open_sessions False # Spawner使用systemd管理单用户服务 c.JupyterHub.spawner_class systemdspawner.SystemdSpawner c.SystemdSpawner.default_url /lab c.SystemdSpawner.mem_limit 4G c.SystemdSpawner.cpu_limit 2 c.SystemdSpawner.user_workingdir /home/{username} c.SystemdSpawner.user_name {username} # 单用户是否使用sudospawner可选项 # c.JupyterHub.spawner_class jupyterhub.spawner.LocalProcessSpawner这里逐个解释。c.JupyterHub.hub_ip和hub_port是hub进程内部通信的监听地址我设置为127.0.0.1只允许本机访问外部请求通过nginx反向代理转发进来安全性更好。bind_url是对外暴露的地址告诉hub它应该用什么URL来生成给用户浏览器访问的链接。c.JupyterHub.data_dir是JupyterHub存放cookie_secret、数据库文件、服务运行时状态的地方建议单独建一个目录不要放在/tmp下。cookie_secret_file这个文件特别重要JupyterHub用它来加密浏览器会话Cookie。首次启动前必须手动创建一个随机密钥文件否则每次重启hub进程用户会话全部失效所有人都会被要求重新登录。很多管理员忽略这个问题测试时还好生产环境一重启全乱了。创建密钥文件的命令mkdir -p /srv/jupyterhub openssl rand -hex 32 /srv/jupyterhub/jupyterhub_cookie_secret chown -R root:root /srv/jupyterhub chmod 700 /srv/jupyterhubc.Authenticator.open_sessions等参数和用户登录后的安全策略相关在后面细说。3.2 用户认证PAM系统用户认证与管理员权限JupyterHub支持多种认证方式比如基于数据库的自定义认证、LDAP认证、OAuth和OIDC认证等。但针对通用Linux服务器最直接、最省事的是PAM认证也就是直接用Linux系统账号来登录JupyterHub。这个方案的优点是显而易见的用户不用额外注册账号Linux系统账号直接在服务器上就能用文件权限的隔离也是天然的Linux文件权限机制。在配置文件中指定c.JupyterHub.authenticator_class jupyterhub.auth.PAMAuthenticator系统里需要创建对应的Linux用户useradd -m -s /bin/bash alice useradd -m -s /bin/bash bob passwd alice passwd bob创建好之后PAM认证插件会自动检查用户输入的用户名密码是否与Linux系统账号匹配。这样做还有一个好处是后面的文件权限完全不需要额外配置每个用户的home目录互不可见用户登录后只能访问自己的目录。管理员权限通过系统用户组来识别。创建一个hubadmin用户组把管理员都加进去groupadd hubadmin usermod -a -G hubadmin alice配置文件中指定c.Authenticator.admin_groups {hubadmin}这样alice登录之后界面上就会多出Admin管理入口可以查看所有在线的用户会话、强制停止指定用户的服务、查看所有用户的服务日志等做运维时非常有用。需要注意的一点是PAM认证默认只允许在服务器有系统账号的用户登录。如果团队里有人不想给他开SSH权限但又要他使用JupyterHub那就不能用这个方案可以在JupyterHub里配置使用NativeAuthenticator在JupyterHub自己的数据库里维护一套账号密码体系。这个后面再讲。3.3 单用户服务管理默认Spawner与SystemdSpawner对比JupyterHub中负责启动每个用户的Notebook服务的组件叫Spawner。默认的Spawner是本地进程模式也就是LocalProcessSpawner。在这种模式下每次用户登录Hub会以该用户的身份fork出一个Python进程跑Jupyter Notebook的服务端。这个模式简单够用但有一个很明显的短板进程的监控能力弱。一旦某个用户的Notebook进程意外崩溃Hub不会主动拉起它而且进程还在运行时产生的僵尸进程很难清理。更麻烦的是不同用户的服务都挂在同一个系统服务下一旦某个用户执行了耗光内存或CPU的代码整个服务器都可能卡死其他用户也跟着遭殃。SystemdSpawner的机制就不一样。它会在用户登录时通过systemd创建一个独立的用户服务单元每个用户的Jupyter Notebook进程有独立的systemd服务名例如jupyter-alice.service。这样带来的好处是进程崩溃后systemd会自动按规则重启每个用系统都有一个独立的cgroup可以精准设置CPU和内存限制日志完全隔离用journalctl -u jupyter-alice查看alice的服务日志比在Hub日志里大海捞针强多了可以配合systemd的resource control设置每个用户最多能占多少CPU、多少内存配置SystemdSpawner的两个核心参数是mem_limit和cpu_limit单位分别是字节和CPU核心数。比如我给普通用户配置4GB内存上限和2核CPU上限这样就防止了一个用户在notebook里跑个死循环导致全服务器瘫痪。需要注意的是使用SystemdSpawner时服务器上必须运行systemd作为系统初始化器。Ubuntu 20.04及之后的版本没问题如果用的是某些容器环境或者WSL没有完整的systemd就不要用这个Spawner退回LocalProcessSpawner即可。3.4 用户启动目录与权限隔离用户登录后JupyterHub会为每个用户启动一个Notebook服务服务的工作目录默认是该用户的home目录。这个逻辑在SystemdSpawner中通过user_workingdir和user_name来指定c.SystemdSpawner.user_workingdir /home/{username} c.SystemdSpawner.user_name {username}花括号里的{username}是一个占位符JupyterHub在启动不同用户的服务时会自动替换成实际的用户名。这样做的好处是每个用户的默认工作目录就是他们的home目录不管在哪儿打开Jupyter看到的都是自己那摊文件。如果要开放一个公共目录给所有用户只读访问比如一个数据集或者共享软件包目录可以在系统层面把目录权限设置为755并放在如/srv/shared_data这样的地方所有用户根据具体需求决定是否挂载到自己的工作区。不要轻易改动/home下用户的权限结构否则会引入安全隐患。用户在Notebook里能执行什么权限的系统命令由系统账号本身的权限决定。如果alice在系统里只是一个普通用户没有sudo权限那她开的Notebook就没办法执行sudo。3.5 增加管理员无法后台查看用户文件这里有一个常见误区要提醒一下。很多人以为管理员能管理用户的服务就代表管理员能看到用户notebook里的代码和数据。其实这完全是两码事。JupyterHub的管理员功能界面提供的是对服务的控制——停掉某个用户的服务、查看服务的运行状态、终止用户的kernel这些是基于systemd服务管理的和管理员直接ssh进服务器看用户的home目录是两回事。在系统层面root用户理论上始终拥有所有文件权限JupyterHub只是在这个基础上提供了一个Web管理界面。如果你的团队有代码保密的需求应该在更高的运维层面用磁盘加密、系统审计等手段来保证而不能指望JupyterHub来解决这个问题。所以我还想强调一下权限问题。JupyterHub从机制上设计了用户文件的隔离每个用户只能看到自己的notebook、自己的kernel、自己的进程。但服务器本身还是由管理员掌握的。对于管理员来说不要因为自己有系统的全部权限就随意查看用户的文件这是基本的安全伦理也是合作团队保持信任的底线。4. 完整实操过程与关键节点记录4.1 每步必做继承系统环境初始化配置实际上在JupyterHub的配置过程中最容易出问题的不是配置文件本身而是用户环境不对。举个例子。假设管理员在conda的jupyterhub环境里装了jupyterhub和notebook用户alice登录后SystemdSpawner会以alice用户身份去启动Notebook服务。这时它启动用的Python解释器是哪个如果alice自己有一个单独的conda环境那没问题。如果alice的home目录下没有独立的conda那么系统就会尝试用系统Python来跑notebook。如果系统自带的Python里根本没有notebook包启动就会直接失败。要解决这个问题有几个思路。思路一是给所有用户都装好Python和notebook包。这个在实际操作中不现实因为每来一个新用户都要装一遍环境。思路二是在Notebook服务启动时显式指定需要使用的Python解释器路径。在JupyterHub配置中可以用c.SystemdSpawner.environment来设置PATHimport os c.SystemdSpawner.environment { PATH: /opt/miniconda3/envs/jupyterhub/bin:/opt/miniconda3/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin, JUPYTER_RUNTIME_DIR: /tmp/{username}-runtime, }这样用户启动的Notebook进程就能找到conda环境里的notebook包和Jupyter命令了。思路三是我最推荐的以系统普通用户身份运行Notebook但要先确保每个用户的home目录里有一个独立的conda环境或者至少能访问一个公共的conda环境。比较标准做法是在服务器上建立一个公共的conda环境比如叫base_env所有用户都通过它来运行Python代码在Jupyter里给用户添加一个指向该环境Python解释器的Kernel。这样做的优点是环境统一依赖一致也减少了每个用户自己管理环境的负担。具体做法是在JupyterHub所在的服务器上# 建立公共conda环境 /opt/miniconda3/bin/conda create -n base_env python3.11 ipykernel jupyter -y /opt/miniconda3/bin/conda run -n base_env python -m ipykernel install --prefix/opt/miniconda3/envs/jupyterhub --name base_env --display-name Base Python 3.11然后在JupyterHub配置文件中把这个公共环境的Python路径作为所有用户默认的Kernel路径c.Spawner.kernel_spec base_env这样用户登录后打开新的NotebookKernel会自动选择Base Python 3.11用同一个统一的基础环境。4.2 用户Notebook服务的启动流程与日志观察JupyterHub配置完成之后先不要急着跑systemd服务先在后台手动启动一次hub进程确认配置文件没有语法错误conda activate jupyterhub jupyterhub -f /etc/jupyterhub/jupyterhub_config.py第一次启动时能看到几个关键日志一是Hub进程创建数据库生成初始密码hashing二是启动了configurable-http-proxy代理进程绑定到8000端口三是提示Hub已就绪等待请求。日志正常后用浏览器访问http://服务器IP:8000就能看到登录页面了。登录流程走一遍输入alice的用户名密码点击登录JupyterHub内部会依次做几件事PAM认证用户名密码确认合法后分配一个随机端口通过SystemdSpawner启动jupyter-alice服务该服务内部会启动一个Jupyter Notebook进程代理把该用户的请求转发到这个内部端口。整个过程通常需要3到8秒如果超过10秒还没看到Notebook页面基本就是Spawner环境配置有问题。此时建议立刻打开另一个SSH窗口观察alice的服务日志journalctl -u jupyter-alice -f这个日志会真实反映出Notebook服务启动过程中的细节比如Python解释器路径、缺哪个包、权限对不对、端口是否能监听。绝大多数启动失败的问题看这里就能定位。4.3 systemd服务文件创建手动启动验证没问题后把JupyterHub以systemd服务的方式托管起来。创建一个service文件sudo cat /etc/systemd/system/jupyterhub.service EOF [Unit] DescriptionJupyterHub Afternetwork.target [Service] Typesimple Userroot EnvironmentPATH/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/opt/miniconda3/bin:/opt/miniconda3/envs/jupyterhub/bin ExecStart/opt/miniconda3/envs/jupyterhub/bin/jupyterhub -f /etc/jupyterhub/jupyterhub_config.py WorkingDirectory/srv/jupyterhub Restarton-failure RestartSec5 [Install] WantedBymulti-user.target EOF systemctl daemon-reload systemctl enable jupyterhub systemctl start jupyterhub这里注意JupyterHub进程要以root身份运行才能调用系统PAM认证和创建用户服务。这一点可能让部分管理员有顾虑但这是官方文档推荐的架构。实际安全性是由各个用户进程的Spawner机制来保证的Hub进程虽然是root但每个用户的Notebook进程会通过systemd来降权到对应用户名下运行用户之间是隔离的。启动后检查服务状态systemctl status jupyterhub ss -tlnp | grep 8000这时候如果能看到java-less的LISTEN状态在0.0.0.0:8000说明服务已经正常对外监听。4.4 反向代理与HTTPS加密直接暴露8000端口给用户访问也能用但存在两个问题一是端口不标准用户容易记错二是数据明文传输Notebook里的代码、密码、模型结果完全赤裸裸暴露在网络中在内网还好一旦跨公网访问就非常危险。所以强烈建议在JupyterHub前面用nginx做反向代理并配置HTTPS。Nginx的配置片段如下server { listen 443 ssl http2; server_name jupyter.example.com; ssl_certificate /etc/letsencrypt/live/jupyter.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/jupyter.example.com/privkey.pem; # 长连接设置 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket支持JupyterLab终端功能依赖 location / { proxy_pass http://127.0.0.1:8000; } }在nginx配置中最重要的就是WebSocket代理部分。JupyterLab的终端和某些交互组件依赖WebSocket实时双向通信如果Upgrade或Connection头没有正确转发用户在界面上打开终端时会出现一直在正在连接但始终连不上的情况。配置处理好之后重新加载nginx配置nginx -t systemctl reload nginx同时修改JupyterHub配置文件中的bind_url域名c.JupyterHub.bind_url https://jupyter.example.com/jupyter然后重启JupyterHub服务。用户直接用浏览器访问https://jupyter.example.com就能安全地使用所有功能了。4.5 防火墙与安全组配置建议很多管理员在配置完服务后发现从外部浏览器无法访问第一反应是检查JupyterHub配置却忘了看防火墙。真实排查中我发现十次里至少有三次以上的服务没跑起来其实是防火墙或安全组没放行端口。在Ubuntu上用ufw的话把对外端口放行ufw allow 80/tcp ufw allow 443/tcp ufw allow 8000/tcp # 如果用8000直接对外访问 ufw status在云服务器上还要到控制台的安全组规则中检查入方向是否放行对应端口。这里提醒一下如果用了nginx做代理其实8000端口完全没必要对外开放只让nginx内部访问就够防火墙只需要放行80和443。5. 性能调优与资源隔离实战5.1 单用户资源限制的精细化管理多用户场景下最大的风险是谁也不知道用户A会在notebook里跑什么代码。几年前我在实验室搭了一台共享服务器给组里十几个学生用最初没设任何资源限制有一天某个学生跑了一个大数据处理任务内存瞬间吃满服务器直接不可用所有人的Session全断正在训练的模型全丢。后来我把SystemdSpawner的资源限制全部打开才算是把这种事故概率降到了可接受范围。除了前面说的mem_limit和cpu_limit还有一些细节值得关注。c.SystemdSpawner.mem_limit 4G c.SystemdSpawner.cpu_limit 2 c.SystemdSpawner.working_dir /home/{username} c.SystemdSpawner.user_workingdir /home/{username} c.SystemdSpawner.isolate_network True c.SystemdSpawner.slice jupyterhubc.SystemdSpawner.isolate_network设为True后每个用户的Notebook服务会有独立的网络命名空间用户之间通过网络层面的隔离能防止某些基于网络的干扰行为。c.SystemdSpawner.slice参数把用户服务归属到名为jupyterhub的systemd切片下配合systemd的资源统计一眼就能看出哪个用户当前的CPU和内存占用情况systemd-cgtop你会发现加了资源限制之后单用户跑满内存时最多只是自己的服务崩溃其他用户完全不受影响。这就是做平台和做玩具的本质区别。5.2 Spawner超时与空转回收策略在团队协作场景里很多用户登录后长时间没有操作但Notebook服务一直挂着白白占用系统资源。JupyterHub里可以对这类空闲服务设置超时回收。# 日志空闲超过30分钟就自动关闭 c.JupyterHub.shutdown_on_logout True c.Spawner.http_timeout 60 c.Spawner.start_timeout 60 c.Spawner.poll_interval 30更深度的做法是设置idle culler这是JupyterHub官方团队提供的一个后台脚本定期扫描所有用户服务的活跃状态超过阈值就调用API关闭它们。把idle-culler注册成systemd timer任务就能实现定时回收pip install jupyterhub-idle-culler然后在systemd里建立一个定时任务每小时检查一次超过2小时没操作的notebook就会自动关闭。这样配置之后服务器资源利用效率明显提升几个人在线时各开各的服务没人用的时候资源自动释放。不过也要想清楚如果团队里有跑长时间训练的情况要适当延长超时时间避免训练任务被误杀。5.3 与GPU配置相关的问题记录如果要让所有用户都能使用GPU跑深度学习训练这步需要额外处理。JupyterHub本身和GPU没有直接关系真正决定能不能用GPU的是用户Notebook进程能看到哪些设备以及CUDA环境是否正确配置。在一台有NVIDIA GPU的服务器上首先要确保驱动和CUDA Toolkit已经装好用nvidia-smi确认GPU状态正常。之后在SystemdSpawner里把GPU设备映射进去c.SystemdSpawner.extra_create_kwargs { device_policy: closed, allowed_devices: [/dev/nvidia0, /dev/nvidiactl, /dev/nvidia-uvm, /dev/nvidia-uvm-tools] }不同驱动版本对应的设备节点名可能不完全一样建议先用ls /dev/nvidia*查一下实际节点。更好的办法是给用户统一准备好conda环境并安装好pytorch或tensorflow的GPU版本保证nvidia-smi命令在notebook里能用。GPU配置中最容易踩的坑是用户在自己的环境里pip install torch的时候装的是CPU版因为pip默认安装的torch就是CPU版要用GPU就得从相应的index安装。所以管理员最好在公共环境里把GPU版框架提前装好避免用户自己装错版本后一脸懵。6. 常见问题与排查技巧实录6.1 登录一直在转圈或直接502错误这是多用户JupyterHub里最经典的问题。情况通常是用户能打开登录页输入账号密码点登录之后浏览器一直转圈最后页面报502 Bad Gateway或者Proxy Error。排查思路是先看Hub日志journalctl -u jupyterhub -n 100 --no-pager如果日志里出现类似Proxy at http://127.0.0.1:8001 failed to connect to server ...的错误说明代理到用户Notebook服务的转发链路出问题了。此时需要用journalctl -u jupyter-alice看看用户服务启动到哪一步如果用户服务没起来检查用户目录权限、系统PATH以及Spawner配置。如果用户服务起来了但还是502那大概率是代理进程或者Hub进程出现的网络配置不一致。最直接的方法是重启一次JupyterHub服务和代理进程systemctl restart jupyterhub注意这会让所有人的会话中断重新登录不是万不得已不要在大白天人多的时候执行。如果是深夜或者用户都离线了重启一次往往能解决很多沉淀状态导致的问题。不过根因还是要去查不然过两天又会出现同样的问题。6.2 用户服务启动失败Permission denied或Exec format error用户登录时Hub显示User alices server failed to start去查journalctl -u jupyter-alice常见报错包括Permission denied和Exec format error。Permission denied的大概率原因是用户的home目录权限不对。Linux对home目录的权限要求很严格如果home目录或其他目录对当前用户不可写或者执行者没有执行权限notebook启动就会失败。用ls -ld /home/alice查看一下当前权限正常应该是drwxr-x---之类的。修复方式chown -R alice:alice /home/alice chmod 700 /home/aliceExec format error出现得比较罕见一种情况是用户home目录挂载在某个网络文件系统上而该文件系统的noexec选项禁止执行二进制文件。这时候notebook二进制虽然存在却执行不了。解决办法是检查挂载参数或者把jupyter的runtime目录和kernel执行目录改到本地磁盘。还有一种情况用户环境里用了32位Python但服务器是64位内核也会报Exec format error。这种基本只能重装环境解决。6.3 多个用户同时在线时内存经常告警资源告警是多人同时使用服务器必然遇到的。配置了mem_limit后单个用户最多占用4G内存但如果有五个用户同时各占3G服务器总内存迟早也要爆炸。这里需要规划一下总内存和每个用户的配额。比如服务器总内存32G系统自身占用和JupyterHub环境预留6G左右剩下26G分给用户。如果平时同时在线人数最多8人左右单用户配额设置3G是相对稳妥的。太少了用户体验差一个稍微大点的数据集分析都跑不了太多了其他用户无法使用失去了共享的意义。更好的办法是给用户单独集中使用大的数据目录提醒团队成员禁抢公共数据目录里跑重计算重要计算尽量分类错时跑。如果在服务器上部署了Prometheus和Grafana可以监控每个用户的内存使用趋势这样对调优容量和配额设计会更有把握。6.4 用户忘记密码怎么办PAM认证模式下用户密码就是Linux系统账号密码忘记密码时管理员在服务器端执行sudo passwd alice然后告诉alice新密码就可以重新登录了。这里有一个隐藏细节PAMAuthenticator默认情况下允许用户在JupyterHub页面上找一封重置密码邮件吗其实不行因为没有配置邮件系统。所以管理员必须能登录服务器才能帮用户重置密码。如果你的团队希望用户能自助修改或重置密码建议接入NativeAuthenticator在JupyterHub界面里提供注册和密码修改功能。但那样做需要引入用户自注册对某些安全要求严格的团队可能不可接受按需采用即可。6.5 常见问题速查表问题现象可能原因排查步骤解决办法登录后一直转圈Hub与代理通信异常journalctl -u jupyterhub重启JupyterHub服务或检查代理进程502 Bad Gateway单用户Notebook服务未启动journalctl -u jupyter-用户名修复用户目录权限或Spawner配置用户服务启动失败Permission denied用户home目录权限错误ls -ld /home/用户名chown/chmod修复用户目录权限访问页面打开很慢HTTPS证书配置或DNS解析缓慢curl -v https://域名检查nginx代理和证书有效期用户kernel一直显示正在连接WebSocket转发未配置检查nginx的Upgrade/Connection头修改nginx代理配置并reload内存告警单用户配额过大或用户代码有消耗问题systemd-cgtop降低mem_limit或优化用户代码所有用户都无法访问Hub进程挂掉或系统资源耗尽systemctl status jupyterhub启动服务或排查OOM杀死记录用户环境里没有基础包用户kernel指向了错误的Python检查kernel列表配置统一的公共conda kernel路径7. 进阶扩展与安全加固指南7.1 多用户JupyterHub的备份与恢复策略在一套JupyterHub体系稳定运行一段时候后备份问题会逐渐暴露。用户自己的代码存各自的home目录这点通常不需要整体备份真正需要重点管理的是JupyterHub的元数据数据库文件、Cookie密钥、配置文件和用户环境清单。准备一个备份脚本定期压缩打包#!/bin/bash BACKUP_DIR/home/admin/backups DATE$(date %Y%m%d-%H%M%S) mkdir -p $BACKUP_DIR # 备份hub数据目录 tar -czf $BACKUP_DIR/jupyterhub-data-$DATE.tar.gz /srv/jupyterhub # 备份hub配置 tar -czf $BACKUP_DIR/jupyterhub-config-$DATE.tar.gz /etc/jupyterhub # 备份用户环境清单 conda activate jupyterhub conda list --explicit $BACKUP_DIR/jupyterhub-env-$DATE.txt把脚本挂到crontab里设置每天凌晨执行。恢复时只需要先把系统装好JupyterHub依赖然后把备份的/srv/jupyterhub和/etc/jupyterhub解压覆盖重启服务即可。Cookie密钥一旦丢失所有用户的会话会全部失效所以强烈建议把cookie_secret单独放一个文件合并到备份范围内。7.2 通过LDAP或企业账号系统接入认证很多企业内部有统一的账号系统比如OpenLDAP或Active Directory。JupyterHub也能接入这类系统让用户直接用办公账号登录服务器省去维护Linux系统账号的麻烦。原理是使用LDAPAuthenticator或OAuthenticator插件替代PAMAuthenticator。以LDAP为例pip install jupyterhub-ldapauthenticator配置也很容易c.JupyterHub.authenticator_class ldapauthenticator.LDAPAuthenticator c.LDAPAuthenticator.server_address ldap.example.com c.LDAPAuthenticator.bind_dn_template uid{username},oupeople,dcexample,dccom c.LDAPAuthenticator.user_search_base oupeople,dcexample,dccom c.LDAPAuthenticator.user_attribute uid c.LDAPAuthenticator.lookup_dn True c.LDAPAuthenticator.lookup_dn_search_filter ((objectClassposixAccount)(uid{username})) c.LDAPAuthenticator.lookup_dn_search_user cnadmin,dcexample,dccom c.LDAPAuthenticator.lookup_dn_search_password admin_password接入LDAP之后Linux系统账号可以仍然存在因为Spawner还需要用它们来启动进程也可以配置成动态创建用户目录。实际上比较稳妥的方案是LDAP用户登录后通过SystemdSpawner以某个固定用户身份运行服务然后通过环境变量把用户身份传给Notebook里的业务逻辑。这样的配置会稍微复杂一些适合有专门运维团队的场景。7.3 结合JupyterLab的扩展插件与主题定制JupyterHub和JupyterLab原生支持扩展插件用户可以在自己的界面里安装JupyterLab插件来增强体验。管理员如果希望统一团队的界面风格和功能也可以在config里为所有用户指定插件列表conda activate jupyterhub pip install jupyterlab-git jupyterlab-spellchecker jupyterlab-toc对于安装的插件如果想对全局用户生效需要放在JupyterLab的全局扩展目录中。由于JupyterLab的扩展机制和Python包类似安装后会同时提供一个前端资源和后端服务需要手动执行jupyter lab build在执行构建时系统会用Node.js和webpack把所有前端的JS资源打包耗时通常在三到十分钟不等期间JupyterLab服务需要暂停使用所以尽量选在对用户影响小的时候执行。构建成功后再访问JupyterLab所有用户都能看到新装的插件功能了。7.4 多服务器节点扩展的可能性最后聊一个常见困惑手动部署的JupyterHub能不能横向扩展答案是完全可以但要拆开来看。JupyterHub的Hub进程和代理本身就是无状态的可以横向扩展。单用户Notebook服务的本质是——每个用户都是独立的进程理论上可以分布在不同服务器上。常见做法是配合DockerSpawner或KubeSpawnerKubernetes来自动分配用户到不同节点。但如果保持手动部署方案最简单可行的横向扩展是在每台服务器上各装一个独立的JupyterHub实例通过统一的入口域名做负载均衡或分流。比如一台机器分配给A组一台机器分配给B组各自有自己的Hub和用户目录互不干扰。这种方案虽然做不到真正的一个Hub统管所有机器但实现简单、稳定性高对于两到三台服务器的中小团队来说运维成本低得不是一星半点。真要到了一台Hub管几十台机器的规模那时候再迁移到Kubernetes也不算亏因为底层的镜像构建、环境管理、用户体系在手动部署阶段沉淀下来的经验完全能用得上。写在最后一点真实体会这篇文章从决定写到最后写完前后跨度将近一个月中间一直在用自己搭的这套JupyterHub环境做各种验证和记录。我个人觉得手动部署JupyterHub最大的价值不在于省了容器那点开销而在于它逼着你把整个服务链路从下到上摸了一遍。你会知道代理为什么转发超时知道用户服务为什么会启动失败知道某个权限配置影响的是哪一层而不是出了问题只能把容器删了重来。这种掌控感在真正需要长期运维和团队协作的时候会很不一样。最后再分享一个小技巧。如果你也是第一次在生产服务器上部署强烈建议先在本地虚拟机里完整走一遍流程包括创建用户、登录测试、并发访问、模拟用户跑一个大型计算、查看日志以及重启恢复。我用这套方案在测试环境跑了完整流程之后部署到正式服务器时半小时就完成了但前期测试踩掉的那些坑每一个都在正式环境里准确地兑现出来了。别嫌麻烦这一步能省下后面大量的排障时间。如果你在配置过程中遇到什么奇怪的问题欢迎留言描述你看到的日志和报错我尽量帮着定位。毕竟多用户JupyterHub这个事儿最大的坑永远在你看不到的细节里。
多用户JupyterHub手动部署指南：Linux服务器从零搭建与调优
我最早接触JupyterHub是在实验室里。二十几台Linux服务器二十几个研究生和工程师每个人都在各自电脑上装环境、跑脚本、传数据结果就是环境越来越乱谁也不知道隔壁同事用的Python版本是多少哪台机器的CUDA版本能跑哪个模型。后来一台一台手动装Jupyter勉强能用但只要有人同时访问或者有人误操作重启了服务所有人都得跟着遭殃。JupyterHub这个组件的价值就在这里——它把多用户隔离、统一认证、独立工作空间变成了一套标准机制部署在通用Linux服务器上之后任何一台机器都可以变成一个真正意义上的小型计算平台团队里每个人通过浏览器登录看到的只有自己的notebook目录和运行环境互不干扰资源可管可控。这篇文章是我在通用Linux服务器上手动配置多用户JupyterHub的完整复盘。我这里说的通用指的是不依赖官方Docker镜像、不用Kubernetes就在一台裸金属Linux服务器上用conda、pip、systemd和nginx搭起来。这套方案适合学校实验室、中小团队、企业内部共享开发机也适合想在几台闲置服务器上搭一个公共计算环境的人。如果你正打算给多个人提供Jupyter服务但又不确定从哪一步开始配置比较稳妥这篇文章应该能帮你少走不少弯路。1. 方案选型与整体设计思路1.1 为什么选择手动部署而不是直接用DockerJupyterHub官方文档里最提倡的其实是Docker部署一条docker-compose up就能把hub、数据库、代理、单用户notebook容器全拉起来体验相当顺滑。但我在实际项目里踩过几次Docker方案的坑之后发现它对以下几种场景并不友好一是内网环境拉取镜像费劲官方镜像体积大不说某些内部网络还没有可靠的镜像源二是团队想接入统一的LDAP或AD认证Docker化的JupyterHub要把认证插件和配置文件一起打进去调试一次要反复重建容器三是共享存储的挂载比如所有用户都要能访问一个公共数据集目录或者模型仓库容器里的挂载点和权限控制比裸机要绕得多。所以针对通用Linux服务器这个场景手动安装的收益更高。使用conda创建的专用独立环境来安装JupyterHub一来不污染系统自带的Python二来所有依赖版本都能单独管理升级或者整体迁移都方便。真要出问题了直接在宿主机上就能排查不用进容器。用systemd把服务托底管起来开机自启、崩溃自动拉起、日志集中管理运维体验一点不比容器差。1.2 整体架构从浏览器到Notebook的完整链路先把整条请求链路理清楚。用户通过浏览器访问服务器的某一个端口比如默认的8000或者你自定义的8888端口最先接住请求的是JupyterHub的Hub进程它会负责处理登录页面的渲染、用户身份验证以及单用户服务器实例的调度。JupyterHub内部还有一个代理组件叫configurable-http-proxy它是用Node.js写的负责把路由到顶层Hub的请求按一定规则分发到各个用户专属的Jupyter Notebook服务上。比如用户alice登录成功后代理会把alice的所有请求转发到127.0.0.1:39572这个内部端口上这个端口是hub为alice动态启动的一个Jupyter Notebook实例端口号是随机分配的。整个体系可以拆成三个角色代理节点负责流量分发Hub节点负责认证和调度单用户Notebook节点负责具体的Python操作和代码运行。理解这个链路特别重要因为后面很多配置其实就是在调整这三个环节的参数。例如某个用户启动Notebook失败你得去查单用户日志而不是Hub日志页面能打开、登录请求发出去无响应多半是代理节点挂了或者hub跟代理之间的通信出了问题。手动部署的思路就是一层层把链路理顺再做加固。1.3 我做过的几种可行性方案对比在决定手动部署之前我把常见的几种方案都大致跑了一遍给它们在通用Linux服务器这个前提下的表现打过分。方案部署难度可定制性认证扩展性故障排查难度适合场景Docker Compose全家桶低低中中依赖容器日志快速体验、公网演示Kubernetes部署高高高高链路复杂大型集群、动态扩缩容systemd nginx手动部署中高高低原生日志中小团队、内网服务器、长期运维我的结论很明确通用Linux服务器上最稳妥的就是systemd加nginx手动部署。K8s方案不是说不好而是对大多数只有一两台服务器的团队来说运维成本远大于收益。Docker方案适合临时用不适合作为正式的共享计算平台长期运行。当然如果你以后要扩展到几十台机器再考虑K8s也不迟手动部署的思路在迁移时依然有很强的参考价值。2. 环境准备与核心依赖安装2.1 服务器基础环境检查与系统准备动手之前先把服务器状态摸清楚。我推荐使用Ubuntu 20.04及以上版本或CentOS 7以上的发行版实际上我的部署测试在Ubuntu 22.04 LTS上跑得最顺。拿到一台新服务器后先用下面几条命令确认基本状态cat /etc/os-release uname -m free -h df -h /home python3 --version这里重点看两件事系统架构是不是x86_64内存和磁盘是否充足。JupyterHub本身的资源占用并不高几十个用户在线时Hub和代理进程加起来占用内存大概在300到500MB左右。真正的资源大户是用户启动的Notebook后端进程每个内核进程根据所跑代码的不同占用内存从几百MB到几个GB都有可能。对于团队规模在十人以内的场景建议服务器内存至少16GB起步磁盘尽量给每个用户留出50GB以上的配额。系统里如果之前装过旧版的Python包或者有多个Python版本混在一起我建议先把环境清理干净再动手。我的习惯是安装miniconda把整个Python依赖栈和系统自带Python分开避免后续pip install时出现externally-managed-environment这种鬼问题。Miniconda的安装包大概也就几十MB比Anaconda轻量得多。2.2 安装conda并创建JupyterHub专用环境Miniconda装好之后创建一个名为jupyterhub的独立conda环境所有JupyterHub相关的依赖都放在这个环境里绝不污染系统Pythonwget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh -b -p /opt/miniconda3 /opt/miniconda3/bin/conda create -n jupyterhub python3.11 -y source /opt/miniconda3/bin/activate jupyterhub这一步不仅仅是环境隔离的问题更重要的是保证后面升级JupyterHub时不会影响到其他依赖conda环境运行的服务。我在生产服务器上吃过大意亏直接用系统Python装JupyterHub几个月后系统某次安全补丁升级了OpenSSL把所有JupyterHub服务直接搞崩排查了整整一个下午才定位到原因。用独立的conda环境之后升级系统和Python库的相互影响被完全隔绝了省心太多。环境创建完接下来安装JupyterHub本体、Notebook服务、身份认证插件和代理组件conda activate jupyterhub pip install jupyterhub notebook jupyterlab pip install jupyterhub-systemdspawner npm install -g configurable-http-proxy这里有一点需要特别注意。官方文档给出的最基础安装方式是只装jupyterhub和notebook但在手动部署场景下我强烈建议同时安装jupyterhub-systemdspawner这个插件。它的作用是让Hub通过systemd来启动和监控每一个用户的Notebook服务而不是默认的本地进程模式。这样每个用户的服务就变成了一个独立的systemd unit崩溃了能被自动拉起日志也能通过journalctl独立查看运维体验提升一个档次。2.3 Node.js与系统依赖的坑点记录configurable-http-proxy依赖Node.js环境这个代理组件是JupyterHub的流量入口必须提前装好。在Ubuntu上直接apt安装nodejs可能版本太老尤其是20.04及之前的版本自带Node版本还是v10或v12装上之后代理服务经常会出现TLS握手异常。我的建议是从NodeSource官方源安装Node.js LTS版本curl -fsSL https://deb.nodesource.com/setup_20.x | bash - apt-get install -y nodejs node -v npm -v装完之后先别急着启动JupyterHub先手动验证一下代理组件能不能跑起来configurable-http-proxy --port 8001 --ip 127.0.0.1如果这条命令能正常在前台运行且没有任何报错输出说明Node.js环境和代理组件都正常。如果在执行时提示找不到configurable-http-proxy那多半是npm全局安装目录没有写进PATH检查一下/usr/bin路径下是否生成了可执行文件或者用ln -s把npm全局bin目录软链到/usr/local/bin里。3. 核心配置与用户认证体系搭建3.1 JupyterHub主配置文件编写思路安装好依赖后真正的重头戏是编写JupyterHub的配置文件。JupyterHub的配置是一份Python文件默认路径是/etc/jupyterhub/jupyterhub_config.py运行时通过--config指定路径即可。它的本质就是一个Python脚本里面导入了jupyterhub模块然后为配置项赋值。我先给出一份可以落地的核心配置再逐行解释关键参数的含义# /etc/jupyterhub/jupyterhub_config.py import os # JupyterHub服务监听地址 c.JupyterHub.hub_ip 127.0.0.1 c.JupyterHub.hub_port 8081 # 对外服务地址由nginx反向代理转发 c.JupyterHub.bind_url http://127.0.0.1:8000 # 数据目录 c.JupyterHub.data_dir /srv/jupyterhub c.JupyterHub.cookie_secret_file /srv/jupyterhub/jupyterhub_cookie_secret # 认证方式使用系统PAM用户认证 c.JupyterHub.authenticator_class jupyterhub.auth.PAMAuthenticator c.PAMAuthenticator.admin_groups {hubadmin} c.PAMAuthenticator.open_sessions False # Spawner使用systemd管理单用户服务 c.JupyterHub.spawner_class systemdspawner.SystemdSpawner c.SystemdSpawner.default_url /lab c.SystemdSpawner.mem_limit 4G c.SystemdSpawner.cpu_limit 2 c.SystemdSpawner.user_workingdir /home/{username} c.SystemdSpawner.user_name {username} # 单用户是否使用sudospawner可选项 # c.JupyterHub.spawner_class jupyterhub.spawner.LocalProcessSpawner这里逐个解释。c.JupyterHub.hub_ip和hub_port是hub进程内部通信的监听地址我设置为127.0.0.1只允许本机访问外部请求通过nginx反向代理转发进来安全性更好。bind_url是对外暴露的地址告诉hub它应该用什么URL来生成给用户浏览器访问的链接。c.JupyterHub.data_dir是JupyterHub存放cookie_secret、数据库文件、服务运行时状态的地方建议单独建一个目录不要放在/tmp下。cookie_secret_file这个文件特别重要JupyterHub用它来加密浏览器会话Cookie。首次启动前必须手动创建一个随机密钥文件否则每次重启hub进程用户会话全部失效所有人都会被要求重新登录。很多管理员忽略这个问题测试时还好生产环境一重启全乱了。创建密钥文件的命令mkdir -p /srv/jupyterhub openssl rand -hex 32 /srv/jupyterhub/jupyterhub_cookie_secret chown -R root:root /srv/jupyterhub chmod 700 /srv/jupyterhubc.Authenticator.open_sessions等参数和用户登录后的安全策略相关在后面细说。3.2 用户认证PAM系统用户认证与管理员权限JupyterHub支持多种认证方式比如基于数据库的自定义认证、LDAP认证、OAuth和OIDC认证等。但针对通用Linux服务器最直接、最省事的是PAM认证也就是直接用Linux系统账号来登录JupyterHub。这个方案的优点是显而易见的用户不用额外注册账号Linux系统账号直接在服务器上就能用文件权限的隔离也是天然的Linux文件权限机制。在配置文件中指定c.JupyterHub.authenticator_class jupyterhub.auth.PAMAuthenticator系统里需要创建对应的Linux用户useradd -m -s /bin/bash alice useradd -m -s /bin/bash bob passwd alice passwd bob创建好之后PAM认证插件会自动检查用户输入的用户名密码是否与Linux系统账号匹配。这样做还有一个好处是后面的文件权限完全不需要额外配置每个用户的home目录互不可见用户登录后只能访问自己的目录。管理员权限通过系统用户组来识别。创建一个hubadmin用户组把管理员都加进去groupadd hubadmin usermod -a -G hubadmin alice配置文件中指定c.Authenticator.admin_groups {hubadmin}这样alice登录之后界面上就会多出Admin管理入口可以查看所有在线的用户会话、强制停止指定用户的服务、查看所有用户的服务日志等做运维时非常有用。需要注意的一点是PAM认证默认只允许在服务器有系统账号的用户登录。如果团队里有人不想给他开SSH权限但又要他使用JupyterHub那就不能用这个方案可以在JupyterHub里配置使用NativeAuthenticator在JupyterHub自己的数据库里维护一套账号密码体系。这个后面再讲。3.3 单用户服务管理默认Spawner与SystemdSpawner对比JupyterHub中负责启动每个用户的Notebook服务的组件叫Spawner。默认的Spawner是本地进程模式也就是LocalProcessSpawner。在这种模式下每次用户登录Hub会以该用户的身份fork出一个Python进程跑Jupyter Notebook的服务端。这个模式简单够用但有一个很明显的短板进程的监控能力弱。一旦某个用户的Notebook进程意外崩溃Hub不会主动拉起它而且进程还在运行时产生的僵尸进程很难清理。更麻烦的是不同用户的服务都挂在同一个系统服务下一旦某个用户执行了耗光内存或CPU的代码整个服务器都可能卡死其他用户也跟着遭殃。SystemdSpawner的机制就不一样。它会在用户登录时通过systemd创建一个独立的用户服务单元每个用户的Jupyter Notebook进程有独立的systemd服务名例如jupyter-alice.service。这样带来的好处是进程崩溃后systemd会自动按规则重启每个用系统都有一个独立的cgroup可以精准设置CPU和内存限制日志完全隔离用journalctl -u jupyter-alice查看alice的服务日志比在Hub日志里大海捞针强多了可以配合systemd的resource control设置每个用户最多能占多少CPU、多少内存配置SystemdSpawner的两个核心参数是mem_limit和cpu_limit单位分别是字节和CPU核心数。比如我给普通用户配置4GB内存上限和2核CPU上限这样就防止了一个用户在notebook里跑个死循环导致全服务器瘫痪。需要注意的是使用SystemdSpawner时服务器上必须运行systemd作为系统初始化器。Ubuntu 20.04及之后的版本没问题如果用的是某些容器环境或者WSL没有完整的systemd就不要用这个Spawner退回LocalProcessSpawner即可。3.4 用户启动目录与权限隔离用户登录后JupyterHub会为每个用户启动一个Notebook服务服务的工作目录默认是该用户的home目录。这个逻辑在SystemdSpawner中通过user_workingdir和user_name来指定c.SystemdSpawner.user_workingdir /home/{username} c.SystemdSpawner.user_name {username}花括号里的{username}是一个占位符JupyterHub在启动不同用户的服务时会自动替换成实际的用户名。这样做的好处是每个用户的默认工作目录就是他们的home目录不管在哪儿打开Jupyter看到的都是自己那摊文件。如果要开放一个公共目录给所有用户只读访问比如一个数据集或者共享软件包目录可以在系统层面把目录权限设置为755并放在如/srv/shared_data这样的地方所有用户根据具体需求决定是否挂载到自己的工作区。不要轻易改动/home下用户的权限结构否则会引入安全隐患。用户在Notebook里能执行什么权限的系统命令由系统账号本身的权限决定。如果alice在系统里只是一个普通用户没有sudo权限那她开的Notebook就没办法执行sudo。3.5 增加管理员无法后台查看用户文件这里有一个常见误区要提醒一下。很多人以为管理员能管理用户的服务就代表管理员能看到用户notebook里的代码和数据。其实这完全是两码事。JupyterHub的管理员功能界面提供的是对服务的控制——停掉某个用户的服务、查看服务的运行状态、终止用户的kernel这些是基于systemd服务管理的和管理员直接ssh进服务器看用户的home目录是两回事。在系统层面root用户理论上始终拥有所有文件权限JupyterHub只是在这个基础上提供了一个Web管理界面。如果你的团队有代码保密的需求应该在更高的运维层面用磁盘加密、系统审计等手段来保证而不能指望JupyterHub来解决这个问题。所以我还想强调一下权限问题。JupyterHub从机制上设计了用户文件的隔离每个用户只能看到自己的notebook、自己的kernel、自己的进程。但服务器本身还是由管理员掌握的。对于管理员来说不要因为自己有系统的全部权限就随意查看用户的文件这是基本的安全伦理也是合作团队保持信任的底线。4. 完整实操过程与关键节点记录4.1 每步必做继承系统环境初始化配置实际上在JupyterHub的配置过程中最容易出问题的不是配置文件本身而是用户环境不对。举个例子。假设管理员在conda的jupyterhub环境里装了jupyterhub和notebook用户alice登录后SystemdSpawner会以alice用户身份去启动Notebook服务。这时它启动用的Python解释器是哪个如果alice自己有一个单独的conda环境那没问题。如果alice的home目录下没有独立的conda那么系统就会尝试用系统Python来跑notebook。如果系统自带的Python里根本没有notebook包启动就会直接失败。要解决这个问题有几个思路。思路一是给所有用户都装好Python和notebook包。这个在实际操作中不现实因为每来一个新用户都要装一遍环境。思路二是在Notebook服务启动时显式指定需要使用的Python解释器路径。在JupyterHub配置中可以用c.SystemdSpawner.environment来设置PATHimport os c.SystemdSpawner.environment { PATH: /opt/miniconda3/envs/jupyterhub/bin:/opt/miniconda3/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin, JUPYTER_RUNTIME_DIR: /tmp/{username}-runtime, }这样用户启动的Notebook进程就能找到conda环境里的notebook包和Jupyter命令了。思路三是我最推荐的以系统普通用户身份运行Notebook但要先确保每个用户的home目录里有一个独立的conda环境或者至少能访问一个公共的conda环境。比较标准做法是在服务器上建立一个公共的conda环境比如叫base_env所有用户都通过它来运行Python代码在Jupyter里给用户添加一个指向该环境Python解释器的Kernel。这样做的优点是环境统一依赖一致也减少了每个用户自己管理环境的负担。具体做法是在JupyterHub所在的服务器上# 建立公共conda环境 /opt/miniconda3/bin/conda create -n base_env python3.11 ipykernel jupyter -y /opt/miniconda3/bin/conda run -n base_env python -m ipykernel install --prefix/opt/miniconda3/envs/jupyterhub --name base_env --display-name Base Python 3.11然后在JupyterHub配置文件中把这个公共环境的Python路径作为所有用户默认的Kernel路径c.Spawner.kernel_spec base_env这样用户登录后打开新的NotebookKernel会自动选择Base Python 3.11用同一个统一的基础环境。4.2 用户Notebook服务的启动流程与日志观察JupyterHub配置完成之后先不要急着跑systemd服务先在后台手动启动一次hub进程确认配置文件没有语法错误conda activate jupyterhub jupyterhub -f /etc/jupyterhub/jupyterhub_config.py第一次启动时能看到几个关键日志一是Hub进程创建数据库生成初始密码hashing二是启动了configurable-http-proxy代理进程绑定到8000端口三是提示Hub已就绪等待请求。日志正常后用浏览器访问http://服务器IP:8000就能看到登录页面了。登录流程走一遍输入alice的用户名密码点击登录JupyterHub内部会依次做几件事PAM认证用户名密码确认合法后分配一个随机端口通过SystemdSpawner启动jupyter-alice服务该服务内部会启动一个Jupyter Notebook进程代理把该用户的请求转发到这个内部端口。整个过程通常需要3到8秒如果超过10秒还没看到Notebook页面基本就是Spawner环境配置有问题。此时建议立刻打开另一个SSH窗口观察alice的服务日志journalctl -u jupyter-alice -f这个日志会真实反映出Notebook服务启动过程中的细节比如Python解释器路径、缺哪个包、权限对不对、端口是否能监听。绝大多数启动失败的问题看这里就能定位。4.3 systemd服务文件创建手动启动验证没问题后把JupyterHub以systemd服务的方式托管起来。创建一个service文件sudo cat /etc/systemd/system/jupyterhub.service EOF [Unit] DescriptionJupyterHub Afternetwork.target [Service] Typesimple Userroot EnvironmentPATH/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/opt/miniconda3/bin:/opt/miniconda3/envs/jupyterhub/bin ExecStart/opt/miniconda3/envs/jupyterhub/bin/jupyterhub -f /etc/jupyterhub/jupyterhub_config.py WorkingDirectory/srv/jupyterhub Restarton-failure RestartSec5 [Install] WantedBymulti-user.target EOF systemctl daemon-reload systemctl enable jupyterhub systemctl start jupyterhub这里注意JupyterHub进程要以root身份运行才能调用系统PAM认证和创建用户服务。这一点可能让部分管理员有顾虑但这是官方文档推荐的架构。实际安全性是由各个用户进程的Spawner机制来保证的Hub进程虽然是root但每个用户的Notebook进程会通过systemd来降权到对应用户名下运行用户之间是隔离的。启动后检查服务状态systemctl status jupyterhub ss -tlnp | grep 8000这时候如果能看到java-less的LISTEN状态在0.0.0.0:8000说明服务已经正常对外监听。4.4 反向代理与HTTPS加密直接暴露8000端口给用户访问也能用但存在两个问题一是端口不标准用户容易记错二是数据明文传输Notebook里的代码、密码、模型结果完全赤裸裸暴露在网络中在内网还好一旦跨公网访问就非常危险。所以强烈建议在JupyterHub前面用nginx做反向代理并配置HTTPS。Nginx的配置片段如下server { listen 443 ssl http2; server_name jupyter.example.com; ssl_certificate /etc/letsencrypt/live/jupyter.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/jupyter.example.com/privkey.pem; # 长连接设置 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket支持JupyterLab终端功能依赖 location / { proxy_pass http://127.0.0.1:8000; } }在nginx配置中最重要的就是WebSocket代理部分。JupyterLab的终端和某些交互组件依赖WebSocket实时双向通信如果Upgrade或Connection头没有正确转发用户在界面上打开终端时会出现一直在正在连接但始终连不上的情况。配置处理好之后重新加载nginx配置nginx -t systemctl reload nginx同时修改JupyterHub配置文件中的bind_url域名c.JupyterHub.bind_url https://jupyter.example.com/jupyter然后重启JupyterHub服务。用户直接用浏览器访问https://jupyter.example.com就能安全地使用所有功能了。4.5 防火墙与安全组配置建议很多管理员在配置完服务后发现从外部浏览器无法访问第一反应是检查JupyterHub配置却忘了看防火墙。真实排查中我发现十次里至少有三次以上的服务没跑起来其实是防火墙或安全组没放行端口。在Ubuntu上用ufw的话把对外端口放行ufw allow 80/tcp ufw allow 443/tcp ufw allow 8000/tcp # 如果用8000直接对外访问 ufw status在云服务器上还要到控制台的安全组规则中检查入方向是否放行对应端口。这里提醒一下如果用了nginx做代理其实8000端口完全没必要对外开放只让nginx内部访问就够防火墙只需要放行80和443。5. 性能调优与资源隔离实战5.1 单用户资源限制的精细化管理多用户场景下最大的风险是谁也不知道用户A会在notebook里跑什么代码。几年前我在实验室搭了一台共享服务器给组里十几个学生用最初没设任何资源限制有一天某个学生跑了一个大数据处理任务内存瞬间吃满服务器直接不可用所有人的Session全断正在训练的模型全丢。后来我把SystemdSpawner的资源限制全部打开才算是把这种事故概率降到了可接受范围。除了前面说的mem_limit和cpu_limit还有一些细节值得关注。c.SystemdSpawner.mem_limit 4G c.SystemdSpawner.cpu_limit 2 c.SystemdSpawner.working_dir /home/{username} c.SystemdSpawner.user_workingdir /home/{username} c.SystemdSpawner.isolate_network True c.SystemdSpawner.slice jupyterhubc.SystemdSpawner.isolate_network设为True后每个用户的Notebook服务会有独立的网络命名空间用户之间通过网络层面的隔离能防止某些基于网络的干扰行为。c.SystemdSpawner.slice参数把用户服务归属到名为jupyterhub的systemd切片下配合systemd的资源统计一眼就能看出哪个用户当前的CPU和内存占用情况systemd-cgtop你会发现加了资源限制之后单用户跑满内存时最多只是自己的服务崩溃其他用户完全不受影响。这就是做平台和做玩具的本质区别。5.2 Spawner超时与空转回收策略在团队协作场景里很多用户登录后长时间没有操作但Notebook服务一直挂着白白占用系统资源。JupyterHub里可以对这类空闲服务设置超时回收。# 日志空闲超过30分钟就自动关闭 c.JupyterHub.shutdown_on_logout True c.Spawner.http_timeout 60 c.Spawner.start_timeout 60 c.Spawner.poll_interval 30更深度的做法是设置idle culler这是JupyterHub官方团队提供的一个后台脚本定期扫描所有用户服务的活跃状态超过阈值就调用API关闭它们。把idle-culler注册成systemd timer任务就能实现定时回收pip install jupyterhub-idle-culler然后在systemd里建立一个定时任务每小时检查一次超过2小时没操作的notebook就会自动关闭。这样配置之后服务器资源利用效率明显提升几个人在线时各开各的服务没人用的时候资源自动释放。不过也要想清楚如果团队里有跑长时间训练的情况要适当延长超时时间避免训练任务被误杀。5.3 与GPU配置相关的问题记录如果要让所有用户都能使用GPU跑深度学习训练这步需要额外处理。JupyterHub本身和GPU没有直接关系真正决定能不能用GPU的是用户Notebook进程能看到哪些设备以及CUDA环境是否正确配置。在一台有NVIDIA GPU的服务器上首先要确保驱动和CUDA Toolkit已经装好用nvidia-smi确认GPU状态正常。之后在SystemdSpawner里把GPU设备映射进去c.SystemdSpawner.extra_create_kwargs { device_policy: closed, allowed_devices: [/dev/nvidia0, /dev/nvidiactl, /dev/nvidia-uvm, /dev/nvidia-uvm-tools] }不同驱动版本对应的设备节点名可能不完全一样建议先用ls /dev/nvidia*查一下实际节点。更好的办法是给用户统一准备好conda环境并安装好pytorch或tensorflow的GPU版本保证nvidia-smi命令在notebook里能用。GPU配置中最容易踩的坑是用户在自己的环境里pip install torch的时候装的是CPU版因为pip默认安装的torch就是CPU版要用GPU就得从相应的index安装。所以管理员最好在公共环境里把GPU版框架提前装好避免用户自己装错版本后一脸懵。6. 常见问题与排查技巧实录6.1 登录一直在转圈或直接502错误这是多用户JupyterHub里最经典的问题。情况通常是用户能打开登录页输入账号密码点登录之后浏览器一直转圈最后页面报502 Bad Gateway或者Proxy Error。排查思路是先看Hub日志journalctl -u jupyterhub -n 100 --no-pager如果日志里出现类似Proxy at http://127.0.0.1:8001 failed to connect to server ...的错误说明代理到用户Notebook服务的转发链路出问题了。此时需要用journalctl -u jupyter-alice看看用户服务启动到哪一步如果用户服务没起来检查用户目录权限、系统PATH以及Spawner配置。如果用户服务起来了但还是502那大概率是代理进程或者Hub进程出现的网络配置不一致。最直接的方法是重启一次JupyterHub服务和代理进程systemctl restart jupyterhub注意这会让所有人的会话中断重新登录不是万不得已不要在大白天人多的时候执行。如果是深夜或者用户都离线了重启一次往往能解决很多沉淀状态导致的问题。不过根因还是要去查不然过两天又会出现同样的问题。6.2 用户服务启动失败Permission denied或Exec format error用户登录时Hub显示User alices server failed to start去查journalctl -u jupyter-alice常见报错包括Permission denied和Exec format error。Permission denied的大概率原因是用户的home目录权限不对。Linux对home目录的权限要求很严格如果home目录或其他目录对当前用户不可写或者执行者没有执行权限notebook启动就会失败。用ls -ld /home/alice查看一下当前权限正常应该是drwxr-x---之类的。修复方式chown -R alice:alice /home/alice chmod 700 /home/aliceExec format error出现得比较罕见一种情况是用户home目录挂载在某个网络文件系统上而该文件系统的noexec选项禁止执行二进制文件。这时候notebook二进制虽然存在却执行不了。解决办法是检查挂载参数或者把jupyter的runtime目录和kernel执行目录改到本地磁盘。还有一种情况用户环境里用了32位Python但服务器是64位内核也会报Exec format error。这种基本只能重装环境解决。6.3 多个用户同时在线时内存经常告警资源告警是多人同时使用服务器必然遇到的。配置了mem_limit后单个用户最多占用4G内存但如果有五个用户同时各占3G服务器总内存迟早也要爆炸。这里需要规划一下总内存和每个用户的配额。比如服务器总内存32G系统自身占用和JupyterHub环境预留6G左右剩下26G分给用户。如果平时同时在线人数最多8人左右单用户配额设置3G是相对稳妥的。太少了用户体验差一个稍微大点的数据集分析都跑不了太多了其他用户无法使用失去了共享的意义。更好的办法是给用户单独集中使用大的数据目录提醒团队成员禁抢公共数据目录里跑重计算重要计算尽量分类错时跑。如果在服务器上部署了Prometheus和Grafana可以监控每个用户的内存使用趋势这样对调优容量和配额设计会更有把握。6.4 用户忘记密码怎么办PAM认证模式下用户密码就是Linux系统账号密码忘记密码时管理员在服务器端执行sudo passwd alice然后告诉alice新密码就可以重新登录了。这里有一个隐藏细节PAMAuthenticator默认情况下允许用户在JupyterHub页面上找一封重置密码邮件吗其实不行因为没有配置邮件系统。所以管理员必须能登录服务器才能帮用户重置密码。如果你的团队希望用户能自助修改或重置密码建议接入NativeAuthenticator在JupyterHub界面里提供注册和密码修改功能。但那样做需要引入用户自注册对某些安全要求严格的团队可能不可接受按需采用即可。6.5 常见问题速查表问题现象可能原因排查步骤解决办法登录后一直转圈Hub与代理通信异常journalctl -u jupyterhub重启JupyterHub服务或检查代理进程502 Bad Gateway单用户Notebook服务未启动journalctl -u jupyter-用户名修复用户目录权限或Spawner配置用户服务启动失败Permission denied用户home目录权限错误ls -ld /home/用户名chown/chmod修复用户目录权限访问页面打开很慢HTTPS证书配置或DNS解析缓慢curl -v https://域名检查nginx代理和证书有效期用户kernel一直显示正在连接WebSocket转发未配置检查nginx的Upgrade/Connection头修改nginx代理配置并reload内存告警单用户配额过大或用户代码有消耗问题systemd-cgtop降低mem_limit或优化用户代码所有用户都无法访问Hub进程挂掉或系统资源耗尽systemctl status jupyterhub启动服务或排查OOM杀死记录用户环境里没有基础包用户kernel指向了错误的Python检查kernel列表配置统一的公共conda kernel路径7. 进阶扩展与安全加固指南7.1 多用户JupyterHub的备份与恢复策略在一套JupyterHub体系稳定运行一段时候后备份问题会逐渐暴露。用户自己的代码存各自的home目录这点通常不需要整体备份真正需要重点管理的是JupyterHub的元数据数据库文件、Cookie密钥、配置文件和用户环境清单。准备一个备份脚本定期压缩打包#!/bin/bash BACKUP_DIR/home/admin/backups DATE$(date %Y%m%d-%H%M%S) mkdir -p $BACKUP_DIR # 备份hub数据目录 tar -czf $BACKUP_DIR/jupyterhub-data-$DATE.tar.gz /srv/jupyterhub # 备份hub配置 tar -czf $BACKUP_DIR/jupyterhub-config-$DATE.tar.gz /etc/jupyterhub # 备份用户环境清单 conda activate jupyterhub conda list --explicit $BACKUP_DIR/jupyterhub-env-$DATE.txt把脚本挂到crontab里设置每天凌晨执行。恢复时只需要先把系统装好JupyterHub依赖然后把备份的/srv/jupyterhub和/etc/jupyterhub解压覆盖重启服务即可。Cookie密钥一旦丢失所有用户的会话会全部失效所以强烈建议把cookie_secret单独放一个文件合并到备份范围内。7.2 通过LDAP或企业账号系统接入认证很多企业内部有统一的账号系统比如OpenLDAP或Active Directory。JupyterHub也能接入这类系统让用户直接用办公账号登录服务器省去维护Linux系统账号的麻烦。原理是使用LDAPAuthenticator或OAuthenticator插件替代PAMAuthenticator。以LDAP为例pip install jupyterhub-ldapauthenticator配置也很容易c.JupyterHub.authenticator_class ldapauthenticator.LDAPAuthenticator c.LDAPAuthenticator.server_address ldap.example.com c.LDAPAuthenticator.bind_dn_template uid{username},oupeople,dcexample,dccom c.LDAPAuthenticator.user_search_base oupeople,dcexample,dccom c.LDAPAuthenticator.user_attribute uid c.LDAPAuthenticator.lookup_dn True c.LDAPAuthenticator.lookup_dn_search_filter ((objectClassposixAccount)(uid{username})) c.LDAPAuthenticator.lookup_dn_search_user cnadmin,dcexample,dccom c.LDAPAuthenticator.lookup_dn_search_password admin_password接入LDAP之后Linux系统账号可以仍然存在因为Spawner还需要用它们来启动进程也可以配置成动态创建用户目录。实际上比较稳妥的方案是LDAP用户登录后通过SystemdSpawner以某个固定用户身份运行服务然后通过环境变量把用户身份传给Notebook里的业务逻辑。这样的配置会稍微复杂一些适合有专门运维团队的场景。7.3 结合JupyterLab的扩展插件与主题定制JupyterHub和JupyterLab原生支持扩展插件用户可以在自己的界面里安装JupyterLab插件来增强体验。管理员如果希望统一团队的界面风格和功能也可以在config里为所有用户指定插件列表conda activate jupyterhub pip install jupyterlab-git jupyterlab-spellchecker jupyterlab-toc对于安装的插件如果想对全局用户生效需要放在JupyterLab的全局扩展目录中。由于JupyterLab的扩展机制和Python包类似安装后会同时提供一个前端资源和后端服务需要手动执行jupyter lab build在执行构建时系统会用Node.js和webpack把所有前端的JS资源打包耗时通常在三到十分钟不等期间JupyterLab服务需要暂停使用所以尽量选在对用户影响小的时候执行。构建成功后再访问JupyterLab所有用户都能看到新装的插件功能了。7.4 多服务器节点扩展的可能性最后聊一个常见困惑手动部署的JupyterHub能不能横向扩展答案是完全可以但要拆开来看。JupyterHub的Hub进程和代理本身就是无状态的可以横向扩展。单用户Notebook服务的本质是——每个用户都是独立的进程理论上可以分布在不同服务器上。常见做法是配合DockerSpawner或KubeSpawnerKubernetes来自动分配用户到不同节点。但如果保持手动部署方案最简单可行的横向扩展是在每台服务器上各装一个独立的JupyterHub实例通过统一的入口域名做负载均衡或分流。比如一台机器分配给A组一台机器分配给B组各自有自己的Hub和用户目录互不干扰。这种方案虽然做不到真正的一个Hub统管所有机器但实现简单、稳定性高对于两到三台服务器的中小团队来说运维成本低得不是一星半点。真要到了一台Hub管几十台机器的规模那时候再迁移到Kubernetes也不算亏因为底层的镜像构建、环境管理、用户体系在手动部署阶段沉淀下来的经验完全能用得上。写在最后一点真实体会这篇文章从决定写到最后写完前后跨度将近一个月中间一直在用自己搭的这套JupyterHub环境做各种验证和记录。我个人觉得手动部署JupyterHub最大的价值不在于省了容器那点开销而在于它逼着你把整个服务链路从下到上摸了一遍。你会知道代理为什么转发超时知道用户服务为什么会启动失败知道某个权限配置影响的是哪一层而不是出了问题只能把容器删了重来。这种掌控感在真正需要长期运维和团队协作的时候会很不一样。最后再分享一个小技巧。如果你也是第一次在生产服务器上部署强烈建议先在本地虚拟机里完整走一遍流程包括创建用户、登录测试、并发访问、模拟用户跑一个大型计算、查看日志以及重启恢复。我用这套方案在测试环境跑了完整流程之后部署到正式服务器时半小时就完成了但前期测试踩掉的那些坑每一个都在正式环境里准确地兑现出来了。别嫌麻烦这一步能省下后面大量的排障时间。如果你在配置过程中遇到什么奇怪的问题欢迎留言描述你看到的日志和报错我尽量帮着定位。毕竟多用户JupyterHub这个事儿最大的坑永远在你看不到的细节里。
