Databricks 远程开发

Important

远程开发处于 Beta 阶段。

Databricks 远程开发允许您通过 SSH 隧道从 IDE 访问您的工作区，并在 Databricks 计算环境中交互式地运行工作负载。设置简单，无需环境管理，并在 Databricks 工作区内保护所有代码和数据。

Requirements

若要使用远程开发连接到 Databricks 无服务器或经典计算环境，您必须具备：

在本地计算机上安装 Databricks CLI 1.5.0 或更高版本，并配置了身份验证。请参阅安装或更新 Databricks CLI。
以下任一：
- Visual Studio Code 版本为 1.110.0（通用版）或更高版本，且已安装 Remote - SSH extension（1.0.46+）。
- 游标版本：2.6.11（通用）或更高版本。

若要连接到无服务器 GPU 计算，必须启用 AI 运行时功能。请参阅 AI 运行时。

连接到经典（专用、单用户）计算资源：

计算必须运行 Databricks Runtime 17.0 或更高版本。请参阅专用计算概述。
必须启用 Unity Catalog。
如果计算策略存在，则它不得禁止执行作业。
使用自定义容器时，它必须已安装 openssh-server 。

连接至无服务器计算

若要连接到无服务器计算，请从 IDE 中的终端运行 databricks ssh connect 命令。不需要单独的安装步骤。

有关命令的详细信息 databricks ssh connect ，请参阅 ssh 命令组。

databricks ssh connect

使用 --accelerator 选项连接到 AI 运行时：

databricks ssh connect --accelerator=GPU_1xA10

连接后，完成开发环境的设置。参见开放项目。

若要连接到无服务器计算并在 Visual Studio Code 或 Cursor 中启动会话，请使用--ide此选项。 CLI 将打开指向主工作区文件夹的 IDE 窗口。

databricks ssh connect --ide=vscode

连接到经典计算

若要连接到经典计算，请先设置 SSH 连接，然后使用 IDE 或终端进行连接。

设置 SSH 连接

注释

仅当连接到经典计算时，才需要设置 SSH 连接。

首先，使用 databricks ssh 安装命令设置 SSH 隧道。为该连接提供一个名称，例如将 <connection-name> 替换为 my-connection：

databricks ssh setup --name <connection-name>

CLI 会提示你选择群集。您还可以直接使用 --cluster <cluster-id> 指定一个。

databricks ssh setup --name <connection-name> --cluster <cluster-id>

注释

对于 IntelliJ 用户，Databricks 建议将 --auto-start-cluster=false 添加到安装命令中，并在连接之前手动启动群集。这是因为 JetBrains IDE 在启动时会启动所有已配置的集群，这可能会导致意外的计算费用。

使用 Visual Studio Code 或 Cursor 进行连接

对于 Visual Studio Code，请安装远程 SSH 扩展。游标默认包含远程 SSH 扩展。
在 IDE 主菜单中，单击“ 查看>命令面板”。选择 “远程 SSH：设置”。或者，选择 “首选项：打开用户设置”（JSON） 以直接修改 settings.json 。
在 Remote.SSH: Default Extensions（或 remote.SSH.defaultExtensions 在 settings.json 中）下，添加 ms-Python.Python 和 ms-toolsai.jupyter。

如果要修改 settings.json：
```
"remote.SSH.defaultExtensions": [
    "ms-Python.Python",
    "ms-toolsai.jupyter"
]
```
注释

（可选）增加 Remote.SSH: Connect Timeout 的值（或者在 remote.SSH.connectTimeout 中增加 settings.json），以进一步降低超时错误的可能性。默认超时为 360。
在命令面板中，选择 “远程 SSH：连接到主机”。
从下拉菜单中，选择在第一步中设置的连接。 IDE 将继续在新窗口中进行连接。

使用 IntelliJ IDE 进行连接

按照远程服务器教程进行设置。
在新连接屏幕上，输入：
- 用户名： root
- 主机： <connection-name>

使用终端进行连接

ssh <connection-name>

打开项目

默认情况下，该 databricks ssh connect 命令将打开到临时目录。若要访问工作区文件，请从 IDE 或终端导航到工作区目录：

在Visual Studio Code或光标中，从命令面板（Cmd/Ctrl+Shift+P）中选择“打开文件夹”并导航到/Workspace/Users/<your-username>。
在终端窗口中，更改目录： cd /Workspace/Users/<your-username>

注释

群集重启后，/Workspace、/Volumes 和 /dbfs 中的文件会持久存留。重启时，位于/home、/root以及其他本地路径中的文件是临时性的，会丢失。

运行代码（Visual Studio Code或Cursor）

若要使用远程开发运行代码，必须设置 Databricks 虚拟环境。该环境包含所有内置的 DBR 库和计算范围库。

打开命令面板（Cmd/Ctrl+Shift+P），然后选择Python：选择解释器。
pythonEnv-xxx从列表中选择虚拟环境。如果未显示：
1. 从 IDE 中的终端运行 echo $DATABRICKS_VIRTUAL_ENV 。
  
  示例输出： /local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python
2. 在 Python: 选择解释器 提示中，将完整输出粘贴为解释器路径。
打开新的终端，虚拟环境应会自动激活。
若要运行 Jupyter 笔记本，请确保将虚拟环境选为内核。单击笔记本右上角的 “选择内核 ”。

使用标准 Python 扩展和 .ipynb Jupyter 扩展运行和调试 Python 文件和笔记本文件。

若要在无服务器计算的Python文件中使用 Spark，请显式初始化会话：

from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.serverless().profile("DEFAULT").getOrCreate()

管理 Python 依赖项

使用笔记本在群集级别全局管理Python依赖项或限定为单个项目。

群集库（建议）

请通过工作区 UI 中的 计算 > 库 安装依赖项。这些依赖项在集群重启后仍会保留，并可在 pythonEnv-xxx 中使用。请参阅群集库。

项目特定的笔记本设置

对于项目范围的依赖项，请在每个会话开始时运行包含 %pip install 命令的笔记本：

# Install from pyproject.toml
%pip install .

# Install from a requirements file
%pip install -r requirements.txt

# Install a wheel from Volumes or Workspace
%pip install /Volumes/catalog/schema/volume/your_library.whl

%pip 命令包括特定于 Databricks 的防护措施，并将依赖项传播到 Spark 执行程序节点。这将启用具有自定义依赖项的用户定义函数（UDF）。

有关更多示例，请参阅使用 %pip 命令管理库。

如果会话在 10 分钟内重新连接，则无需重新运行笔记本。可以使用 SSH 配置中的 -shutdown-delay 来进行配置。

注释

同一群集上的多个 SSH 会话共享一个虚拟环境。

局限性

Databricks 远程开发具有以下限制：

不支持共享群集。
用于Visual Studio Code和远程开发的 Databricks 扩展尚不兼容，不应一起使用。
在/Workspace、/Volumes和/dbfs之外编辑的文件将在群集重启时丢失。
每个群集最多允许 10 个 SSH 连接。
处于非活动状态的会话可能会在 1 小时后断开。
不能从其他远程环境或 Docker 容器使用远程开发。
当同时打开三个或多个 Jupyter 笔记本时，可能会遇到性能或连接问题。将来的版本中将解决此限制。

Databricks 笔记本的不同之处

使用远程开发时笔记本存在一些差异：

Python 文件不定义任何 Databricks 全局文件（如 spark 或 dbutils）。您必须通过 from databricks.sdk.runtime import spark 显式导入它们。
对于 ipynb 笔记本，可以使用这些功能：
- Databricks 全局变量：display、displayHTML、dbutils、table、sql、udf、getArgument、sc、sqlContext、spark
- %sql 用于执行 SQL 单元格的魔术命令

要处理 Python 源代码“笔记本”：

搜索jupyter.interactiveWindow.cellMarker.codeRegex，并将其设置为：

^# COMMAND ----------|^# Databricks notebook source|^(#\\s*%%|#\\s*\\<codecell\\>|#\\s*In\\[\\d*?\\]|#\\s*In\\[ \\])

搜索jupyter.interactiveWindow.cellMarker.default，并将其设置为：
```
# COMMAND ----------
```

故障排除

本部分包含有关解决常见问题的信息。

SSH 连接失败或超时

验证群集是否在工作区 UI 中运行。
检查外发端口 22 是否已打开，并确保它在您的笔记本电脑、网络和 VPN 上是被允许的。
延长 SSH 超时期限。请参阅使用 Visual Studio Code 或 Cursor 进行连接。
对于密钥不匹配错误，请删除 ~/.databricks/ssh-tunnel-keys 并重新运行 databricks ssh setup。
对于“远程主机标识已更改”错误，请检查 ~/.ssh/known_hosts 文件并删除与群集相关的条目。
在 1 小时后，SSH 会话可能会断开，并且无法与单个群集建立超过 10 个 SSH 连接。请参阅限制。

找不到 `code` 命令

如果看到 Error: exec: "code": executable file not found in $PATH，请打开命令面板（Cmd/Ctrl+Shift+P），选择 Shell 命令：在 PATH 中安装“code”命令，然后重启 IDE 或终端会话。

CLI 身份验证错误

使用databricks auth login确认 Databricks CLI 配置文件是否有效。
确认你对群集具有 CAN MANAGE 权限。

我的代码不起作用

请确保你已设置 Databricks 虚拟环境，参见运行代码（Visual Studio Code 或 Cursor）
IPYNB 笔记本和 *.py Databricks 笔记本有权访问 Databricks 全局版，但 Python *.py 文件不具有访问权限。请参阅 Databricks Notebook 的差异之处。

群集重启后文件消失或环境重置

在 /Workspace、/Volumes 和 /dbfs 装载中的文件在群集重启后将保持存在。重启时，位于/home、/root以及其他本地路径中的文件是临时性的，会丢失。
对持久性依赖项使用群集库管理。根据需要使用 init 脚本自动重新安装。请参阅什么是 init 脚本？。

SSH 设置在 Windows （WSL）上失败

直接在 Windows 上运行 databricks ssh setup，而不是在 WSL 中运行。 Windows Visual Studio Code实例找不到在 WSL 端创建的 SSH 配置。

FAQ

远程开发与 Databricks Connect 有何不同？

Databricks Connect 允许使用 Spark API 编写代码，并在 Databricks 计算中远程运行代码，而不是在本地 Spark 会话中运行这些代码。 Databricks Visual Studio Code 扩展通过 Databricks Connect 提供在 Databricks 上对用户代码的内置调试功能。

通过远程开发，可以从 IDE 访问工作区，并将整个开发环境移到计算中， Python、内核和所有执行在 Databricks 上运行，并且具有对计算资源的完全访问权限。

我的代码和数据如何受到保护？

所有代码都在您的 Databricks 云 VPC 中运行。没有任何数据或代码离开安全环境。 SSH 流量已完全加密。

支持哪些 IDE？

正式支持 Visual Studio Code 和 Cursor。任何具有 SSH 功能的 IDE 都兼容，但仅测试 VS Code 和 Cursor。

IDE 中是否提供了所有 Databricks 笔记本功能？

某些功能，例如 display()、dbutils 和 %sql，在使用时受到限制或需要手动设置。请参阅 Databricks Notebook 的差异之处。

使用 SSH 隧道进行连接时，群集是否会自动启动？

是的，但如果启动群集的时间比连接超时时间长，则连接尝试将失败。若要防止这种情况，请从命令面板（或 in remote.SSH.connectTimeout）中增加settings.json的值，以进一步降低发生超时错误的可能性。

如何知道我的群集是否正在运行？

导航到 Databricks 工作区 UI 中的 “计算 ”，并检查群集的状态。群集必须显示正在运行，SSH 连接才能正常工作。

如何断开 SSH/IDE 会话的连接？

可以通过关闭 IDE 窗口、使用 IDE 中的 “断开连接 ”选项、关闭 SSH 终端或在终端中运行 exit 命令来断开会话连接。

当我不工作时，如何停止集群并避免产生费用？

若要立即停止，请从工作区 UI 终止群集。导航到 Databricks 工作区 UI 中的 “计算 ”，找到群集，然后单击“ 终止 ”或“ 停止”。

从工作区 UI 将简短的自动终止策略设置在群集上。断开连接后，SSH 服务器会等待 shutdown-delay 的时间段（默认值：10 分钟），随后应用集群的空闲超时设置。

应如何处理持久性依赖项？

群集重启后，会话期间安装的依赖项会丢失。对要求和设置脚本使用永久性存储（/Workspace/Users/<your-username>）。使用群集库或 init 脚本进行自动化。

支持哪些身份验证方法？

身份验证使用 Databricks CLI 和您的 ~/.databrickscfg 配置文件。 SSH 密钥由 Databricks 远程开发处理。

是否可以从群集连接到外部数据库或服务？

是的，只要群集网络允许出站连接，并且你拥有必要的库。

是否可以使用其他 IDE 扩展？

大多数扩展在远程 SSH 会话中安装时都起作用，具体取决于 IDE 和群集。默认情况下，Visual Studio Code 不会在远程主机上安装本地扩展。可以通过打开扩展面板并在远程主机上启用本地扩展来手动安装它们。还可以将 Visual Studio Code 配置为始终远程安装某些扩展。请参阅 “连接到 Databricks”。

远程开发是否支持专用链接？

是的，但工作区管理员必须将 Visual Studio Code 和 Cursor 扩展市场中的 URL 加入允许列表。本地计算机还必须能够访问 Internet。

反馈

此页面是否有帮助？

Last updated on 2026-06-23