在Linux服务器上首次部署Jupyter Notebook,如何启动并限制访问范围?

发布人:A5数据发布时间:2026-10-26 17:44阅读量:119

首次部署 Jupyter Notebook 时,建议使用独立的 Linux 用户和 Python 虚拟环境,不要直接以 root 运行。若主要通过 SSH 管理服务器,最稳妥的访问方式是让 Jupyter 只监听服务器本机的 127.0.0.1,再通过 SSH 隧道访问;如果必须让办公网或私有网络直接打开,则绑定服务器私网 IP,并在系统防火墙和云平台安全组中仅放行指定网段。

下面以 Ubuntu 22.04/24.04、Debian 12 等使用 apt 的发行版为例,安装当前 Python 环境中的 Notebook 7,并使用 Jupyter Server 配置项完成启动、认证和访问范围限制。命令输出属于示例,实际路径、IP 地址和端口应以服务器环境为准。

A5数据提供中国香港、美国、日本、新加坡等地区的物理服务器,涵盖不同档位的CPU、内存及SSD、NVMe存储资源,可为Linux服务器上的Jupyter Notebook提供运行环境,承载项目文件和数据处理任务。对于在Notebook中开展模型测试或图像处理的场景,其香港、美国GPU服务器还提供A100 80GB、RTX 4090等显卡选项。

一、准备条件与访问方案

1. 确认系统、Python 和端口

先登录服务器,确认发行版、Python 版本以及目标端口是否已经被占用。

cat /etc/os-release
python3 --version
ss -lntp | grep ':8888' || true
ip -br addr

建议满足以下条件:

  • 使用具备 sudo 权限的管理账号完成系统安装。
  • Python 版本建议为 3.9 或更高版本。
  • 服务器上存在可用的 SSH 服务。
  • 计划使用的 8888 端口没有被其他服务占用。
  • 准备一个专用的 Jupyter 工作目录,不直接把整个用户家目录暴露为 Notebook 根目录。
  • 服务器具有足够的磁盘空间。Notebook 文件、数据集和运行时生成的检查点文件都会占用磁盘。

如果 Python 版本过低,不要直接在系统目录中覆盖发行版自带 Python。应先使用发行版提供的较新 Python 包,或改用独立的 Python 安装方式,然后再创建虚拟环境。

2. 选择访问边界

首次部署时,可以从以下两种方式中选择一种:

一、准备条件与访问方案配图

访问方式Jupyter 监听地址适用场景外部端口暴露情况
SSH 隧道127.0.0.1管理员或开发人员通过 SSH 使用不需要对外开放 8888
私有网络访问服务器私网 IP办公网、专有网络或内网客户端访问仅放行指定网段

不建议直接配置为 0.0.0.0 并将 8888 对整个互联网开放。Jupyter 自带的身份认证不能替代网络边界控制;如果确实需要公网访问,还应配合 HTTPS、反向代理、访问控制和安全审计,这已经超出首次本地部署的范围。

本文先按“SSH 隧道”完成配置。后文单独给出改为私有网络访问时需要调整的配置和防火墙规则。

二、创建专用用户和 Python 虚拟环境

1. 创建 Jupyter 用户

如果服务器上尚未有专用用户,可以创建一个名为 jupyter 的普通用户。该命令不会修改现有用户的数据,但会新增一个系统账号。

id jupyter >/dev/null 2>&1 || sudo adduser --disabled-password --gecos "" jupyter

创建 Notebook 目录,并将目录所有者设置为该用户:

sudo install -d -o jupyter -g jupyter -m 0750 /home/jupyter/notebooks

确认用户和目录权限:

getent passwd jupyter
sudo -u jupyter stat -c '%U:%G %a %n' /home/jupyter/notebooks

预期结果类似:

jupyter:x:1001:1001:,,,:/home/jupyter:/bin/bash
jupyter:jupyter 750 /home/jupyter/notebooks

如果系统中已经存在 jupyter 用户,但其家目录不是 /home/jupyter,后续命令中的路径需要按 getent passwd jupyter 返回的实际家目录调整,不要直接套用示例路径。

2. 安装虚拟环境支持

在 Ubuntu 或 Debian 上安装 Python 虚拟环境和 pip 组件:

sudo apt update
sudo apt install -y python3-venv python3-pip

如果系统提示软件包不存在,应先检查 /etc/apt/sources.list 和发行版版本,不要把其他发行版的仓库混入当前系统。

切换到专用用户,创建虚拟环境:

sudo -iu jupyter

在 jupyter 用户环境中执行:

python3 -m venv /home/jupyter/.venvs/notebook
source /home/jupyter/.venvs/notebook/bin/activate

python -m pip install --upgrade pip
python -m pip install "notebook>=7,<8"

使用虚拟环境的好处是避免系统 Python 与 Jupyter 依赖相互覆盖。安装完成后验证命令路径和版本:

which python
which jupyter
python --version
jupyter notebook --version
python -m pip show notebook jupyter_server

预期的 which 结果应指向类似路径:

/home/jupyter/.venvs/notebook/bin/python
/home/jupyter/.venvs/notebook/bin/jupyter

如果 which python 仍然指向 /usr/bin/python3,说明虚拟环境没有激活。此时重新执行:

source /home/jupyter/.venvs/notebook/bin/activate

三、配置 Notebook 根目录和身份认证

1. 生成并备份配置文件

Jupyter Server 采用 Python 配置文件。先创建配置目录;如果配置文件已经存在,先备份,避免覆盖已有设置。

mkdir -p /home/jupyter/.jupyter

if [ -f /home/jupyter/.jupyter/jupyter_server_config.py ]; then
    cp /home/jupyter/.jupyter/jupyter_server_config.py \
       "/home/jupyter/.jupyter/jupyter_server_config.py.bak.$(date +%Y%m%d%H%M%S)"
fi

首次部署可以写入以下配置:

cat > /home/jupyter/.jupyter/jupyter_server_config.py <<'EOF'
c = get_config()

c.ServerApp.ip = "127.0.0.1"
c.ServerApp.port = 8888
c.ServerApp.open_browser = False
c.ServerApp.allow_remote_access = False
c.ServerApp.allow_root = False
c.ServerApp.root_dir = "/home/jupyter/notebooks"
EOF

这些配置分别表示:

  • ip = "127.0.0.1":只接受服务器本机连接。
  • port = 8888:使用 TCP 8888 端口。
  • open_browser = False:服务器没有图形桌面时不尝试打开浏览器。
  • allow_remote_access = False:不允许直接作为远程 Web 服务使用。
  • allow_root = False:禁止以 root 身份启动。
  • root_dir:浏览器进入 Notebook 后默认看到的文件范围。

检查配置文件内容和权限:

sed -n '1,120p' /home/jupyter/.jupyter/jupyter_server_config.py
stat -c '%U:%G %a %n' /home/jupyter/.jupyter/jupyter_server_config.py

配置文件应归属于 jupyter 用户,权限不宜对所有用户开放:

chown jupyter:jupyter /home/jupyter/.jupyter/jupyter_server_config.py
chmod 600 /home/jupyter/.jupyter/jupyter_server_config.py

上述权限命令在 jupyter 用户下执行即可。如果当前仍是管理账号,则改用:

sudo chown jupyter:jupyter /home/jupyter/.jupyter/jupyter_server_config.py
sudo chmod 600 /home/jupyter/.jupyter/jupyter_server_config.py

2. 设置登录密码并保留令牌认证

在虚拟环境中执行密码设置命令:

source /home/jupyter/.venvs/notebook/bin/activate
jupyter server password

命令会交互式要求输入两次密码。密码不要直接写在命令行中,否则可能进入 Shell 历史记录。建议使用与系统登录密码不同的长密码。

该命令通常会在以下文件中保存哈希后的密码:

/home/jupyter/.jupyter/jupyter_server_config.json

验证文件是否生成,但不要把其中的哈希内容发布到日志或工单中:

test -s /home/jupyter/.jupyter/jupyter_server_config.json \
  && echo "Jupyter 密码配置文件已生成"

默认令牌认证仍可能处于启用状态。启动时终端可能显示带有 ?token= 的访问地址,这个令牌等同于临时登录凭据,不应发送给无关人员。首次验证可以使用命令行输出的令牌,也可以在浏览器中输入刚设置的密码。

四、首次启动与本机验证

1. 以前台方式启动

仍然在 jupyter 用户和虚拟环境中启动,先不要急于配置开机自启:

source /home/jupyter/.venvs/notebook/bin/activate

jupyter notebook \
  --config=/home/jupyter/.jupyter/jupyter_server_config.py

启动成功时,终端通常会出现类似信息:

[I 10:20:31.000 ServerApp] Jupyter Server 2.x.x is running at:
[I 10:20:31.000 ServerApp] http://127.0.0.1:8888/tree
[I 10:20:31.000 ServerApp] Use Control-C to stop this server and shut down all kernels.

如果输出中带有令牌链接,应将其视为敏感信息。当前终端保持运行状态,不要关闭。另开一个 SSH 会话,在服务器上验证监听地址:

ss -lntp | grep ':8888'

SSH 隧道模式下,预期看到类似结果:

LISTEN 0 128 127.0.0.1:8888 0.0.0.0:*

重点是监听地址应为 127.0.0.1:8888,而不是 0.0.0.0:8888。如果出现后者,说明配置没有被读取,或者启动命令中存在其他参数覆盖配置。

在服务器本机测试 HTTP 响应:

curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  http://127.0.0.1:8888/tree

出现 200、302 或需要认证的响应,通常说明 Web 服务已经有响应。若显示连接失败,应先检查前台启动窗口中的错误信息。

2. 从管理电脑建立 SSH 隧道

在本地电脑执行以下命令,其中 admin 替换为实际的 SSH 登录用户,SERVER_IP 替换为服务器地址:

四、首次启动与本机验证配图

ssh -N -L 8888:127.0.0.1:8888 admin@SERVER_IP

参数含义如下:

  • -N:只建立隧道,不执行远程 Shell 命令。
  • -L 8888:127.0.0.1:8888:把本地 127.0.0.1:8888 转发到服务器本机的 127.0.0.1:8888。
  • admin@SERVER_IP:使用已有的 SSH 管理账号连接服务器。

如果本地 8888 端口已经被占用,可以改用本地 18888,但远端端口仍保持 8888:

ssh -N -L 18888:127.0.0.1:8888 admin@SERVER_IP

然后在本地浏览器打开:

http://127.0.0.1:8888/tree

或:

http://127.0.0.1:18888/tree

浏览器出现登录页面后,使用设置的密码或启动日志中的令牌完成认证。能够看到 /home/jupyter/notebooks 下的目录,并能新建一个测试 Notebook,说明安装、认证、端口转发和工作目录均已生效。

测试结束后,可以回到前台启动窗口按 Ctrl+C 停止服务。只有前台验证通过后,才建议配置 systemd 长期运行。

五、配置 systemd 让服务持续运行

1. 创建服务单元

停止前台进程后,回到具有 sudo 权限的管理账号。确认系统中不存在同名且正在使用的服务,不要直接覆盖已有运维配置:

sudo systemctl cat jupyter.service 2>/dev/null || true

首次部署可以创建 /etc/systemd/system/jupyter.service:

sudo tee /etc/systemd/system/jupyter.service >/dev/null <<'EOF'
[Unit]
Description=Jupyter Notebook Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=jupyter
Group=jupyter
WorkingDirectory=/home/jupyter/notebooks
ExecStart=/home/jupyter/.venvs/notebook/bin/jupyter notebook --config=/home/jupyter/.jupyter/jupyter_server_config.py
Restart=on-failure
RestartSec=5
UMask=0027

[Install]
WantedBy=multi-user.target
EOF

该服务只会以 jupyter 用户运行,UMask=0027 可以减少新建文件被其他普通用户读取的范围。服务文件属于系统配置,修改前应保留原文件副本;如果系统中已有同名服务,应改用其他服务名或先确认原服务用途。

2. 启动并检查服务

重新加载 systemd 配置,然后启动服务:

sudo systemctl daemon-reload
sudo systemctl enable --now jupyter.service

enable --now 同时执行开机自启和立即启动,会改变系统启动行为。如果只想先测试当前启动状态,可以分开执行:

sudo systemctl start jupyter.service

查看服务状态:

sudo systemctl status jupyter.service --no-pager

正常情况下应看到:

Active: active (running)
Main PID: xxxx (jupyter-notebook)

再检查最近日志:

sudo journalctl -u jupyter.service -n 50 --no-pager

确认监听范围和运行用户:

ss -lntp | grep ':8888'
sudo systemctl show jupyter.service -p User -p WorkingDirectory

预期结果应同时满足:

  • 服务状态为 active (running)。
  • 运行用户为 jupyter。
  • 工作目录为 /home/jupyter/notebooks。
  • 监听地址为 127.0.0.1:8888。
  • 通过 SSH 隧道可以打开登录页面。

如果服务启动后自动退出,先不要连续重启,应查看完整日志:

sudo journalctl -u jupyter.service -b --no-pager

六、需要私有网络访问时的调整方式

如果办公网或私有网络中的其他电脑必须直接访问 Jupyter,可以将监听地址改成服务器的私网 IP,例如 10.20.1.15。这会扩大访问面,因此必须同步配置防火墙和云平台安全组。

先确认服务器实际私网地址:

ip -br addr

然后备份配置文件:

sudo cp /home/jupyter/.jupyter/jupyter_server_config.py \
  "/home/jupyter/.jupyter/jupyter_server_config.py.bak.$(date +%Y%m%d%H%M%S)"

编辑配置文件:

sudo -u jupyter nano /home/jupyter/.jupyter/jupyter_server_config.py

将相关配置改为:

c = get_config()

c.ServerApp.ip = "10.20.1.15"
c.ServerApp.port = 8888
c.ServerApp.open_browser = False
c.ServerApp.allow_remote_access = True
c.ServerApp.allow_root = False
c.ServerApp.root_dir = "/home/jupyter/notebooks"

保存后重启服务:

sudo systemctl restart jupyter.service
sudo systemctl status jupyter.service --no-pager
ss -lntp | grep ':8888'

此时预期监听结果类似:

LISTEN 0 128 10.20.1.15:8888 0.0.0.0:*

1. 限制 UFW 来源网段

如果服务器使用 UFW,先查看现有规则并确认 SSH 放行规则,避免误操作导致远程失联:

sudo ufw status numbered

例如,只允许 10.20.0.0/16 网段访问 8888:

sudo ufw allow from 10.20.0.0/16 to any port 8888 proto tcp comment 'Jupyter private access'

再次检查:

sudo ufw status verbose

不要为了让 Jupyter 可访问而直接执行 ufw enable,尤其不要在没有确认 SSH 规则的情况下启用防火墙。云服务器还需要在云平台安全组中配置同样的来源限制,不能只依赖系统内的 UFW 规则。

从允许的私网客户端访问:

http://10.20.1.15:8888/tree

此时仍然需要 Jupyter 密码或令牌。网络限制和应用认证是两层控制,不能相互替代。

2. 私有网络模式的回滚

如果不再需要直接访问,可以先删除防火墙规则,再将 Jupyter 恢复为本机监听:

sudo ufw delete allow from 10.20.0.0/16 to any port 8888 proto tcp

然后将配置恢复为:

c.ServerApp.ip = "127.0.0.1"
c.ServerApp.allow_remote_access = False

最后重启服务并重新使用 SSH 隧道:

sudo systemctl restart jupyter.service
ss -lntp | grep ':8888'

七、常见失败处理

1. 创建虚拟环境时报 No module named venv

说明系统没有安装虚拟环境组件。使用管理账号执行:

sudo apt update
sudo apt install -y python3-venv

然后重新创建虚拟环境。不要把 pip 包直接安装到系统 Python 中。

2. pip 报 externally-managed-environment

这是发行版保护系统 Python 的提示。确认已经激活虚拟环境:

source /home/jupyter/.venvs/notebook/bin/activate
which python
python -m pip --version

如果路径不是 /home/jupyter/.venvs/notebook/bin/,先不要继续安装。

3. 8888 端口被占用

先查看占用者:

sudo ss -lntp | grep ':8888'

不要直接执行 kill -9,因为占用端口的进程可能属于其他业务。确认进程归属和用途后,可以选择:

  • 将 Jupyter 端口改为 8890,并同步修改 SSH 隧道或私网访问地址。
  • 停止确认无用的测试进程。
  • 保留现有服务,选择其他端口。

如果改用 8890,配置和隧道必须同时对应:

c.ServerApp.port = 8890
ssh -N -L 8890:127.0.0.1:8890 admin@SERVER_IP

4. systemd 启动失败但前台启动正常

重点检查 systemd 使用的路径和用户:

sudo journalctl -u jupyter.service -n 100 --no-pager
sudo -u jupyter test -x /home/jupyter/.venvs/notebook/bin/jupyter
sudo -u jupyter test -r /home/jupyter/.jupyter/jupyter_server_config.py
sudo -u jupyter test -d /home/jupyter/notebooks

常见原因包括:

  • 虚拟环境路径写错。
  • 配置文件由 root 创建,jupyter 用户无法读取。
  • root_dir 目录不存在或无写权限。
  • 前台进程仍占用 8888。
  • 配置文件使用了当前安装版本不支持的旧配置项。

5. 服务器本机可以访问,远程浏览器无法访问

如果当前配置是 127.0.0.1,远程浏览器直接访问服务器 IP 失败是预期行为。此时应建立 SSH 隧道,而不是直接扩大监听地址。

如果已经采用私网 IP 模式,则按顺序检查:

  1. ss -lntp 是否监听在正确的私网 IP。
  2. 客户端是否位于允许的源网段。
  3. UFW 是否放行 8888。
  4. 云平台安全组是否放行相同的源网段。
  5. Jupyter 日志中是否有 Host 或认证错误。

八、验收与回滚检查项

验收检查

首次部署完成后,建议逐项确认:

  • [ ] jupyter notebook --version 能正常返回版本。
  • [ ] Jupyter 安装在 /home/jupyter/.venvs/notebook 虚拟环境中。
  • [ ] Notebook 进程由 jupyter 用户运行,而不是 root。
  • [ ] /home/jupyter/notebooks 是实际工作目录。
  • [ ] SSH 隧道模式下只监听 127.0.0.1:8888。
  • [ ] 私网模式下只监听指定私网 IP,并且防火墙仅允许指定来源网段。
  • [ ] 浏览器能够打开登录页。
  • [ ] 使用密码或令牌后能够进入 Notebook 文件列表。
  • [ ] 能创建并运行一个简单的测试 Notebook。
  • [ ] systemctl status jupyter.service 显示 active (running)。
  • [ ] systemctl is-enabled jupyter.service 返回 enabled。
  • [ ] 日志中没有重复崩溃、权限错误或端口冲突信息。

回滚检查

如果首次部署需要撤销,建议按以下顺序进行,避免误删 Notebook 数据:

  1. 停止并取消服务自启:
sudo systemctl disable --now jupyter.service
  1. 如果只是撤销 systemd 管理,保留虚拟环境和 Notebook 文件,仅移除服务单元。确认该文件确实是本次创建的服务后再执行:
sudo cp /etc/systemd/system/jupyter.service \
  /root/jupyter.service.backup.$(date +%Y%m%d%H%M%S)

sudo rm /etc/systemd/system/jupyter.service
sudo systemctl daemon-reload
  1. 如果需要恢复旧配置,从备份文件中选择正确版本,不要直接使用未确认的通配符:
ls -lt /home/jupyter/.jupyter/jupyter_server_config.py.bak.*
sudo cp /home/jupyter/.jupyter/jupyter_server_config.py.bak.备份时间 \
  /home/jupyter/.jupyter/jupyter_server_config.py
sudo chown jupyter:jupyter /home/jupyter/.jupyter/jupyter_server_config.py
sudo chmod 600 /home/jupyter/.jupyter/jupyter_server_config.py
  1. 如果曾经开放私网防火墙规则,删除对应的 8888 规则,并同步撤销云平台安全组中的规则:
sudo ufw status numbered
sudo ufw delete allow from 10.20.0.0/16 to any port 8888 proto tcp
  1. 不要把 deluser --remove-home jupyter 作为普通回滚动作。该操作可能删除 /home/jupyter/notebooks 中的文件,只有在完成数据备份、确认不再需要该用户及其目录后,才应单独评估。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5933.html

相关推荐