在本地浏览器使用远程 JupyterLab：SSH 隧道、独立环境与内核管理

代码、数据和 Python 环境放在 Linux 服务器上，操作界面留在本地浏览器，这是远程使用 JupyterLab 很方便的一种方式。连接可以交给 SSH：JupyterLab 只监听服务器的回环地址，本地通过端口转发访问它。

本文以单人使用为例：远端端口用 8889，本地端口用 8887。服务器需要已有可登录的普通用户和 Python 3，本地需要 OpenSSH 客户端。多人共用工作环境应另行考虑 JupyterHub。

一、在服务器上创建独立环境

以下命令在远程服务器的普通用户终端执行：

python3 -m venv ~/venvs/jupyter
source ~/venvs/jupyter/bin/activate
python -m pip install --upgrade pip
python -m pip install jupyterlab ipykernel
mkdir -p ~/notebooks

Debian/Ubuntu 如果提示缺少 ensurepip，先安装对应 Python 版本的 venv 包；使用系统默认 Python 时通常是 sudo apt install python3-venv。不要为了绕过系统 Python 的包管理限制而直接使用 sudo pip install。

已有 conda 环境也可以安装 jupyterlab，关键是确认启动服务时用的是哪一个环境。JupyterLab 安装文档列出了 pip 和 conda 等安装方式。

二、只在回环地址启动 JupyterLab

仍在服务器上执行：

~/venvs/jupyter/bin/jupyter lab \
  --no-browser \
  --ip=127.0.0.1 \
  --port=8889 \
  --ServerApp.port_retries=0 \
  --ServerApp.root_dir="$HOME/notebooks"

port_retries=0 用来避免端口被占用时自动换到另一个端口，导致 SSH 隧道仍指向旧端口。root_dir 决定文件浏览器的起始目录。

终端会输出登录地址和 token。保留该终端，稍后登录需要用到 token。这里不需要设置 ip='*'、关闭身份验证或允许 root 启动；SSH 可以直接连接服务器自己的 127.0.0.1:8889。

如果更喜欢密码登录，在相同环境中执行：

~/venvs/jupyter/bin/jupyter server password

根据提示设置密码，再重启 JupyterLab。无需把示例密码哈希复制进配置文件。Jupyter Server 文档说明了本地监听与密码配置方式。

三、在本地建立 SSH 隧道

下面这条命令在自己的电脑上执行。把 [email protected] 换成实际 SSH 用户和地址：

ssh -N \
  -L 127.0.0.1:8887:127.0.0.1:8889 \
  -o ExitOnForwardFailure=yes \
  -o ServerAliveInterval=30 \
  -o ServerAliveCountMax=3 \
  [email protected]

Windows PowerShell 可以直接使用同一条命令的单行形式：

ssh -N -L 127.0.0.1:8887:127.0.0.1:8889 -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 [email protected]

连接关系是：

本地浏览器 → 本地 127.0.0.1:8887 → SSH → 服务器 127.0.0.1:8889

第一个 127.0.0.1 属于本地电脑，第二个属于 SSH 服务器。-N 表示不启动远程 shell，只保留转发。ExitOnForwardFailure 能发现本地监听端口等转发建立失败，但不会预先检查远端 Jupyter 是否已经启动。参数定义见 OpenSSH 手册。

保持隧道终端运行，在本地浏览器打开：

http://127.0.0.1:8887/lab

按页面提示输入远端 Jupyter 输出的 token，或刚设置的密码。不要直接照抄服务器输出的 :8889 地址到本地浏览器——本地入口是 :8887。

四、保留远程会话

断开普通 SSH 会话可能影响其中启动的进程。如果已经安装 tmux，可以在服务器上新建会话：

tmux new -s jupyter

在里面运行前面的 JupyterLab 启动命令，然后按 Ctrl+B，再按 D 分离会话。以后使用 tmux attach -t jupyter 返回。tmux 保留的是远程进程，本地的 SSH 隧道仍需保持连接。

五、给项目添加独立 Python 内核

JupyterLab 的运行环境和执行 Notebook 的内核环境可以不同。假设项目已有虚拟环境 ~/venvs/project-a，在服务器上执行：

~/venvs/project-a/bin/python -m pip install ipykernel
~/venvs/project-a/bin/python -m ipykernel install --user \
  --name project-a \
  --display-name "Python (project-a)"

刷新 JupyterLab 后选择 Python (project-a)。--name 是内核注册名称，--display-name 是界面名称。注册命令必须由目标环境的 Python 执行，具体机制见 IPython 内核安装说明。

查看和移除注册记录：

~/venvs/jupyter/bin/jupyter kernelspec list
~/venvs/jupyter/bin/jupyter kernelspec remove project-a

移除 kernelspec 不会删除对应的虚拟环境。

六、遇到问题先检查哪一层

只要分别确认远程进程、本地隧道和内核环境这三层，后续就可以在本地浏览器中维护远程项目，而无需单独开放 Jupyter 的公网端口。