在Linux服务器上首次部署Jupyter Notebook,如何启动并限制访问范围?
首次部署 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 模式,则按顺序检查:
ss -lntp是否监听在正确的私网 IP。- 客户端是否位于允许的源网段。
- UFW 是否放行 8888。
- 云平台安全组是否放行相同的源网段。
- 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 数据:
- 停止并取消服务自启:
sudo systemctl disable --now jupyter.service
- 如果只是撤销 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
- 如果需要恢复旧配置,从备份文件中选择正确版本,不要直接使用未确认的通配符:
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
- 如果曾经开放私网防火墙规则,删除对应的 8888 规则,并同步撤销云平台安全组中的规则:
sudo ufw status numbered
sudo ufw delete allow from 10.20.0.0/16 to any port 8888 proto tcp
- 不要把
deluser --remove-home jupyter作为普通回滚动作。该操作可能删除/home/jupyter/notebooks中的文件,只有在完成数据备份、确认不再需要该用户及其目录后,才应单独评估。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5933.html



