commit f96c1aa109d8ffb60a06de6ccfebb6d0a6d0e2fe Author: tongtongstudio Date: Thu Nov 12 12:08:03 2026 +0800 Add local ADB bridge through remote device transport diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a32bcd7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +/adb/ +/scrcpy/ +/QtScrcpy/ +__pycache__/ +*.pyc +/target/ +/bin/ +/work/ +.env +*.log diff --git a/README.md b/README.md new file mode 100644 index 0000000..8b2bbdd --- /dev/null +++ b/README.md @@ -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:` 及设备 `tcp:` 服务。 diff --git a/adb_bridge.py b/adb_bridge.py new file mode 100644 index 0000000..1feedd0 --- /dev/null +++ b/adb_bridge.py @@ -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()) diff --git a/start-bridge.ps1 b/start-bridge.ps1 new file mode 100644 index 0000000..cab0edd --- /dev/null +++ b/start-bridge.ps1 @@ -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 diff --git a/tests/test_bridge.py b/tests/test_bridge.py new file mode 100644 index 0000000..dc351d3 --- /dev/null +++ b/tests/test_bridge.py @@ -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()