Databricks SSH 隧道

這很重要

Databricks 的 SSH 隧道目前仍處於測試階段。

Databricks 的 SSH 隧道允許你將 IDE 連接到 Databricks 運算。它設定簡單，能在叢集上互動式執行與除錯程式碼，減少環境不匹配，並確保您的 Databricks 工作空間內所有程式碼與資料安全。

需求

要使用 SSH 隧道，您必須具備：

Databricks CLI 版本 0.269 或更高，安裝在你的本地機器並已設定好認證。請參見安裝。
在你的 Databricks 工作空間中以專用（單一使用者）存取模式進行運算。請參閱專用運算概觀。
- 運算必須使用 Databricks Runtime 17.0 及以上版本。
- 必須啟用 Unity 目錄。
- 如果有計算政策存在，就不能禁止工作執行。

建立 SSH 隧道

首先，使用 databricks 的 ssh setup 指令設定 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 或游標連接

對於 Visual Studio Code，安裝 Remote SSH 擴充功能。游標包含遠端 SSH 擴充功能。
在 IDE 主選單中，點選 「檢視>指令面板」。選擇 遠端-SSH：設定。或者，選擇 偏好設定：開啟使用者設定（JSON） 直接修改 settings.json 。
在 Remote.SSH：預設擴充功能（或 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 in 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 擴充功能可以自動偵測虛擬環境，但你仍然需要手動啟用正確的虛擬環境。 從指令面板中選擇 Interpreter 指令，並選擇環境 pythonEnv-xxx。這可以存取所有內建的 Databricks 執行時函式庫，或你在全球叢集上安裝的任何東西。
在某些情況下，Python 擴充功能無法自動偵測虛擬環境（），venv例如當你打開無法辨識為 Python 專案的資料夾時。要解決這個問題，打開終端機並執行 echo $DATABRICKS_VIRTUAL_ENV，然後複製路徑，並在 Python 的「選擇解譯器 」指令中使用。

選擇 venv 後，可以透過 Python 或 Jupyter 擴充套件正常執行或除錯 Python 檔案或筆記本。

管理 Python 套件

安裝所需依賴最簡單的方式是使用工作區的 UI。請參閱計算範疇庫。採用此方法，您可以為叢集全域安裝所需的依賴項。你不需要每次叢集重啟都重新安裝函式庫。

然而，若要針對特定專案進行程式化設置，則可使用筆記本範圍內的安裝。

專案專用設定筆記本

要管理特定專案的相依性：

在你的專案中建立一個 setup.ipynb 檔案。
ssh CLI 建立一個 Python 環境（pythonEnv-xxx），該環境已內建 Databricks 執行時函式庫或 Compute-scoped 函式庫。把筆記本綁在這個 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 session 時，都執行此筆記本程式。如果現有的 ssh 會話在 10 分鐘內被中斷並重新連接到叢集，你不需要重新安裝其依賴項。（時間可透過本地 SSH 設定中的 -shutdown-delay=10m 選項進行配置。）

備註

如果你有多個 ssh 會話同時連接到同一個叢集，它們會使用相同的虛擬環境。

局限性

Databricks SSH 隧道有以下限制：

Visual Studio Code 的 Databricks 擴充功能與 Databricks 的 SSH 隧道尚未相容，不應同時使用。
你在工作空間中透過 Databricks 工作區介面建立的任何 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 全域變數：displaydisplayHTMLdbutilstablesqludfgetArgumentscsqlContextspark
- %sql magic 命令用來執行 SQL 程式碼區塊

要使用 Python 原始碼「筆記本」：

搜尋 jupyter.interactiveWindow.cellMarker.codeRegex 並將其設定為：

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

搜尋 jupyter.interactiveWindow.cellMarker.default 並將其設定為：
```
# COMMAND ----------
```

故障排除

本節包含解決常見問題的相關資訊。

SSH 連線失敗或逾時

確保你的叢集是在 Databricks UI 中執行，而不是突然停止或啟動。
檢查你的筆電/網路/VPN 是否開放並允許外撥 22 埠。
在你的 IDE 中延長 SSH 連線超時時間。請參見使用 Visual Studio Code 或游標連接。
如果你看到公鑰或私鑰不符，試著刪除該 ~/.databricks/ssh-tunnel-keys 資料夾。
如果你看到「遠端主機識別已更改」錯誤，請檢查檔案 ~/.ssh/known_hosts 並刪除與叢集相關的條目。
如果 SSH 會話在 1 小時後中斷，這是已知的限制。請參閱限制。
單一叢集最多允許 10 個 SSH 連線。

CLI 認證錯誤

確認你的 Databricks CLI 設定檔有效且已認證（databricks auth login）。
確保你有適當的叢集權限，例如 CAN MANAGE。

叢集重啟後檔案消失或環境重置

只有 /Workspace、/Volumes 和 /dbfs mount 是持久的。重新啟動後，所有資料 /home、 /root等都會被刪除。
使用叢集函式庫管理來處理持久相依。如果需要，可以用 init 腳本自動化重裝。請參閱什麼是 init 指令碼？。

「不是 git 儲存庫」錯誤或 IDE 缺少 git 功能

Git 只有在你透過終端機克隆到 /Workspace/Users/<your-username> 時才有效。網路建立的資料夾沒有 .git 的元資料。請參考「我如何使用 Git 搭配 SSH 隧道？」。

我的程式碼不行

務必選擇能存取所有 Databricks 執行時相依關係的 Python 直譯器。
- 如果你開啟 Python 專案，Python 擴充功能可以自動偵測虛擬環境，但你仍然需要手動啟用正確的虛擬環境。執行 Python：選擇直譯器 指令，並選擇 pythonEnv-xxx 環境。它能存取所有內建的 Databricks 執行時函式庫，或你在全球叢集上安裝的任何東西。
- 在某些情況下，Python 擴充功能無法自動偵測虛擬環境，例如當你打開無法辨識為 Python 專案的資料夾時。你可以打開終端機並執行 echo $DATABRICKS_VIRTUAL_ENV，然後複製路徑，並在 Python 的「選擇直譯器 」指令中使用。
IPYNB 筆記本和 *.py Databricks 筆記本可以存取 Databricks 的全域檔案，但 Python *.py 檔案沒有。請參考 Databricks Notebooks 的差異。

無法在 Windows 的 WSL 下設定 ssh 連線

Databricks 建議直接在 Windows 上執行 SSH 設定。如果你在 WSL 端設定，但用 Windows 版的 Visual Studio Code，它就找不到必要的 ssh 設定。

FAQ

我的程式碼和資料是如何被保護的？

所有程式碼都運行在您的 Databricks 雲端虛擬私人雲（VPC）中。沒有任何資料或程式碼會離開你的安全環境。 SSH 流量是完全加密的。

支援哪些 IDE？

Visual Studio Code 與游標是官方支援的，但 Databricks 的 SSH 隧道與任何具備 SSH 功能的 IDE 相容。

所有 Databricks 筆記本功能都能從 IDE 中取得嗎？

部分功能 display()如、 dbutils、 %sql 可使用，但有限制或手動設定。請參考 Databricks Notebooks 的差異。

多個使用者可以同時在同一叢集上開發嗎？

否。

當我透過 SSH 隧道連接時，叢集會自動啟動嗎？

是的，但如果啟動叢集的時間比連線逾時還久，連線嘗試就會失敗。

我怎麼知道我的叢集是否在運作？

在 Databricks 工作區介面中進入 計算區 ，查看叢集狀態。叢集必須顯示 Running，SSH 隧道連線才可以正常運作。

我該如何斷開我的 SSH/IDE 會話？

你可以關閉 IDE 視窗、使用 IDE 中的斷線 選項、關閉 SSH 終端機，或在終端機執行 exit 指令來斷開連線。

斷開 SSH 會自動停止我的叢集嗎？

不，ssh 伺服器有可設定的關機延遲，並且會在背景持續運行指定時間（預設為 10 公尺，可在 ssh 設定的 ProxyCommand 中修改 -shutdown-delay 選項來更改）。在逾時結束後，伺服器會被終止，這會啟動叢集的閒置逾時（這是在你建立叢集時設定的）。

我該如何關閉集群，以避免不必要的費用？

在 Databricks 工作區介面中進入計算，找到你的叢集，然後選擇終止或停止。

我該如何處理持續存在的依賴關係？

在工作階段中安裝的相依關係在叢集重新啟動後就會消失。需求和設定腳本使用持久儲存（/Workspace/Users/<your-username>）來處理。使用叢集函式庫或初始化腳本來自動化。

支援哪些認證方法？

認證則使用 Databricks 的 CLI 和你的 ~/.databrickscfg profiles 檔案。 SSH 金鑰由 Databrick 的 SSH 隧道處理。

我可以連接到叢集中的外部資料庫或服務嗎？

可以，只要你的叢集網路允許外接連線，且你有必要的函式庫。

我可以使用額外的 IDE 擴充功能嗎？

大多數擴充功能安裝在遠端 SSH 會話中即可運作，視你的 IDE 和叢集而定。 Visual Studio Code 預設不會在遠端主機上安裝本地擴充功能。你可以手動安裝，方法是打開擴充功能面板，並在遠端主機啟用本地擴充功能。你也可以設定 Visual Studio Code 讓某些擴充功能總是遠端安裝。請參見 Connect to Databricks。

我該如何使用 Git 搭配 SSH 隧道？

目前使用 Databricks 工作空間介面建立的 Git 資料夾在 IDE 中不會被識別為 git 倉庫。為了解決這個問題，請在 SSH 會話中使用 git CLI 將儲存庫克隆到你的持久工作區資料夾中：

打開終端機並導覽到想要的父目錄（例如， cd /Workspace/Users/<your-username>）
在那個目錄裡複製你的儲存庫。
在 Visual Studio Code 中，透過執行 code <repo-name> 新視窗開啟此資料夾，或使用 UI 在新視窗中開啟該資料夾。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-16