Add local ADB bridge through remote device transport

This commit is contained in:
tongtong committed 2026-11-12 12:08:03 +08:00
commit f96c1aa109
5 files changed
+296

No files matched your search

+10
View File
@@ -0,0 +1,10 @@
/adb/
/scrcpy/
/QtScrcpy/
__pycache__/
*.pyc
/target/
/bin/
/work/
.env
*.log
+77
View File
@@ -0,0 +1,77 @@
# Android 远程设备桥接
让本机普通 `adb devices` 显示远程手机,同时保留本地 ADB 服务及其他本地设备。
```text
本地 adb → 127.0.0.1:15555(本程序)
→ 192.168.5.222:5037(远程 ADB 服务)
→ 已连接的 192.168.100.141:5555
→ 手机自身 localhost:5555(adbd)
```
本地无需能访问手机网段。远程电脑必须能访问手机,手机必须已开启 TCP ADB 5555;仅 USB 或 TLS 无线调试设备不能直接套用本方案。
## 远程电脑
保持下面的服务运行(停止旧服务会中断已有调试连接):
```powershell
adb kill-server
adb -a -P 5037 nodaemon server start
```
另开窗口:
```powershell
adb connect 192.168.100.141:5555
adb devices
```
只允许可信 VPN 客户端访问远程 TCP 5037。ADB smart socket 没有客户端认证和加密,不应直接暴露公网。以后走公网时,把 `--remote-host` 和 `--remote-port` 改成 SSH 等认证加密隧道的本地入口。
## 本地电脑
需要 Python 3、ADB;画面操作另外需要 scrcpy。
在项目目录执行并保持窗口运行:
```powershell
python .\adb_bridge.py
```
另开 PowerShell,清除之前指向远程服务的环境变量,仅影响当前窗口:
```powershell
Remove-Item Env:ADB_SERVER_SOCKET -ErrorAction SilentlyContinue
Remove-Item Env:ANDROID_ADB_SERVER_ADDRESS -ErrorAction SilentlyContinue
Remove-Item Env:ANDROID_ADB_SERVER_PORT -ErrorAction SilentlyContinue
adb connect 127.0.0.1:15555
adb devices -l
adb -s 127.0.0.1:15555 shell getprop ro.product.model
```
应出现 `127.0.0.1:15555 device`。首次可能是 `unauthorized`,需要在手机上批准本地电脑的 RSA 调试密钥;远程电脑的授权不会自动授予本地电脑。
画面及鼠标操作:
```powershell
scrcpy -s 127.0.0.1:15555
```
这是真正注册到本地 ADB 服务的 TCP 设备,Android Studio 应能发现它(需使用同一个本地 ADB 服务)。安装、shell、logcat、forward/reverse 均走本地 ADB 的正常设备通道;实际设备上的兼容性仍需验证。断点调试要求目标应用可调试。
## 参数、诊断及停止
```powershell
python .\adb_bridge.py --check
python .\adb_bridge.py --remote-host 192.168.5.222 --remote-port 5037 --serial 192.168.100.141:5555 --device-port 5555 --listen-port 15555
python -m unittest discover -s tests -v
```
- `--check` 只检查远程设备选择和手机 TCP 端口,不验证本地 RSA 授权、投屏或 IDE。
- 找不到设备:在远程电脑重新 `adb connect`,检查设备序列号。
- `tcp:5555` 失败:手机必须监听自身 TCP 5555;某些系统可能限制回环访问。
- 远程链路断开后:恢复远程设备连接,再在本地重跑 `adb connect 127.0.0.1:15555`。当前版本不主动自动重连。
- 停止:本地执行 `adb disconnect 127.0.0.1:15555`,再在桥接窗口按 Ctrl+C。
协议依据:本项目自带的 `adb/docs/dev/services.md` 中 `host:transport:<serial-number>` 及设备 `tcp:<port>` 服务。
+110
View File
@@ -0,0 +1,110 @@
"""Expose an adbd TCP endpoint through a remote ADB smart socket server."""
import argparse
import logging
import select
import socket
import socketserver
def read_exact(sock, size):
data = bytearray()
while len(data) < size:
chunk = sock.recv(size - len(data))
if not chunk:
raise ConnectionError('ADB server closed the connection')
data.extend(chunk)
return bytes(data)
def request(sock, service):
payload = service.encode('utf-8')
if len(payload) > 65535:
raise ValueError('ADB service name is too long')
sock.sendall(f'{len(payload):04x}'.encode('ascii') + payload)
status = read_exact(sock, 4)
if status == b'FAIL':
size = int(read_exact(sock, 4), 16)
raise ConnectionError(read_exact(sock, size).decode('utf-8', 'replace'))
if status != b'OKAY':
raise ConnectionError(f'Invalid ADB response: {status!r}')
def open_device(host, port, serial, device_port, timeout=10):
sock = socket.create_connection((host, port), timeout=timeout)
try:
request(sock, f'host:transport:{serial}')
# This TCP connection is opened by adbd on the PHONE, not by the PC.
request(sock, f'tcp:{device_port}')
sock.settimeout(None)
sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
return sock
except BaseException:
sock.close()
raise
def relay(left, right):
"""Preserve TCP half-close so responses can finish after a request EOF."""
peers = {left: right, right: left}
while peers:
readable, _, _ = select.select(list(peers), [], [], 1)
for source in readable:
data = source.recv(65536)
target = peers[source]
if data:
target.sendall(data)
else:
del peers[source]
try:
target.shutdown(socket.SHUT_WR)
except OSError:
pass
class BridgeHandler(socketserver.BaseRequestHandler):
def handle(self):
args = self.server.config
try:
with open_device(args.remote_host, args.remote_port,
args.serial, args.device_port) as upstream:
logging.info('Connected client %s to %s', self.client_address, args.serial)
relay(self.request, upstream)
except (OSError, ValueError) as exc:
logging.warning('Connection ended: %s', exc)
class BridgeServer(socketserver.ThreadingTCPServer):
allow_reuse_address = True
daemon_threads = True
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--remote-host', default='192.168.5.222')
parser.add_argument('--remote-port', type=int, default=5037)
parser.add_argument('--serial', default='192.168.100.141:5555')
parser.add_argument('--device-port', type=int, default=5555,
help='adbd TCP listening port on the phone')
parser.add_argument('--listen-port', type=int, default=15555)
parser.add_argument('--check', action='store_true', help='check upstream only, then exit')
args = parser.parse_args()
logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s')
try:
with open_device(args.remote_host, args.remote_port, args.serial, args.device_port):
logging.info('Upstream ADB transport and phone TCP port are reachable')
if args.check:
return 0
with BridgeServer(('127.0.0.1', args.listen_port), BridgeHandler) as server:
server.config = args
logging.info('Listening on 127.0.0.1:%d; keep this window open', args.listen_port)
logging.info('Run locally: adb connect 127.0.0.1:%d', args.listen_port)
server.serve_forever()
except KeyboardInterrupt:
return 0
except (OSError, ValueError) as exc:
logging.error('%s', exc)
return 1
if __name__ == '__main__':
raise SystemExit(main())
+8
View File
@@ -0,0 +1,8 @@
param(
[string]$RemoteHost = '192.168.5.222',
[string]$Serial = '192.168.100.141:5555',
[int]$ListenPort = 15555
)
$ErrorActionPreference = 'Stop'
python (Join-Path $PSScriptRoot 'adb_bridge.py') --remote-host $RemoteHost --serial $Serial --listen-port $ListenPort
exit $LASTEXITCODE
+91
View File
@@ -0,0 +1,91 @@
import socket
import threading
import unittest
from adb_bridge import open_device, read_exact, relay
class BridgeTests(unittest.TestCase):
def run_server(self, handler):
listener = socket.socket()
listener.bind(('127.0.0.1', 0))
listener.listen()
errors = []
def serve():
try:
with listener:
conn, _ = listener.accept()
with conn:
conn.settimeout(3)
handler(conn)
except Exception as exc:
errors.append(exc)
thread = threading.Thread(target=serve, daemon=True)
thread.start()
return listener.getsockname()[1], thread, errors
def read_service(self, conn):
return read_exact(conn, int(read_exact(conn, 4), 16))
def test_select_device_and_preserve_binary_stream(self):
def handler(conn):
self.assertEqual(self.read_service(conn), b'host:transport:test-phone')
# Fragmented replies exercise exact reads, not packet boundaries.
conn.sendall(b'OK')
conn.sendall(b'AY')
self.assertEqual(self.read_service(conn), b'tcp:5555')
conn.sendall(b'OKAY\x00\xffCNXN')
self.assertEqual(read_exact(conn, 3), b'ACK')
port, thread, errors = self.run_server(handler)
with open_device('127.0.0.1', port, 'test-phone', 5555) as conn:
self.assertEqual(read_exact(conn, 6), b'\x00\xffCNXN')
conn.sendall(b'ACK')
thread.join(4)
self.assertFalse(thread.is_alive())
self.assertEqual(errors, [])
def test_remote_failure_is_reported(self):
def handler(conn):
self.read_service(conn)
conn.sendall(b'FAIL0010device not found')
port, thread, errors = self.run_server(handler)
with self.assertRaisesRegex(ConnectionError, 'device not found'):
open_device('127.0.0.1', port, 'missing', 5555)
thread.join(4)
self.assertEqual(errors, [])
def test_half_close_keeps_return_path_open(self):
left, client = socket.socketpair()
right, device = socket.socketpair()
for sock in (left, client, right, device):
sock.settimeout(3)
self.addCleanup(sock.close)
errors = []
def forward():
try:
relay(left, right)
except Exception as exc:
errors.append(exc)
thread = threading.Thread(target=forward, daemon=True)
thread.start()
client.sendall(b'request')
client.shutdown(socket.SHUT_WR)
self.assertEqual(read_exact(device, 7), b'request')
self.assertEqual(device.recv(1), b'')
device.sendall(b'response')
device.shutdown(socket.SHUT_WR)
self.assertEqual(read_exact(client, 8), b'response')
self.assertEqual(client.recv(1), b'')
thread.join(4)
self.assertFalse(thread.is_alive())
self.assertEqual(errors, [])
if __name__ == '__main__':
unittest.main()