Skip to content

README.md

Latest commit

 

History

History
366 lines (262 loc) · 12.9 KB

README.md

File metadata and controls

366 lines (262 loc) · 12.9 KB
Raw

radb -- 遠端 ADB P2P 轉發工具

English Version

透過 P2P 網路穿透，讓你在本機像操作本地 USB 設備一樣，使用遠端主機上的 Android 手機。支援 adb shell、scrcpy 投影與大檔案傳輸。

macOS 使用者：首次開啟若出現「已損毀」或「無法驗證開發者」提示，請執行 sudo xattr -dr com.apple.quarantine /Applications/radb.app 即可解決。詳細說明

Windows 使用者：獨立 .exe 經 UPX 壓縮，部分防毒軟體可能誤報。若遇此情況請改用 .zip 版本。詳細說明

核心特色

  • P2P 穿透 NAT/防火牆，無需 VPN 或 Port Forwarding
  • 三種連線模式：P2P 直連 / 區網 TCP 直連 / Relay Server 中繼
  • 單一主機管理多支設備，每台設備獨立 port，支援多開發者同時使用
  • DTLS 全程加密，Token 身分驗證
  • 單一執行檔部署，免安裝相依套件
  • CLI + GUI 雙介面，一鍵選機、自動分配 Port
  • 支援 adb shell、scrcpy、大檔案傳輸（100MB+ 穩定）

架構簡圖

graph LR
    subgraph 開發者本機
        CLI[radb CLI]
        Daemon[主控端]
    end

    subgraph 雲端/內網
        Signal[radb relay server]
    end

    subgraph 遠端主機
        Agent[被控端]
        Phone1[📱 Device 1]
        Phone2[📱 Device 2]
    end

    CLI -->|IPC| Daemon
    Daemon <-->|WebRTC P2P| Agent
    Daemon <-->|WebSocket 信令| Signal
    Agent <-->|WebSocket 信令| Signal
    Agent -->|ADB Protocol| Phone1
    Agent -->|ADB Protocol| Phone2
Loading

詳細架構設計請參閱 系統架構文件。

環境需求

需求項目 說明
Go >= 1.22（僅建置時需要）
ADB 被控端所在主機需安裝 Android Platform Tools
網路 主控端與被控端需能互相連線（可透過 Server 中繼、LAN 直連或 SDP 手動配對）
作業系統 Windows / Linux / macOS

安裝方式

從原始碼建置

git clone https://github.com/chris1004tw/remote-adb.git
cd remote-adb
go build -trimpath -o radb ./cmd/radb

Windows 上若使用 Go 1.26 以上版本，建議改用：

powershell -ExecutionPolicy Bypass -File .\scripts\build-windows.ps1

go install

go install github.com/chris1004tw/remote-adb/cmd/radb@latest

預編譯 Binary

前往 GitHub Releases 下載對應平台的檔案。

平台 格式 說明
macOS .dmg（Universal Binary） 同時支援 Intel 與 Apple Silicon，開啟後將 radb.app 拖入 Applications
Linux .tar.gz 解壓後取得 radb 執行檔
Windows .zip 解壓後取得 radb.exe（未壓縮，PE 結構完整）
Windows .exe 獨立執行檔（UPX 壓縮，體積較小）

防毒軟體提示：獨立 .exe 經 UPX 壓縮以縮小體積，部分防毒軟體可能因啟發式偵測產生誤報。若遇到此情況，請改用 .zip 版本，其中的 binary 未經 UPX 壓縮，不會觸發誤判。

macOS 首次執行

由於未經 Apple 簽名，macOS 會阻擋首次執行，可能出現以下提示：

  • 「無法打開，因為無法驗證開發者」（Gatekeeper 攔截）
  • 「已損毀，無法打開。您應該將其丟到垃圾桶」（隔離屬性標記）

請依以下任一方式解除：

方式一：移除隔離屬性（推薦，可同時解決「已損毀」提示）

sudo xattr -dr com.apple.quarantine /Applications/radb.app

方式二：本地簽名

# 安裝 Command Line Tools for Xcode（若已安裝可跳過）
xcode-select --install

# 本地簽名
sudo codesign --force --deep --sign - /Applications/radb.app

使用方式

radb 提供三種連線模式，所有模式都同時支援 CLI 和 GUI：

模式 適用場景 需要伺服器
P2P 跨 NAT，一對一快速配對 不需要（預設使用 Cloudflare 免費 TURN）
Direct 同一區網 / VPN 不需要
Relay 多人多設備，長期部署 需要自架 Relay Server

P2P 模式（跨 NAT，不需要任何 Server）

透過 WebRTC 打洞，交換邀請碼/回應碼即可建立 P2P 連線：

# 主控端：生成邀請碼
radb p2p connect
# → 複製邀請碼給被控端，等待輸入回應碼
# → 回應碼輸入錯誤時會重新提示（邀請碼為一次性，不會因誤按而浪費）

# 被控端：處理邀請碼並回傳回應碼
radb p2p agent <邀請碼>
# → 複製回應碼回主控端

# 主控端貼上回應碼 → P2P 連線建立
# → 每台設備分配獨立 port（從 5555 起），自動 adb connect

# 預設使用 Cloudflare 免費 TURN，可用 --conn-mode / --turn-mode 切換：
radb p2p connect --conn-mode direct-only   # 僅 STUN 直連，不使用 TURN 中繼
radb p2p connect --conn-mode relay-only    # 僅走 TURN 中繼
radb p2p connect --turn-mode custom        # 使用自訂 TURN Server

Direct 模式（區網直連，無需 Server）

適用於同一 LAN 或 VPN 內的場景：

# 被控端：在區網內開啟監聽
radb direct agent --port 9000 --token mysecret

# 主控端：自動發現 LAN 上的被控端（mDNS）
radb direct discover

# 查詢設備
radb direct connect 192.168.1.100:9000 --list --token mysecret

# TCP 直連（每台設備分配獨立 port，支援 adb shell / scrcpy / forward）
radb direct connect 192.168.1.100:9000 --token mysecret
# → 每台設備分配獨立 port（從 5555 起），自動 adb connect

Relay 模式（透過中繼伺服器）

適用於多人多設備的團隊環境：

步驟 1：啟動 Relay Server

RADB_TOKEN=your-secret radb relay server --port 8080

步驟 2：在遠端主機啟動被控端

RADB_TOKEN=your-secret radb relay agent --server ws://your-server:8080 --host-id lab-pc-01

步驟 3：啟動本機 Daemon

RADB_TOKEN=your-secret radb relay daemon --server ws://your-server:8080

步驟 4：互動式綁定設備

radb relay bind
# 選擇主機 → 選擇設備 → 自動分配 Port
# 輸出：已綁定 DEVICE_SERIAL → localhost:15555

步驟 5：像本地設備一樣使用

adb -s localhost:15555 shell
scrcpy -s localhost:15555
adb -s localhost:15555 push large_file.apk /sdcard/

完整設定參數請參閱 設定指南。

GUI 介面

直接執行 radb（不帶引數）即可開啟圖形介面。

radb

分頁

分頁 功能 對應 CLI
簡易連線 跨 NAT 手動 SDP 交換（主控端 / 被控端雙模式） radb p2p
區網直連 開啟被控端伺服器或掃描 LAN 自動發現 radb direct
Relay 伺服器 透過中央 Relay Server 連線 radb relay

功能特色

  • Per-device Proxy Port：每台遠端設備分配獨立 port（從 5555 起遞增），scrcpy / UIAutomator 可直接以 adb -s 127.0.0.1:<port> 操作特定設備
  • 設備機型名稱顯示：設備列表顯示機型名稱（如 "Pixel 10 Pro XL (SN123) → 127.0.0.1:5555"），一目了然
  • 重新添加遠端 ADB 設備：P2P 主控端提供一鍵重新 adb connect 按鈕，Scrcpy GUI 等工具誤斷 ADB 時不需重建 P2P 連線
  • 重新偵測被控端設備：P2P 主控端可請求被控端重新掃描 ADB 設備，不需重建連線
  • 快速邀請碼：P2P 分頁提供「立即產生邀請碼」按鈕，犧牲部分候選換取速度
  • 邀請碼預產生：切入主控模式時自動在背景預產生邀請碼，點擊時可秒出結果
  • 連線進度顯示：多階段進度回報（準備 TURN → 建立元件 → 蒐集候選 → 壓縮）
  • 多語系：繁體中文 / English，根據系統語系自動偵測，可即時切換（不需重啟）
  • 自動更新：啟動後背景檢查新版本，主畫面底部顯示通知橫幅

設定面板

點擊右下角齒輪圖示開啟，可管理：

  • ADB Port、Proxy Port、Direct Port
  • 連線方式（優先直連 / 僅直連 / 僅中繼）
  • NAT 探測伺服器（STUN）
  • 中繼伺服器模式（Cloudflare 免費 / 自訂 URL + 帳號密碼）
  • 語言切換、手動檢查更新

TURN 預設使用 Cloudflare 免費憑證（自動取得，開箱即用）。設定以 TOML 格式持久化於 exe 同目錄的 radb.toml。

設定說明

環境變數 預設值 說明
RADB_TOKEN (必填) PSK 驗證 Token
RADB_SERVER_URL ws://localhost:8080 Server 位址
RADB_STUN_URLS stun:stun.l.google.com:19302 STUN Server
RADB_CONN_MODE direct-first 連線方式（direct-first / direct-only / relay-only）
RADB_TURN_MODE cloudflare TURN 模式（cloudflare / custom）
RADB_TURN_URL (空) 自訂 TURN Server URL（--turn-mode custom 時使用）
RADB_DIRECT_PORT (空) 被控端 Direct TCP 監聽埠
RADB_DIRECT_TOKEN (空) Direct 連線 Token
RADB_PORT_START 5555 主控端起始 Port

完整設定請參閱 設定指南。

專案目錄結構

remote-adb/
├── cmd/
│   └── radb/              # 統一入口（p2p/direct/relay 三模組 + update/version + GUI + 自動搬遷/遷移）
├── internal/
│   ├── adb/               # ADB 協定、設備管理、自動下載 platform-tools（exe 同目錄）
│   ├── agent/             # 遠端代理端核心邏輯
│   ├── buildinfo/         # 編譯時注入的版本資訊（Version/Commit/Date）+ 主機名稱快取
│   ├── cli/               # bubbletea 互動式 bind 選單
│   ├── daemon/            # 背景服務、Port 分配、Binding Table、IPC
│   ├── bridge/            # GUI/CLI 共用邏輯（SDP 編解碼、ADB transport、forward 管理）
│   ├── directsrv/         # TCP 直連服務 + mDNS 廣播 + 客戶端連線
│   ├── gui/               # Gio GUI 介面（設定面板 + i18n 多語系 + Cloudflare TURN + TURN 預取快取）
│   ├── ioutil/            # 共用 I/O 工具（ChunkedCopy：分塊複製 + short write 保護 + sync.Pool buffer reuse、BiCopy：雙向複製 + 雙向 Close + ctx 取消）
│   ├── proxy/             # TCP 代理（16KB chunking、單連線替換設計）
│   ├── signal/            # WebSocket 信令 hub、PSK 認證、客戶端 ConnectAndAuth 共用
│   ├── updater/           # 自動更新（GitHub Releases 下載 + 跨平台 binary 替換）
│   └── webrtc/            # PeerConnection 與 DataChannel 管理（detach 模式 + relay 偵測 + Cloudflare TURN 取得）
├── pkg/protocol/          # 共用信令 JSON 格式（Envelope + Payload types）
├── assets/                # 跨平台共用資源（應用程式 SVG 圖示）
├── macos/                 # macOS .app bundle metadata（Info.plist）
├── configs/               # 設定檔範例
├── docs/                  # 詳細設計文件
├── scripts/               # 平台輔助腳本（build-dmg.sh、build-windows.ps1：Windows 本地建置入口）
├── test/e2e/              # 端對端整合測試
├── go.mod
└── README.md

開發指南

# 建置
go build -trimpath -o radb ./cmd/radb

# 測試
go test ./...

# Lint
golangci-lint run

Windows 本機建置時，若 Go 版本為 1.26+，請改用 scripts/build-windows.ps1 以自動套用 GOEXPERIMENT=nogreenteagc。

詳細請參閱 開發者指南。

文件連結

文件 說明
系統架構 三元件架構、信令協定、技術選型
被控端設計 遠端被控端的設備管理與轉發機制
主控端設計 本機端 Daemon、CLI、TCP 代理設計
設定指南 完整環境變數與 CLI flag 參數表
開發者指南 建置、測試、程式碼規範
coturn 架設指南 TURN Server 安裝、設定與整合

FAQ

Q: 連線不上遠端設備？ A: 檢查 Server 是否可達、Token 是否一致、防火牆是否阻擋 WebRTC 流量。若在對稱型 NAT 後方，需設定 TURN Server（GUI 預設已啟用 Cloudflare 免費 TURN，通常不需額外設定）。

Q: 設備顯示 offline？ A: 確認遠端主機的 ADB server 正在運行（adb start-server），且設備已授權 USB 偵錯。

Q: Port 被占用？ A: 使用 --port-start 指定不同起始 Port，或用 radb relay list 查看已占用的 Port。

Q: 大檔案傳輸中斷？ A: 若使用 TURN 中繼，檢查 TURN server 的頻寬限制。建議在可行時使用 STUN 直連（P2P）。

License

MIT License -- 詳見 LICENSE