SUMA 遠端 AI 橋接器 (SUMA Remote AI Bridge) 使用教學

跨平台 P2P 遠端 AI 模型安全連線與分享工具

SUMA 遠端 AI 橋接器（SUMA Remote AI Bridge）是一套高效、安全的跨平台 P2P 遠端 AI 模型連線與共享工具。透過 Tailcat / TSnet (WireGuard) 點對點加密通道技術，讓使用者在主機端執行本機 AI 模型（如 Ollama,llama.cpp,vLLM 等），並在客戶端電腦透過標準的本機 HTTP 埠號（如 http://127.0.0.1:18080/v1）直接調用遠端模型，無須繁瑣的路由器連接埠轉發或暴露公網 IP。由 域創數位工作室 (LOCALSOFT Digital Studio) 開發。

🌟 核心特性 (Key Features)

🛡️ 安全加密傳輸與隱私保護

• Tailcat P2P 連線：基於 WireGuard 核心的點對點加密通道，優先建立直接 UDP 直連；在對稱型 NAT 複雜網路環境下自動啟用 DERP 中繼備援。
• 裝置公鑰授權機制：基於 Ed25519 裝置公鑰指紋的雙向信任審核，支援白名單授權、待審核（Pending）提示、一鍵核准與拒絕撤銷。
• 信封加密機密保護：結合作業系統原生安全庫（Windows DPAPI、macOS Keychain、Linux Secret Service）與 AES-256-GCM，本機敏感設定絕不以明文留存。
• 邊界隔離與防護：本機 API 嚴格繫結 Loopback 回環位址（127.0.0.1），具備嚴格的 Origin 白名單驗證與 256-bit 動態 Session Token 認證。
• 日誌脫敏遮罩 (Log Masking)：核心日誌內建敏感資訊過濾，Token、金鑰與對話內容 Prompt 絕不落盤記錄。

💻 雙模式運作與 Linux CLI 無頭支援

• 雙向模式支援：單一實例可同時作為分享主機與連接客戶端，既可調用遠端算力，亦可對外分享本機特定模型。
• Linux 極簡 CLI 模式：專為 Linux 伺服器、Docker 容器與雲端 GPU 執行個體設計，極致輕量無頭運行，預設安靜日誌並支援即時串流輸出。
• 遠端管理員連線 (Remote Admin)：管理者可於 Windows 桌面端輸入 Linux 節點之 Admin Token，遠端視覺化監控節點狀態、即時調整上游埠號、審核裝置與讀取遠端串流日誌。

📦 下載與安裝 (Download &Installation)

本專案支援 Windows 桌面圖形版以及 Linux 伺服器/算力主機無頭 CLI 版。你可以直接由 GitHub Releases 下載編譯完成的安裝包，或自行從原始碼建置。

1.從 GitHub Releases 下載預編譯版本

前往專案的 發布頁面 下載最新安裝檔或壓縮檔：

• Windows 桌面完整版 (GUI + Core)：
  • 下載 SUMA-Remote-AI-Bridge-Setup-<版本號>.exe。
  • 執行安裝精靈，可選擇完整安裝（含桌面捷徑、開始功能表啟動項目、自動偵測 WebView2 Runtime）。
  • 安裝精靈亦提供「完整版」、「客戶端連線專用」、「主機端分享專用」之彈性模式捷徑建立。
• Linux 伺服器 / 運算節點 CLI 版 (Headless)：
  • 前往 GitHub Releases 下載對應架構的壓縮檔：SUMA-Remote-AI-Bridge_<版本號>_Beta-linux-amd64.tar.gz 或 SUMA-Remote-AI-Bridge_<版本號>_Beta-linux-arm64.tar.gz。
  • 亦可直接在 Linux 終端機中使用 wget 或 curl 指令下載（以 0.3.4.0 Beta amd64 為例）：

# 使用 wget 下載
wget "https://github.com/marchfun1/SUMA-Remote-AI-Bridge/releases/download/0340/SUMA-Remote-AI-Bridge_0.3.4.0_Beta-linux-amd64.tar.gz"

# 或使用 curl 下載
curl -L -O "https://github.com/marchfun1/SUMA-Remote-AI-Bridge/releases/download/0340/SUMA-Remote-AI-Bridge_0.3.4.0_Beta-linux-amd64.tar.gz"

• 解壓縮至系統目錄並賦予執行權限：

tar -zxvf SUMA-Remote-AI-Bridge_0.3.4.0_Beta-linux-amd64.tar.gz
cd SUMA-Remote-AI-Bridge_0.3.4.0_Beta-linux-amd64
sudo install -m 755 suma-ai-bridge /usr/local/bin/suma-ai-bridge

🚀 快速開始 (Quick Start)

模式 A：分享本機 AI 模型 (Host Server)

1. Windows 桌面版：
   • 啟動 SUMA Remote AI Bridge，前往「分享模型 (Share)」分頁。
   • 確認本機模型的上游連接埠（如 Ollama 預設為 11434，vLLM 預設為 8000）。
   • 點擊「啟動分享」，系統將自動產生一組專屬的安全連線 Token。
   • 將該 Token 提供給欲連線的客戶端或工作夥伴。
2. Linux CLI 版：
   • 在執行 Ollama 或 vLLM 的 Linux 算力節點上直接執行：suma-ai-bridge
   • 終端機將立即輸出兩組 Token：
     • 連線 Token (Connect Token)：提供給客戶端進行模型連線推論。
     • 管理 Token (Admin Token)：提供給 Windows 管理端進行遠端狀態監控與連接埠動態設定。

模式 B：連接遠端 AI 模型 (Client Connector)

1. 啟動 SUMA Remote AI Bridge，前往「連接模型 (Connect)」分頁。
2. 貼上主機端提供的連線 Token，並指定本機映射連接埠（預設為 18080）。
3. 點擊「建立連線」，連線成功後本機即出現相容 OpenAI / Ollama 的標準 API 端點：
   • Base URL：http://127.0.0.1:18080/v1
   • API Key：輸入任意字串（或免填）即可。
4. 在任何 AI 工具（Chatbox,NextChat,Open WebUI,程式碼擴充套件等）中將 API 網址指向 http://127.0.0.1:18080/v1，即可流暢調用遠端模型。