Linux服务器如何部署JupyterHub多用户环境并完成权限验证?
部署目标是让多名 Linux 用户使用各自的系统账号登录 JupyterHub,并以各自的 Linux 身份运行 JupyterLab。下面以 Ubuntu 22.04/24.04、Python 3、PAM 认证和 JupyterHub 自带的 LocalProcessSpawner 为例。该方式适合单机或小规模团队;Hub 进程需要 root 权限来切换用户身份,普通用户的文件访问仍受 Linux 文件权限控制。
开始前准备一台可用的 Linux 服务器、具备 sudo 权限的管理员账号,以及计划加入的系统用户。首次验证建议只监听本机地址;不要将未启用 HTTPS 的 HTTP 登录页面直接暴露到公网。
A5数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器资源,覆盖多核CPU、大内存、NVMe存储及GPU等配置,可为JupyterHub多用户Notebook运行、数据分析、数据库读写和AI模型测试提供硬件基础。结合不同地区的网络线路、带宽与存储方案,能够匹配跨地域访问、多人并发计算及大容量数据处理等部署场景。
一、准备系统用户和安装环境
先更新软件包索引并安装 Python 虚拟环境、Node.js 和 npm。JupyterHub 的代理组件 configurable-http-proxy 由 npm 安装,JupyterHub 本身则放在独立的 Python 虚拟环境中,避免与系统 Python 包混装。
sudo apt update
sudo apt install -y python3 python3-venv python3-pip nodejs npm
检查运行环境是否可用:
python3 --version
node --version
npm --version
应能看到 Python、Node.js 和 npm 的版本号。如果 Node.js 版本过旧、npm 安装代理组件时报兼容错误,先检查当前发行版仓库提供的版本,再选用与服务器发行版兼容的 Node.js 安装来源;不要在未确认来源和版本的情况下替换系统组件。
创建两个示例用户:hubadmin 用于 Hub 管理,alice 用于普通用户验证。实际部署时替换为自己的账号名。
sudo adduser hubadmin
sudo adduser alice
adduser 会交互式设置密码并创建主目录。不要给普通 JupyterHub 用户添加 sudo 权限。确认账号和主目录已创建:
id hubadmin
id alice
getent passwd hubadmin alice
输出应包含两个账号及其 UID、主组和主目录。JupyterHub 的 PAM 认证依赖系统账号认证;用户必须有可用密码,并且未被系统账号策略禁用。
二、安装 JupyterHub 与 JupyterLab
创建专用虚拟环境,并在其中安装 JupyterHub、JupyterLab。这样 Hub 和用户启动的 Notebook 服务都能使用同一套 Python 包。
sudo python3 -m venv /opt/jupyterhub
sudo /opt/jupyterhub/bin/python -m pip install --upgrade pip
sudo /opt/jupyterhub/bin/python -m pip install jupyterhub jupyterlab
再安装代理组件:
sudo npm install -g configurable-http-proxy
分别确认三个命令可执行:
/opt/jupyterhub/bin/jupyterhub --version
/opt/jupyterhub/bin/jupyter-lab --version
configurable-http-proxy --version
如果最后一条提示找不到命令,检查 npm 全局可执行文件目录是否在服务的 PATH 中:
npm bin -g
command -v configurable-http-proxy
确认代理程序路径后,可在后续 systemd 服务中设置包含该路径的 PATH。不要通过随意复制二进制文件来绕过路径问题。
三、配置认证、用户范围和工作目录
创建配置目录及 Hub 运行目录。运行目录用于存放运行状态等文件,限制为 root 可访问;用户的 Notebook 文件则保存在各自主目录中。
sudo install -d -o root -g root -m 700 /etc/jupyterhub
sudo install -d -o root -g root -m 700 /srv/jupyterhub
sudo /opt/jupyterhub/bin/jupyterhub --generate-config \
-f /etc/jupyterhub/jupyterhub_config.py
编辑配置文件:
sudo nano /etc/jupyterhub/jupyterhub_config.py
在文件末尾加入以下配置。示例仅允许 hubadmin 和 alice 登录;新增用户时,要同步更新 allowed_users。
c.JupyterHub.bind_url = 'http://127.0.0.1:8000'
c.JupyterHub.spawner_class = 'jupyterhub.spawner.LocalProcessSpawner'
c.Authenticator.allowed_users = {'hubadmin', 'alice'}
c.Authenticator.admin_users = {'hubadmin'}
c.Spawner.notebook_dir = '~/work'
c.Spawner.default_url = '/lab'
这里使用 PAM 认证器的默认实现,不需要自行填写 authenticator_class。allowed_users 限定可登录的系统账号,admin_users 则指定 Hub 管理员;管理员权限不等于 Linux root 权限。保持 bind_url 为 127.0.0.1,可避免测试阶段直接向外部网络开放明文登录页面。需要让其他设备访问时,应在部署完成后另行配置受控的 HTTPS 入口。
保存后收紧配置文件权限:
sudo chown root:root /etc/jupyterhub/jupyterhub_config.py
sudo chmod 600 /etc/jupyterhub/jupyterhub_config.py
为每名用户创建工作目录。以下目录所有者设置必须与实际系统账号一致:
sudo install -d -o hubadmin -g hubadmin -m 700 /home/hubadmin/work
sudo install -d -o alice -g alice -m 700 /home/alice/work
验证目录归属和写入权限:
sudo -u hubadmin test -w /home/hubadmin/work && echo "hubadmin 可写"
sudo -u alice test -w /home/alice/work && echo "alice 可写"
sudo -u alice test ! -r /home/hubadmin/work && echo "alice 不能读取 hubadmin 工作目录"
预期分别输出可写和不能读取的提示。实际访问权限也受主目录权限、文件 ACL 和共享组配置影响;如果用户需要共享数据,应只对指定目录设置共享组或 ACL,不要为方便而放宽整个 /home 的权限。
四、创建 systemd 服务并启动
JupyterHub 需要管理不同 Linux 用户的进程,因此本示例以 root 身份运行 Hub 服务。此权限会扩大 Hub 服务本身的安全影响范围,应仅允许可信管理员修改配置和服务文件,也不要在 Hub 配置中加载来源不明的扩展或脚本。
创建 systemd 单元:
sudo nano /etc/systemd/system/jupyterhub.service
写入以下内容:
[Unit]
Description=JupyterHub
After=network.target
[Service]
Type=simple
User=root
WorkingDirectory=/srv/jupyterhub
Environment="PATH=/opt/jupyterhub/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/opt/jupyterhub/bin/jupyterhub -f /etc/jupyterhub/jupyterhub_config.py
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
确认 configurable-http-proxy 的实际路径包含在 PATH 中。如果 command -v configurable-http-proxy 显示的目录不在上面的路径内,将该目录加入 Environment 的 PATH,然后保存。重新载入 systemd 并启动:
sudo systemctl daemon-reload
sudo systemctl enable --now jupyterhub
先检查服务状态,再查看启动日志:
sudo systemctl status jupyterhub --no-pager
sudo journalctl -u jupyterhub -n 50 --no-pager
服务应处于 active (running)。进一步检查端口监听:
sudo ss -lntp | grep ':8000'
本示例应监听 127.0.0.1:8000。如果没有监听,或服务反复退出,先根据日志处理错误,不要急于开放防火墙端口。
五、验证登录与权限隔离
在服务器本机请求登录页面:
curl -I http://127.0.0.1:8000
收到 HTTP 响应即可说明 Hub 的 Web 入口已应答;具体状态码可能随软件版本及访问路径有所不同。远程管理员可以通过受信任的 SSH 会话建立本地端口转发进行验证,例如在管理员工作站执行:
ssh -L 8000:127.0.0.1:8000 admin@服务器地址
随后在本机浏览器访问 http://127.0.0.1:8000。输入 alice 的系统密码后,应进入该用户的 JupyterLab。再用 hubadmin 登录,确认其能够看到 Hub 管理界面。输入错误密码应无法登录;未加入 allowed_users 的有效系统账号也不应获得访问权限。
首次登录后,回到服务器检查用户进程身份:
ps -eo user,pid,args | grep -E 'jupyter-lab|jupyterhub-singleuser' | grep -v grep
运行用户服务器的进程应对应登录账号,而不是所有用户都以 root 运行。检查工作目录归属:
sudo -u alice sh -c 'touch /home/alice/work/.permission-check'
stat -c '%U:%G %a %n' /home/alice/work/.permission-check
sudo rm -f /home/alice/work/.permission-check
预期文件所有者为 alice。最后一条命令仅删除刚刚创建的测试文件;执行前确认路径无误。不要用递归删除命令清理用户主目录。
需要区分三类权限:PAM 决定账号密码是否有效,allowed_users 决定该账号能否登录 Hub,Linux 文件权限决定登录后的进程可以读写哪些文件。任意一层配置正确,都不能替代另外两层的检查。

六、常见失败处理
登录页面无法访问
先检查服务状态和监听地址:
sudo systemctl status jupyterhub --no-pager
sudo ss -lntp | grep ':8000'
如果服务正常但没有外部设备可访问,这是 127.0.0.1 绑定的预期结果,不代表 Hub 故障。只有在已配置安全的 HTTPS 入口并确认访问范围后,才调整监听地址和网络策略。不要仅为排障直接将明文端口开放到公网。
用户密码正确但被拒绝
检查账号是否存在、是否被禁用,以及用户名是否列在 allowed_users 中:
getent passwd alice
sudo passwd -S alice
再检查 Hub 日志:
sudo journalctl -u jupyterhub -n 100 --no-pager
若新增账号后仍不能登录,核对配置文件是否保存、账号拼写是否一致,并在修改后重启服务。不要通过给用户提权来解决认证问题。
用户服务器无法启动
查看 Hub 日志中的启动失败信息,并确认用户主目录及工作目录存在且可写:
sudo -u alice test -d /home/alice/work && echo "目录存在"
sudo -u alice test -w /home/alice/work && echo "目录可写"
同时确认虚拟环境中已安装 JupyterLab:
/opt/jupyterhub/bin/jupyter-lab --version
若代理命令找不到,回查 npm 全局安装结果和 systemd 中的 PATH。改完配置或服务文件后,执行 sudo systemctl daemon-reload(服务文件有改动时)并重启 JupyterHub,再检查新日志。
七、验收与回滚检查项
部署验收至少确认以下事项:
jupyterhub服务已启用且处于运行状态,端口监听符合预期。- 允许列表中的普通用户可登录,未授权用户和错误密码不能登录。
- 普通用户进程以对应 Linux 用户身份运行。
- 用户工作目录归属正确,普通用户无法读取其他用户的私有工作目录。
- 配置文件仅 root 可读写,未对外开放未加密的登录页面。
若首次验证失败需要撤回部署,先停止并禁用服务:
sudo systemctl disable --now jupyterhub
如果要移除 systemd 单元,先确认其路径确为本次创建的文件,再删除并重新载入 systemd:
sudo rm /etc/systemd/system/jupyterhub.service
sudo systemctl daemon-reload
虚拟环境和配置目录中可能包含后续排障所需内容,回滚时优先保留备份,不要直接删除 /srv/jupyterhub、用户主目录或整个 /etc/jupyterhub。确认不再需要 Hub 状态、配置和用户数据后,再按目录逐项核对并处理;卸载 JupyterHub 不会自动删除 Linux 用户及其文件。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/4734.html



