如何使用本地编辑器（如 Cursor）优雅地执行远程 Jupyter 服务器代码

你是否遇到过这样的场景：本地机器性能不足以运行复杂的机器学习模型，或者需要在特定的远程服务器环境（如拥有 GPU 或特殊库）中执行代码，但又想享受本地编辑器（如 VS Code 或 Cursor）的丝滑体验？本文将一步步教你如何配置，让你在本地舒适地编辑 .ipynb 文件，同时利用远程服务器的强大计算能力执行代码。

核心思路：远程执行，本地编辑 + SSH 隧道

我们的目标是：

1. 在远程服务器上运行 Jupyter 服务器，处理代码执行。
2. 在本地机器上运行 Cursor 编辑器，负责代码编写和界面展示。
3. 通过 SSH 隧道建立一条安全的加密通道，将本地编辑器的请求转发给远程服务器。

步骤一：在远程服务器上启动 Jupyter

1. 登录远程服务器:

   ssh 用户名@服务器IP地址
   

2. 安装 Jupyter: 如果尚未安装，确保在你的远程 Python 环境中安装了 Jupyter Notebook 或 JupyterLab 以及 ipykernel：

   pip install notebook ipykernel
   # 或者
   pip install jupyterlab ipykernel
   # 或者使用 conda
   conda install notebook ipykernel # 或 jupyterlab
   

3. 启动 Jupyter 服务器: 导航到你的工作目录，然后启动服务器，关键是使用 --no-browser 并且记下端口号：

   jupyter notebook --no-browser --port=8888
   # 或者使用 jupyter lab
   # jupyter lab --no-browser --port=8888
   

   • --no-browser: 阻止在服务器上自动打开浏览器。
   • --port=8888: 指定监听端口（如果 8888 被占用，选择其他端口）。
   • 注意: 如果你希望 Jupyter 监听来自其他机器的连接（通常不直接需要，因为我们用隧道），可以加 --ip=0.0.0.0，但通过隧道连接时，本地配置依然是访问 localhost。

4. 记录 Token 或设置密码: 服务器启动后会打印一个包含 Token 的 URL，类似 http://localhost:8888/?token=abcdef123...。复制这个完整的 URL。如果你之前设置了密码，则不需要 Token。

步骤二：建立 SSH 隧道（关键一步！）

为什么需要这一步？

远程服务器通常有防火墙保护，Jupyter 端口（如 8888）不会直接暴露给公网。即使端口开放，直接连接也缺乏安全加密。SSH 隧道就像一条安全的、加密的虚拟管道，它将你本地机器的某个端口（例如 8888）的访问请求，通过已建立的 SSH 连接安全地转发到远程服务器的对应端口。这是解决连接不上、特别是 WebSocket 错误（如 400 Bad Request）的关键。

在你的 本地机器 上打开一个新的终端窗口，运行以下命令：

ssh -NfL localhost:8888:localhost:8888 用户名@服务器IP地址

• -N: 不执行远程命令，只建立隧道。
• -f: 在后台运行。
• -L localhost:8888:localhost:8888: 将本地 localhost 的 8888 端口转发到远程 localhost 的 8888 端口。确保这里的端口号与远程 Jupyter 服务器使用的端口一致。
• 将 用户名 和 服务器IP地址 替换为你的实际信息。

验证隧道: 在本地浏览器访问 http://localhost:8888。如果能看到 Jupyter 界面（可能需要输入 Token 或密码），则隧道建立成功。

步骤三：在本地 Cursor 中配置连接

1. 打开命令面板: Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (macOS)。
2. 输入命令: Jupyter: Specify Jupyter server for connections。
3. 选择 "Existing"。
4. 输入服务器 URI:

   • 粘贴之前从远程服务器复制的包含 Token 的完整 URL，但将其中的 localhost 或远程服务器 IP 替换为 localhost（因为我们通过隧道访问本地端口）：

     http://localhost:8888/?token=abcdef123...
     

   • 如果你远程服务器设置了密码，则输入基础 URL：

     http://localhost:8888/
     

     之后 Cursor 会提示你输入密码。

步骤四：开始远程执行

1. 打开你的本地 .ipynb 文件。
2. 点击编辑器右上角的 "Select Kernel"。
3. 你应该能看到标有 http://localhost:8888/ 的远程服务器选项。展开它，选择你希望在远程服务器上使用的 Python 内核。
4. 现在，运行代码单元格！代码会被发送到远程服务器执行，结果将返回到你的本地 Cursor 界面。

重要注意事项

• 文件路径: 代码是在远程服务器上执行的。如果代码需要读取文件 (pd.read_csv('data.csv'))，那么 data.csv 必须存在于远程服务器上，并且路径相对于 Jupyter 服务器的启动目录或为绝对路径。代码无法直接访问你本地的文件。
• Python 环境: 代码使用的是远程服务器上的 Python 环境和库。确保所有必需的库都已在远程环境中安装。
• 资源: 代码将使用远程服务器的 CPU、内存、GPU 等资源。
• 停止: 完成工作后，记得在远程服务器终端按 Ctrl+C 停止 Jupyter 服务器，并结束本地的 SSH 隧道进程（例如使用 pkill -f "ssh -NfL localhost:8888"）。

通过这种方式，你可以完美结合本地编辑的便捷性和远程服务器的强大能力，高效地进行数据科学和机器学习工作。