Linux服务器如何部署JupyterHub多用户环境并完成权限验证?

发布人:A5数据发布时间:2026-10-20 11:07阅读量:122

部署目标是让多名 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

相关推荐