adbproxy 0.1.0__py3-none-any.whl

adbproxy/__init__.py

@@ -0,0 +1,2 @@
+"""ADB proxy implementations and protocol observers."""
+

adbproxy/__main__.py

@@ -0,0 +1,5 @@
+"""python -m adbproxy → 统一 CLI。"""
+
+from adbproxy.cli.main import main
+
+raise SystemExit(main())

adbproxy/cli/__init__.py

@@ -0,0 +1 @@
+"""代理程序命令行入口（统一 adbproxy 与兼容旧脚本）。"""

adbproxy/cli/device.py

@@ -0,0 +1,13 @@
+"""ADB 设备端代理命令行入口。"""
+
+import sys
+
+from adbproxy.device.app import ClientMock
+
+
+def main(argv=None):
+    ClientMock(sys.argv[1:] if argv is None else argv).serve()
+
+
+if __name__ == "__main__":
+    main()

adbproxy/cli/main.py

@@ -0,0 +1,60 @@
+"""统一 CLI：adbproxy server | device。
+
+不修改现有 cli/server.py、cli/device.py；通过临时改写 sys.argv
+再调用旧入口，保证子命令参数与直接运行旧脚本一致。
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+_TOP_HELP = """\
+usage: adbproxy {server,device} ...
+
+子命令:
+  server   client↔adb server smart-socket MITM（原 adb-server-proxy）
+  device   模拟网络 adbd / transport 转发（原 adb-device-proxy）
+
+示例:
+  adbproxy server --help
+  adbproxy device --listen 5566 --target usb
+  python -m adbproxy server --debug
+"""
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if not argv:
+        print(_TOP_HELP, file=sys.stderr)
+        return 2
+
+    if argv[0] in ("-h", "--help"):
+        print(_TOP_HELP)
+        return 0
+
+    cmd, rest = argv[0], argv[1:]
+    if cmd == "server":
+        from adbproxy.cli import server as sub
+    elif cmd == "device":
+        from adbproxy.cli import device as sub
+    else:
+        print(f"unknown command: {cmd}", file=sys.stderr)
+        print(_TOP_HELP, file=sys.stderr)
+        return 2
+
+    old_argv = sys.argv
+    try:
+        # 旧入口固定读 sys.argv[1:]；剥掉子命令名后再调用，避免把
+        # "server"/"device" 传给 AdbProxy / ClientMock 的 argparse。
+        sys.argv = [old_argv[0], *rest]
+        result = sub.main()
+    finally:
+        sys.argv = old_argv
+
+    return 0 if result is None else result
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

adbproxy/cli/server.py

@@ -0,0 +1,13 @@
+"""ADB 服务端代理命令行入口。"""
+
+import sys
+
+from adbproxy.server.app import AdbProxy
+
+
+def main():
+    AdbProxy(sys.argv[1:]).serve()
+
+
+if __name__ == "__main__":
+    main()

adbproxy/config.py

@@ -0,0 +1,39 @@
+import os
+import struct
+
+
+PROXY_PORT = 5037
+REAL_ADB_PORT = 5038
+# 源码布局：本文件在 src/adbproxy/config.py，项目根为 src 的上两级。
+# 运行产物统一落到 <project>/out/{logs,files}，可用 ADB_PROXY_OUT_DIR 覆盖 out 根目录。
+_SRC_DIR = os.path.dirname(os.path.abspath(__file__))
+_PROJECT_ROOT = os.path.dirname(os.path.dirname(_SRC_DIR))
+_OUT_ROOT = os.environ.get(
+    "ADB_PROXY_OUT_DIR", os.path.join(_PROJECT_ROOT, "out")
+)
+LOG_DIR = os.path.join(_OUT_ROOT, "logs")
+FILES_DIR = os.path.join(_OUT_ROOT, "files")
+IDLE_TIMEOUT = 0.15
+MAX_V2_BUF = 1 << 20  # 1 MiB，v2 半包重组缓冲上限
+MAX_CMD = 4096  # 单条命令累积上限
+SYNC_DATA_MAX = (
+    64 * 1024
+)  # 与 AOSP file_sync_protocol.h:146 一致，DATA 单块上限（校验用）
+MAX_SYNC_FILE = 256 * 1024 * 1024  # 单文件落盘上限 256 MiB，防磁盘失控
+# sync v2 定长 struct 大小（核对 file_sync_protocol.h，packed little-endian）
+# sync_stat_v2: id,error,dev,ino,mode,nlink,uid,gid,size,atime,mtime,ctime
+_STAT_V2_FMT = "<IIQQIIIIQqqq"
+_STAT_V2_SIZE = struct.calcsize(_STAT_V2_FMT)  # 72
+# sync_dent_v2: stat_v2 + namelen
+_DENT_V2_FMT = _STAT_V2_FMT + "I"
+_DENT_V2_SIZE = struct.calcsize(_DENT_V2_FMT)  # 76，后随 namelen 字节 name
+# sync_stat_v1: id,mode,size,mtime
+_STAT_V1_SIZE = struct.calcsize("<IIII")  # 16
+# sync_dent_v1: id,mode,size,mtime,namelen
+_DENT_V1_SIZE = struct.calcsize("<IIIII")  # 20，后随 namelen 字节 name
+_SEND_V2_SIZE = struct.calcsize("<III")  # sync_send_v2: id,mode,flags = 12
+_RECV_V2_SIZE = struct.calcsize("<II")  # sync_recv_v2: id,flags = 8
+
+DEFAULT_LISTEN_PORT = 5566
+DEFAULT_ADB_SERVER_PORT = 5037
+DEFAULT_BANNER_FEATURES = "shell_v2,sendrecv_v2"

adbproxy/device/__init__.py

@@ -0,0 +1 @@
+"""ADB server 到 daemon 的传输代理。"""

adbproxy/device/app.py

@@ -0,0 +1,532 @@
+import argparse
+import datetime
+import os
+import signal
+import socket
+import subprocess
+import sys
+import threading
+
+from adbproxy.config import (
+    DEFAULT_ADB_SERVER_PORT,
+    DEFAULT_BANNER_FEATURES,
+    DEFAULT_LISTEN_PORT,
+    FILES_DIR,
+    LOG_DIR,
+)
+from adbproxy.protocols.adb import AdbProtocol
+from adbproxy.runtime.adb_process import AdbServerLease
+from adbproxy.runtime.logging import DebugHexLogger, FileLogger
+
+from .connection import TransportConnection, _next_conn_id
+
+
+class ClientMock:
+    """主流程：监听 --listen、accept 循环、可选自起 adb server / net 目标 connect、信号清理。
+
+    CLI 参数解析、运行生命周期与参考脚本保持一致。
+    """
+
+    def __init__(self, argv):
+        parser = argparse.ArgumentParser(
+            description="client-mock：模拟网络 adbd，MITM 转发到真实设备（传输协议↔5037 文本协议）"
+        )
+        parser.add_argument(
+            "--listen",
+            type=int,
+            default=DEFAULT_LISTEN_PORT,
+            help="监听端口（默认 5566）",
+        )
+        parser.add_argument(
+            "--target",
+            default="usb",
+            help="目标设备：serial:<s> | net:<ip>:<port> | usb（默认 usb 自动取首个 USB 设备）",
+        )
+        parser.add_argument(
+            "--adb-server-port",
+            type=int,
+            default=DEFAULT_ADB_SERVER_PORT,
+            help="后端 adb server 端口（默认 5037 复用系统；非 5037 自起并退出清理）",
+        )
+        parser.add_argument(
+            "--debug",
+            action="store_true",
+            help="每 recv 原始字节 hex 落盘 logs/debug-*.log",
+        )
+        parser.add_argument(
+            "--no-capture", action="store_true", help="禁用 sync/install 文件落盘"
+        )
+        parser.add_argument(
+            "--banner-type",
+            default="device",
+            help="CNXN banner type 前缀（效仿 adbd -b，默认 device）",
+        )
+        args = parser.parse_args(argv)
+        self.listen_port = args.listen
+        self.target = args.target
+        self.adb_server_port = args.adb_server_port
+        self.banner_type = (
+            args.banner_type
+        )  # 效仿 adbd adb_device_banner (adb_trace.cpp:34 + main.cpp:350)
+        self.banner_product = None  # ro.product.name，None=回退
+        self.banner_model = None  # ro.product.model
+        self.banner_device = None  # ro.product.device
+        self.banner_features = DEFAULT_BANNER_FEATURES  # 回退初值，serve() 中 _resolve_banner_features 覆盖
+        self.capture_enabled = not args.no_capture
+        self.debug_enabled = args.debug
+        # 日志目录/文件
+        try:
+            os.makedirs(LOG_DIR, exist_ok=True)
+        except OSError:
+            pass
+        if self.capture_enabled:
+            try:
+                os.makedirs(FILES_DIR, exist_ok=True)
+            except OSError:
+                self.capture_enabled = False
+        now = datetime.datetime.now()
+        stamp = now.strftime("%Y-%m-%d-%H:%M:%S-") + f"{now.microsecond // 1000:03d}"
+        self.log_path = os.path.join(LOG_DIR, stamp + ".log")
+        self.file_logger = FileLogger(self.log_path)
+        if self.debug_enabled:
+            self.debug_path = os.path.join(LOG_DIR, stamp + "-debug.log")
+            self.debug_logger = DebugHexLogger(self.debug_path)
+        else:
+            self.debug_path = None
+            self.debug_logger = None
+        self._conn_counter = 0
+        self._counter_lock = threading.Lock()
+        self._connections_lock = threading.Lock()
+        self._connections = {}
+        self._cleanup_lock = threading.Lock()
+        self._cleaned = False
+        self.listen_sock = None
+        self._stop = False
+        self.adb_server_lease = AdbServerLease(
+            managed_port=self.adb_server_port,
+            log=self._glog,
+        )
+        self.serial = None  # serve() 解析 --target 后填
+
+    def _glog(self, msg):
+        try:
+            print(msg)
+        except Exception:
+            pass
+        self.file_logger.write(msg)
+
+    # ---------- 目标解析 ----------
+    def _resolve_target(self):
+        t = self.target
+        if t.startswith("serial:"):
+            return t[len("serial:") :]
+        if t.startswith("net:"):
+            addr = t[len("net:") :]
+            self._glog(f"[*] adb connect {addr} ...")
+            try:
+                result = subprocess.run(
+                    ["adb", "-P", str(self.adb_server_port), "connect", addr],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=10,
+                )
+            except subprocess.TimeoutExpired:
+                self._glog("[!] adb 调用超时: connect")
+                return None
+            except FileNotFoundError:
+                self._glog("[!] adb 未找到: connect")
+                return None
+            if result.returncode != 0:
+                self._glog(
+                    f"[!] adb connect {addr} 失败，returncode={result.returncode}"
+                )
+                return None
+            return addr
+        if t == "usb" or not t:
+            return self._first_usb_serial()
+        return t  # 当作裸 serial
+
+    def _first_usb_serial(self):
+        try:
+            r = subprocess.run(
+                ["adb", "-P", str(self.adb_server_port), "devices", "-l"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+        except subprocess.TimeoutExpired:
+            self._glog("[!] adb 调用超时: devices")
+            return None
+        except FileNotFoundError:
+            self._glog("[!] adb 未找到: devices")
+            return None
+        if r.returncode != 0:
+            self._glog(f"[!] adb devices -l 失败，returncode={r.returncode}")
+            return None
+        for line in r.stdout.splitlines()[1:]:
+            line = line.strip()
+            if not line:
+                continue
+            parts = line.split()
+            if len(parts) < 3:
+                continue
+            ser, st, *metadata = parts
+            if st != "device":
+                continue
+            if not any(field.startswith("usb:") for field in metadata):
+                continue
+            return ser
+        return None
+
+    # ---------- 查询后端真机 banner features ----------
+    def _resolve_banner_features(self):
+        """启动时经 5037 单帧 host-serial:<serial>:features 查后端真机 CNXN banner
+        features，原样 advertised 给前端，仅硬剥 delayed_ack（front v1 停等流控不支持，
+        banner 含 delayed_ack 触发 adb.cpp:507 mismatch → send_close）。压缩子 feature
+        （sendrecv_v2_brotli/lz4/zstd/dry_run_send）一律保留，靠 raw 透传。失败返回 None，
+        调用方用 DEFAULT_BANNER_FEATURES 回退不崩。
+
+        帧序：单帧 host-serial:<serial>:features（对齐真 adb client
+        format_host_command("features")，adb_client.cpp:415-422）。非 pin-transport 双握手：
+        host:transport 返回 SwitchedTransport 后 smart_socket_data.clear()（sockets.cpp:865），
+        下一帧裸 features 无 host-* 前缀会被误路由到传输流路径向设备发 A_OPEN service=features
+        → 设备无此流服务 → CLSE → 静默失败。"""
+        try:
+            sock = socket.create_connection(
+                ("127.0.0.1", self.adb_server_port), timeout=5
+            )
+        except Exception as e:
+            self._glog(f"[!] 查询 banner features 连接 5037 失败: {e}")
+            return None
+        try:
+            sock.settimeout(5)
+            body = f"host-serial:{self.serial}:features"
+            sock.sendall(AdbProtocol.format_service_frame(body))
+            # 4B status（recv 凑齐半包）
+            st = self._recv_exact_sock(sock, 4)
+            if st is None:
+                self._glog("[!] 查询 banner features 读 status EOF")
+                return None
+            s = st.decode("ascii", errors="ignore")
+            if s == "OKAY":
+                hb = self._recv_exact_sock(sock, 4)
+                if hb is None:
+                    self._glog("[!] 查询 banner features 读 hex4 EOF")
+                    return None
+                try:
+                    plen = int(hb.decode("ascii", errors="ignore"), 16)
+                except ValueError:
+                    self._glog(f"[!] 查询 banner features hex4 非法: {hb!r}")
+                    return None
+                payload = self._recv_exact_sock(sock, plen) if plen else b""
+                if payload is None:
+                    self._glog("[!] 查询 banner features 读 payload EOF")
+                    return None
+                feats = payload.decode("utf-8", errors="replace")
+            elif s == "FAIL":
+                hb = self._recv_exact_sock(sock, 4)
+                plen = 0
+                if hb:
+                    try:
+                        plen = int(hb.decode("ascii", errors="ignore"), 16)
+                    except ValueError:
+                        plen = 0
+                fbody = self._recv_exact_sock(sock, plen) if plen else b""
+                self._glog(
+                    f"[!] 查询 banner features FAIL: {fbody.decode('utf-8', errors='replace')!r}"
+                )
+                return None
+            else:
+                self._glog(f"[!] 查询 banner features status 异常: {s!r}")
+                return None
+        except Exception as e:
+            self._glog(f"[!] 查询 banner features 异常: {e}")
+            return None
+        finally:
+            try:
+                sock.close()
+            except Exception:
+                pass
+        # 硬剥 delayed_ack（front v1 流控硬约束）；压缩子 feature 一律保留
+        feats_list = [f for f in feats.split(",") if f and f != "delayed_ack"]
+        return ",".join(feats_list)
+
+    # ---------- 查询后端真机 banner ro.product.*（效仿 adbd GetProperty 循环）----------
+    def _resolve_banner_fields(self):
+        """效仿 adbd get_connection_string (adb.cpp:294-316) 的 GetProperty(prop) 循环：
+        逐属性经 5037 pin+shell 两步读后端 raw 系统属性（= __system_property_get 远端等价）。
+        shell 须先 host:transport:<serial> pin（adb.cpp:1339-1347 SwitchedTransport）再同 socket
+        发 shell:，adb server 经 connect_to_remote（sockets.cpp:925-934）A_OPEN 到设备
+        ShellService（daemon/services.cpp:354 ConsumePrefix("shell")），输出 raw 流至 EOF
+        （ReadOrderlyShutdown，adb_client.cpp:234）。成功返回 (product,model,device)，
+        失败 None。解析只读旁路，启动期查询 socket 与 per-conn 转发隔离，不影响 sendall 透传。"""
+        _BANNER_PROPS = ("ro.product.name", "ro.product.model", "ro.product.device")
+        values = []
+        for prop in _BANNER_PROPS:
+            val = self._query_getprop(prop)
+            if val is None:
+                return None  # 任一属性失败→整体回退（效仿 adbd 不容部分缺失）
+            values.append(val)
+        return tuple(values)
+
+    def _query_getprop(self, prop):
+        """单次 shell:getprop 查询（pin+shell 两步同 socket，architect round2 修订）。
+        返回 strip 后属性值，失败 None。逐属性独立 socket：shell EOF 后 adb server 关
+        socket 不可复用，故 3 socket/3 RTT。"""
+        try:
+            sock = socket.create_connection(
+                ("127.0.0.1", self.adb_server_port), timeout=5
+            )
+        except Exception as e:
+            self._glog(f"[!] 查询 {prop} 连接 5037 失败: {e}")
+            return None
+        try:
+            sock.settimeout(5)
+            # ① pin transport: host:transport:<serial>（legacy，无 transport_id 回写）
+            # 对齐 problem3 AdbClientBackend.start() 既有 pin 模式（adb.cpp:1339-1347）
+            tport = f"host:transport:{self.serial}"
+            sock.sendall(AdbProtocol.format_service_frame(tport))
+            ts = self._recv_exact_sock(sock, 4)
+            if ts is None:
+                self._glog(f"[!] 查询 {prop} 读 tport status EOF")
+                return None
+            ts = ts.decode("ascii", errors="ignore")
+            if ts == "FAIL":  # tport FAIL：读 hex4+error（device 未找到等）
+                self._read_fail_body(sock, f"tport {prop}")
+                return None
+            if ts != "OKAY":
+                self._glog(f"[!] 查询 {prop} tport status 异常: {ts!r}")
+                return None
+            # ② 同 socket 发 shell:getprop <prop>（无 host 前缀，走 connect_to_remote）
+            svc = f"shell:getprop {prop}"
+            sock.sendall(AdbProtocol.format_service_frame(svc))
+            st = self._recv_exact_sock(sock, 4)
+            if st is None:
+                self._glog(f"[!] 查询 {prop} 读 svc status EOF")
+                return None
+            s = st.decode("ascii", errors="ignore")
+            if s == "OKAY":
+                # shell 流式：recv 循环至 EOF（ReadOrderlyShutdown 语义）
+                stream = bytearray()
+                while True:
+                    try:
+                        chunk = sock.recv(4096)
+                    except OSError:
+                        break  # 超时/异常→EOF
+                    if not chunk:
+                        break  # adb server 命令结束关 socket
+                    stream.extend(chunk)
+                return stream.decode("utf-8", errors="replace").strip()
+            elif s == "FAIL":
+                self._read_fail_body(sock, f"shell {prop}")
+                return None
+            else:
+                self._glog(f"[!] 查询 {prop} svc status 异常: {s!r}")
+                return None
+        except Exception as e:
+            self._glog(f"[!] 查询 {prop} 异常: {e}")
+            return None
+        finally:
+            try:
+                sock.close()
+            except Exception:
+                pass
+
+    def _read_fail_body(self, sock, label):
+        """读 FAIL 后的 hex4+error body 并打日志（复用 features 分支模式，tport/shell 共用）。"""
+        hb = self._recv_exact_sock(sock, 4)
+        plen = 0
+        if hb:
+            try:
+                plen = int(hb.decode("ascii", errors="ignore"), 16)
+            except ValueError:
+                plen = 0
+        fbody = self._recv_exact_sock(sock, plen) if plen else b""
+        self._glog(
+            f"[!] 查询 {label} FAIL: {fbody.decode('utf-8', errors='replace')!r}"
+            if fbody
+            else f"[!] 查询 {label} FAIL"
+        )
+
+    @staticmethod
+    def _recv_exact_sock(sock, n):
+        """精确读 n 字节（循环拼半包）。EOF/异常返回 None。"""
+        buf = bytearray()
+        while len(buf) < n:
+            try:
+                chunk = sock.recv(n - len(buf))
+            except OSError:
+                return None
+            if not chunk:
+                return None
+            buf.extend(chunk)
+        return bytes(buf)
+
+    # ---------- 自起后端 adb server ----------
+    def _ensure_adb_server(self):
+        if self.adb_server_port == DEFAULT_ADB_SERVER_PORT:
+            self.adb_server_lease.initial_state = "reused"
+            return True  # 复用系统 5037
+        self._glog(f"[*] 自起 adb server @ 端口 {self.adb_server_port} ...")
+        return self.adb_server_lease.acquire_owned()
+
+    # ---------- 信号 ----------
+    def _signal_handler(self, signum, frame):
+        self._stop = True
+        self._glog(f"\n[*] 接收到信号 {signum}，正在清理...")
+        try:
+            if self.listen_sock:
+                self.listen_sock.close()
+        except Exception:
+            pass
+
+    # ---------- serve ----------
+    def serve(self):
+        if not self._ensure_adb_server():
+            self.cleanup()
+            sys.exit(1)
+        self.serial = self._resolve_target()
+        if not self.serial:
+            self._glog(f"[!] 无法解析 --target {self.target!r}：未取到可用设备 serial")
+            self.cleanup()
+            sys.exit(1)
+        self._glog(f"[*] target serial={self.serial}")
+        resolved = self._resolve_banner_features()
+        if resolved is not None:
+            self.banner_features = resolved
+            self._glog(
+                f"[*] resolved banner features (from back :{self.adb_server_port}): {resolved}"
+            )
+        else:
+            self._glog(
+                f"[!] banner features 查询失败，回退默认: {DEFAULT_BANNER_FEATURES}"
+            )
+        fields = self._resolve_banner_fields()
+        if fields is not None:
+            self.banner_product, self.banner_model, self.banner_device = fields
+            self._glog(
+                f"[*] resolved banner fields (效仿 adbd GetProperty, from back :{self.adb_server_port}): "
+                f"name={self.banner_product} model={self.banner_model} device={self.banner_device}"
+            )
+        else:
+            self._glog(
+                "[!] banner fields 查询失败，banner 回退修复前形态（type=device, ro.product.name=client-mock）"
+            )
+        # bind listen
+        self.listen_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.listen_sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            self.listen_sock.bind(("127.0.0.1", self.listen_port))
+            self.listen_sock.listen(5)
+        except OSError as e:
+            self._glog(f"[!] 监听端口 {self.listen_port} 绑定失败: {e}")
+            self.cleanup()
+            sys.exit(1)
+        self._glog(
+            f"[*] client-mock 运行中，监听 {self.listen_port}，后端 adb server :{self.adb_server_port}，target={self.serial}"
+        )
+        self._glog(f"[*] 日志文件: {self.log_path}")
+        if self.debug_logger:
+            self._glog(f"[*] debug hex 日志: {self.debug_path}")
+        else:
+            self._glog("[*] debug hex 日志: <off>（--debug 可开启）")
+        if self.capture_enabled:
+            self._glog(
+                f"[*] 文件传输捕获已开启，落盘目录: {FILES_DIR}（--no-capture 可禁用）"
+            )
+        else:
+            self._glog(
+                "[*] 文件传输捕获已禁用（--no-capture），仅打印 sync/install 摘要"
+            )
+        self._glog(
+            "[*] 用法：adb connect 127.0.0.1:%d，然后 adb -s 127.0.0.1:%d <cmd>"
+            % (self.listen_port, self.listen_port)
+        )
+        signal.signal(signal.SIGINT, self._signal_handler)
+        signal.signal(signal.SIGTERM, self._signal_handler)
+        self.listen_sock.settimeout(0.5)
+        try:
+            while not self._stop:
+                try:
+                    client, _ = self.listen_sock.accept()
+                except socket.timeout:
+                    continue
+                except OSError:
+                    break
+                conn_id = _next_conn_id()  # 与 per-stream sb 共用计数器，保证全局唯一
+                conn = TransportConnection(
+                    conn_id,
+                    client,
+                    self.file_logger,
+                    self.capture_enabled,
+                    self.debug_logger,
+                    self.serial,
+                    self.adb_server_port,
+                    self.banner_features,
+                    self.banner_type,
+                    self.banner_product,
+                    self.banner_model,
+                    self.banner_device,
+                )
+                thread = threading.Thread(
+                    target=self._connection_worker, args=(conn,), daemon=True
+                )
+                with self._connections_lock:
+                    self._connections[conn] = thread
+                thread.start()
+        except KeyboardInterrupt:
+            self._glog("\n[*] 接收到中断信号，正在清理环境并退出...")
+        finally:
+            self.cleanup()
+
+    def _connection_worker(self, conn):
+        try:
+            conn.run()
+            conn.wait()
+        finally:
+            with self._connections_lock:
+                self._connections.pop(conn, None)
+
+    def _drain_connections(self):
+        with self._connections_lock:
+            connections = list(self._connections.items())
+        for conn, _thread in connections:
+            conn.stop()
+        current = threading.current_thread()
+        for conn, thread in connections:
+            conn.wait(timeout=5)
+            if thread is not current:
+                thread.join(timeout=5)
+
+    def cleanup(self):
+        cleanup_lock = getattr(self, "_cleanup_lock", None)
+        if cleanup_lock is None:
+            cleanup_lock = threading.Lock()
+            self._cleanup_lock = cleanup_lock
+        with cleanup_lock:
+            if getattr(self, "_cleaned", False):
+                return
+            self._cleaned = True
+        # 1. 关 listen socket 释放端口，打断 accept
+        try:
+            if self.listen_sock:
+                self.listen_sock.close()
+        except Exception:
+            pass
+        # 2. 先停活动连接并等待 transport/backend/observer 收尾。
+        self._drain_connections()
+        # 3. 只清理 lease 明确拥有的 adb server；端口存在不构成 ownership。
+        lease = getattr(self, "adb_server_lease", None)
+        lease_complete = True
+        if lease is not None:
+            if lease.cleanup() is False:
+                lease_complete = False
+                self._glog("[!] adb server 清理未完成；已保留 lease 状态供后续重试")
+        # net 目标不主动 disconnect（让 adb server 自然回收）
+        self.file_logger.close()
+        if self.debug_logger:
+            self.debug_logger.close()
+        if not lease_complete:
+            with cleanup_lock:
+                self._cleaned = False
+        return lease_complete