遠端開發與管理

本指南涵蓋兩個主題：將您的本地 VelaTerm 開放給其他裝置使用，以及連接到遠端機器以在該處開發與管理工作階段。

1. 兩個入口點，兩種方向

所有的遠端功能都位於標題列的右側（主題切換器旁）：

地球儀圖示代表 遠端存取（瀏覽器）——開放此機器，讓手機、平板電腦或其他電腦能透過瀏覽器使用您的 VelaTerm。箭頭圖示則是 連接到遠端伺服器——此機器作為用戶端，向外連線以在另一台機器上進行開發。當伺服器正在運作時，地球儀會顯示為綠色。

2. 開放此機器（遠端存取）

2.1 啟動伺服器

點擊地球儀，設定一個連接埠（預設為 8799——若已被佔用請改變），再設定一個存取密碼，然後按下「啟動伺服器」：

任何裝置要進入都必須使用此存取密碼。它僅在伺服器運作期間有效；停止運作後，下次需設定新的密碼。

2.2 連接裝置

一旦伺服器開始運作，面板會顯示狀態、憑證指紋以及自動生成的配對連結：

要進行連線：將 配對連結傳送給您自己的裝置（透過 AirDrop、自傳訊息等方式——任何可行的方式皆可），在瀏覽器中打開該連結，然後輸入存取密碼。該連結會攜帶經過加密的配對憑證；瀏覽器與機器之間的通訊是端對端加密的。有兩點需要注意：

• 該連結即為密鑰。請僅與您自己的裝置分享。如果您懷疑它已洩漏，請點擊「重新生成連結」——舊連結會立即失效，所有已連線的裝置都會斷開，直到它們使用新的連結為止。
• 首次連線時，瀏覽器會因為憑證未被信任而發出警告——這對自簽名的憑證而言是正常現象。請將瀏覽器顯示的指紋與面板中的「憑證指紋」進行比對；如果兩者相符，代表您正在與自己的機器通訊。

當存在多個網路介面（有線、Wi-Fi、VPN）時，面板會顯示預設的位址，其餘位址則會以「還有 1 個 URL」的形式呈現——請選擇與連線裝置在同一網路上的位址。

在手機上打開同一個連結時，會自動切換到行動版介面（兩層級的導航加上終端機鍵盤）——無需任何設定。

2.3 瀏覽器端的體驗

已連線裝置所看到的登入頁面與主要使用者介面：

瀏覽器用戶端會與桌面版共享相同的即時作業階段：相同的樹狀結構、相同的終端機輸出，雙方都能輸入文字，且雙方都能即時看到對方的操作。視窗排列方式（開啟的分頁、分割視窗）是依每個用戶端獨立決定的。

終端機的大小有「擁有者」的概念：當同一個作業階段在多個用戶端上開啟時，大小會隨著擁有者而改變，其他用戶端則會看到縮放後的鏡像，並伴隨一條「鏡像……點擊以調整此視窗大小」的列（如上圖中終端機的右上角）——點擊該列即可接管目前視窗的大小調整。

2.4 裝置管理

面板中的「已配對裝置」清單會顯示所有已連線的裝置：

若要封鎖某個裝置，請點擊其旁邊的「封鎖」並確認——該裝置會立即斷開連線且無法重新連線（需要新的配對連結）；其他裝置則不受影響。裝置名稱是由用戶端自行報告的——請將其視為標籤，而非真實身份。若要一次性將所有裝置都移除，請使用「重新生成連結」。

2.5 停止伺服器

在面板底部按下「停止伺服器」。瀏覽器用戶端會斷開連線；正在運作的作業階段則不受影響——它們屬於桌面應用程式本身。

3. 連接到遠端（連接到遠端伺服器）

點擊標題列中的連線按鈕，面板會提供 SSH 模式與 URL 模式兩種選項。

3.1 SSH 模式：遠端所需的一切就是 SSH

適用於沒有安裝 VelaTerm 相關組件的遠端開發機（通常為 Linux 或 macOS）。進行連線時會自動執行整個流程：偵測遠端作業系統與架構 → 下載相對應的 vela-server → 以持續執行過程的方式啟動它 → 設定本地的連接埠轉發 → 自動開啟遠端視窗並登入。

輸入 user@host[:port] 並按下「連線」。以下是值得了解的詳細資訊：

**首次連線時的主機金鑰驗證.**新的主機會顯示其 SSH 主機金鑰指紋供您驗證；請選擇「指紋相符，連線」並確認，如此該主機就會被記錄在 known_hosts 中——之後就不會再出現相關提示。如果已知主機的指紋發生變化，面板會變成紅色——在確認之前，請先查明原因（可能是作業系統重新安裝、使用的是不同機器，或是有人竄改了連結）。

**認證.**您現有的 SSH 設定（如 ssh-agent、~/.ssh/config、金鑰等）都會被透明地重複使用；只有在公鑰認證失敗時才會出現密碼輸入畫面。「記住密碼」會將密碼儲存在系統的金鑰串中（絕不儲存在資料庫中），下次再使用時會自動調用。

**資料模式：「使用遠端桌面應用程式的資料庫」。**若未勾選（預設值），遠端伺服器會使用一個獨立的資料目錄(~/.velaterm/data)，與該機器上安裝的任何VelaTerm桌面應用程式完全分離。若勾選，則會使用遠端桌面版本建置的資料庫——雙方都能看到相同的會話樹，這適用於「該機器日常運行VelaTerm，而我則遠端處理相同的專案」的情況。共享的是磁碟上的資料庫檔案，而非正在運行的程序（見§4.1）；建議兩端保持相同版本。

**最近使用的主機。**會列出您已連線過的主機；點擊某個主機僅會填入輸入欄位（不會自動連線）——請檢視後再點擊「連線」。鍵匙圖示表示已儲存密碼；×則表示忘記該主機（及其儲存的密碼）。

**連線進度。**首次連線時會傳輸伺服器二進位檔（數十MB）——按鈕會顯示「準備中」/「傳輸中」並附上百分比。重新連線時會重用遠端已有的伺服器，速度會快得多。

3.2 URL模式：對方已經開啟遠端存取

用於另一台機器的VelaTerm已開啟遠端存取功能（§2）且您擁有其配對連結的情況。與在一般瀏覽器中打開連結相比，此方式可提供專用視窗、由金鑰串支援的自動登入，以及由應用程式處理的指紋驗證。

貼上配對連結，輸入對方設定的存取密碼，然後點擊「連線」。首次連線時會驗證TLS憑證的指紋（與對方面板上顯示的憑證指紋進行比對）；之後，若指紋未變，則可直接連線。透過系統金鑰串儲存密碼的方式也是一樣。

4. 中斷連線、關閉以及剩餘內容

4.1 三層狀態機制

「斷線後資料是否仍存在」取決於您所詢問的層級：

前兩個層級本質上就是安全的。唯一需要考慮的層級是第三個：只要遠端伺服器程式仍在運行，您的正在運行的會話就會存在。

4.2 關閉窗口的含義

SSH 模式：此連線啟動了遠端伺服器且該伺服器屬於您，因此關閉窗口時會詢問要執行何種動作——「停止伺服器」會在遠端關閉它（從而結束其正在運行的會話）；「繼續運行」僅會切斷您這端的連線，但伺服器仍會保持運行狀態，如此下次連接到該電腦時，所有會話都會完整保留。希望您不在時代理程式仍持續運作？請選擇「繼續運行」。

URL 模式：您是正在那邊運行的程式的訪客。關閉您的視窗僅表示您離開；另一端會繼續運作，您回來時一切依然在原處。

4.3 中斷與重新連線

當網路出現問題時，遠端視窗的上方會出現紅色的重新連線條狀圖，並自動重試；正在運行的工作階段不受影響——在 SSH 模式下，遠端伺服器會與 SSH 工作階段分離（其設計上可承受網路中斷）。

需注意的一個限制：自動重新連線僅適用於從視窗到本機轉發端口的路徑。如果 SSH 隧道處理程序或遠端伺服器本身已停止運作，紅色條狀圖將永遠旋轉，重新連線功能也無法幫助——請回到主視窗並再次連線。連線流程會檢測遠端伺服器是否仍存活：若存活則會重複使用（工作階段保持不變）；只有當伺服器已停止運作時，才會啟動新的伺服器。

另外：遠端電腦進入睡眠狀態、登出或重新啟動，都會結束 SSH 模式下的伺服器及其正在運行的工作階段；由於工作階段資料儲存在磁碟上，因此不受影響。

4.4 快速參考

5. 安全模型概覽

密碼（SSH 帳戶密碼、遠端登入密碼）僅儲存在系統金鑰串中，絕不儲存在資料庫中，且僅在您明確同意時才會儲存。區域網路瀏覽器存取是透過具有自簽名憑證的 TLS 進行；配對連結會傳送端對端加密的憑證，且伺服器會拒絕未配對的明文連線。SSH 主機金鑰與遠端 TLS 憑證皆採用首次使用即信任的原則：已知且未改變的連線可直接通過；新的目標會出現一次驗證提示；若指紋改變則會出現紅色警告——請在確認前進行調查。個別裝置可隨時被阻擋（§2.4），且配對連結也可隨意重新生成。

還有一點：如果遠端視窗的標題列顯示紅色的「⚠ vX ≠ vY」標記，表示您的用戶端介面與遠端伺服器的版本不同——功能可能無法同步；請將兩端都升級到相同版本。

6. 常見問題解答

**已連線，但側邊欄仍為空白或紅色條狀圖一直旋轉？**最有可能是SSH通道或遠端伺服器已失效——在視窗內重新連線無法解決此問題（§4.3）。請返回主視窗並再次連線。

**端口 8799 無法啟動？**可能有其他程式佔用了該端口；請在面板中選擇其他端口並重新啟動。

**瀏覽器顯示無法信任此憑證？**這是自簽名憑證的常見現象——請驗證其指紋後繼續操作（§2.2）。若想跳過各瀏覽器的警告，可透過配對連結進入，應用程式會為您處理信任問題。

**希望在您離開時遠端代理仍能持續運作？**在SSH模式下，選擇「關閉視窗時仍持續運行」；會話將在遠端端持續進行。稍後重新連線即可從中斷處繼續。

**手機上的終端視窗看起來很小？**那是根據桌面主機自動調整大小的鏡像——請點擊終端視窗右上方的「點擊以適配此視窗」，即可由當前裝置主導大小調整。