Databricks SSH 隧道

重要

Databricks SSH 隧道处于 Beta 阶段。

Databricks SSH 隧道允许将 IDE 连接到 Databricks 计算。设置起来非常简单，使你可以在群集上以交互方式运行和调试代码，减少环境不匹配，并使 Databricks 工作区中的所有代码和数据都安全。

要求

若要使用 SSH 隧道，必须具备：

在本地计算机上安装 Databricks CLI 0.269 或更高版本，并配置了身份验证。请参阅 “安装”。
使用专用（单用户）访问模式在 Databricks 工作区中计算。请参阅专用计算概述。
- 计算必须使用 Databricks Runtime 17.0 及更高版本。
- 必须启用 Unity Catalog。
- 如果计算策略存在，则它不得禁止执行作业。

设置 SSH 隧道

首先，使用 databricks ssh 安装命令设置 SSH 隧道。将 <connection-name> 替换为隧道的名称，例如 my-tunnel。

databricks ssh setup --name <connection-name>

CLI 会提示你选择群集，也可以通过传递 --cluster <cluster-id>来提供群集 ID。

注释

对于 IntelliJ，Databricks 建议您在安装命令中包含 –-auto-start-cluster=false。启动 JetBrains IDE 会自动启动所有群集，这可能会导致意外的计算成本。如果设置此选项，则必须在工作区中启动群集才能启动 SSH 隧道。

连接到 Databricks

接下来，使用 IDE 或终端连接到 Databricks。

使用 Visual Studio Code 或 Cursor 进行连接

对于 Visual Studio Code，请安装远程 SSH 扩展。游标包括远程 SSH 扩展。
在 IDE 主菜单中，单击“ 查看>命令面板”。选择 “远程 SSH：设置”。或者，选择 “首选项：打开用户设置”（JSON） 以直接修改 settings.json 。
在 Remote.SSH: 默认扩展（或者在 remote.SSH.defaultExtensionssettings.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 将继续在新窗口中进行连接。

注释

如果计算未运行，它将启动。但是，如果计算启动的超时时间长，SSH 连接尝试将失败。
出现服务器类型提示时选择 linux 。

使用 IntelliJ IDE 进行连接

按照远程开发教程进行设置。
在新连接屏幕上，输入以下内容：

用户名： root主机：<connection-name>

使用终端进行连接

若要从命令行连接到 Databricks，请提供连接名称，例如：ssh。

ssh my-tunnel

打开项目

初始连接将打开一个空的 IDE 窗口，无需打开任何文件夹。在 Visual Studio Code 中，使用命令面板中的“打开文件夹”命令打开所需项目。
将工作区装载（/Workspace/Users/<your-username>）用作持久存储。

运行代码（Visual Studio Code）

如果打开 Python 项目，Python 扩展可以自动检测虚拟环境，但仍需要手动激活正确的环境。从命令面板中选择解释器命令，然后选择环境pythonEnv-xxx。此功能能够访问所有内置的 Databricks Runtime 库，或群集上你已全局安装的任何库。
在某些情况下，Python 扩展无法自动检测虚拟环境（venv例如，打开无法识别为 Python 项目的文件夹时）。若要解决此问题，请打开终端并执行 echo $DATABRICKS_VIRTUAL_ENV，然后复制路径并将其用在 Python：选择解释器 命令中。

选择 venv 后，可以使用 Python 或 Jupyter 扩展提供的正常运行或调试操作来执行 Python 文件或笔记本文件。

管理 Python 依赖项

安装所需依赖项的最简单方法是使用工作区 UI。请参阅计算范围的库。使用此方法，可以全局安装群集的依赖项。每次重启群集时，无需重新安装库。

但是，对于作用域为特定项目的更编程设置，请使用笔记本范围的安装。

项目特定的设置文档

若要管理特定项目的依赖项，请执行以下步骤：

在项目中创建 setup.ipynb 文件。
ssh CLI 将创建一个 Python 环境（pythonEnv-xxx），该环境已具有内置的 Databricks Runtime 库或计算作用域的库。将笔记本附加到此 pythonEnv-xxx 环境。
使用 %pip install 命令安装依赖项：
- %pip install . 如果你有 pyproject.toml （%pip install .<group> 来缩小范围）
- %pip install -r dependencies.txt 如果有 dependencies.txt
- %pip install /Volumes/your/wheel.whl （或 /Workspace 路径）如果生成并上传自定义库作为滚轮
%pip 命令具有 Databricks 特定的逻辑和附加的保护措施。该逻辑还确保所有 Spark 执行器节点而不仅仅是您连接的驱动节点都可以使用这些依赖项。这将启用具有自定义依赖项的用户定义函数（UDF）。

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

每次建立新的 ssh 会话时运行此笔记本。如果删除现有 ssh 会话并在 10 分钟内重新连接到群集，则无需重新安装依赖项。本地 ssh 配置中的-shutdown-delay=10m选项可以设置时间。

注释

如果有多个 SSH 会话同时连接到同一群集，则它们使用相同的虚拟环境。

局限性

Databricks SSH 隧道具有以下限制：

Visual Studio Code 和 Databricks SSH 隧道的 Databricks 扩展尚不兼容，不应一起使用。
通过 Databricks 工作区 UI 在工作区中创建的任何 Git 文件夹都不会通过 git CLI 和 IDE git 集成识别为 git 存储库，因为这些文件夹缺少 .git 元数据。若要解决此问题，请参阅如何将 Git 与 SSH 隧道配合使用？。
您连接到的群集上的home目录挂载和root目录挂载是短暂的。重启群集时，不会保留群集上的任何内容。

Databricks 笔记本的不同之处

在使用 SSH 隧道时，笔记本会存在一些差异：

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 源代码“notebooks”，请按以下步骤进行：

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

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

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

Troubleshooting

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

SSH 连接失败或超时

确保群集在 Databricks UI 中运行，而不仅仅是停止或启动。
请检查是否已打开并允许在您的笔记本电脑/网络/VPN上使用出站端口22。
增加 IDE 中的 SSH 连接超时。请参阅使用 Visual Studio Code 或 Cursor 进行连接。
如果看到公钥或私钥不匹配错误，请尝试删除文件夹 ~/.databricks/ssh-tunnel-keys 。
如果看到“远程主机标识已更改”错误，请检查 ~/.ssh/known_hosts 该文件并删除与群集相关的条目。
如果在 1 小时后删除 SSH 会话，这是一个已知的限制。请参阅限制。
允许连接到单个群集的 SSH 连接不超过 10 个。

CLI 身份验证错误

确认 Databricks CLI 配置文件有效且已经过身份验证（databricks auth login）。
请确保具有适当的群集权限，例如 CAN MANAGE。

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

只有 /Workspace、/Volumes 和 /dbfs 挂载是永久性的。重启后，会擦除所有数据/home/root，等等。
对持久性依赖项使用群集库管理。根据需要使用 init 脚本自动重新安装。请参阅什么是 init 脚本？。

IDE 中出现“不是 git 存储库”错误或缺少 git 功能

只有使用终端克隆到 /Workspace/Users/<your-username> 时，Git 才有效。 Web 创建的文件夹没有 .git 元数据。请参阅如何将 Git 与 SSH 隧道配合使用？

我的代码不起作用

请确保选择有权访问所有 Databricks Runtime 依赖项的正确 Python 解释器。
- 如果打开 Python 项目，Python 扩展可以自动检测虚拟环境，但仍需要手动激活正确的环境。执行 Python：选择解释器 命令，然后选择 pythonEnv-xxx 环境。它将有权访问所有内置 Databricks Runtime 库，或者群集上全局安装的任何库。
- 在某些情况下，Python 扩展无法自动检测虚拟环境，例如打开无法识别为 Python 项目的文件夹时。可以打开终端并执行 echo $DATABRICKS_VIRTUAL_ENV，然后复制路径并在 Python：选择解释器 命令中使用。
IPYNB 笔记本和 *.py Databricks 笔记本有权访问 Databricks 全局版，但 Python *.py 文件不具有访问权限。请参阅 Databricks Notebook 的差异之处。

无法在 WSL 下的 Windows 上设置 ssh 连接

Databricks 建议直接在 Windows 上执行 ssh 设置。如果在 WSL 端进行了设置，但接着使用 Windows 版本的 Visual Studio Code，那么将无法找到必要的 ssh 配置。

FAQ

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

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

支持哪些 IDE？

正式支持 Visual Studio Code 和 Cursor，但 Databricks SSH 隧道与具有 SSH 功能的任何 IDE 兼容。

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

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

多个用户是否可以同时在同一群集上进行开发？

否。

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

是的，但如果启动群集的时间比连接超时时间长，则连接尝试将失败。

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

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

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

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

断开连接 SSH 是否会自动停止群集？

否，ssh 服务器具有可配置的关闭延迟，并且它将在后台继续运行指定的时间（默认情况下为 10 米，可以通过修改 -shutdown-delay 选项在 ssh 配置 ProxyCommand 中进行更改）。超时后，服务器将终止，这会启动群集空闲超时（在群集创建期间配置）。

如何关闭群集以避免不必要的费用？

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

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

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

支持哪些身份验证方法？

身份验证使用 Databricks CLI 和 ~/.databrickscfg 配置文件文件。 SSH 密钥由 Databrick SSH 隧道处理。

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

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

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

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

如何将 Git 与 SSH 隧道配合使用？

目前，使用 Databricks 工作区 UI 创建的 Git 文件夹在 IDE 中无法识别为 git 存储库。若要解决此问题，请使用 GIT CLI 将存储库从 SSH 会话克隆到永久性工作区文件夹：

打开终端并导航到所需的父目录（例如 cd /Workspace/Users/<your-username>）
将您的存储库克隆到该目录中。
在 Visual Studio Code 中，可以通过运行 code <repo-name> 在新窗口中打开此文件夹，也可以使用 UI 在新窗口中打开文件夹。

反馈

此页面是否有帮助？

Last updated on 2026-01-16