procproxy 0.1.0__py3-none-any.whl

proxycore/forward.py

@@ -0,0 +1,572 @@
+"""把指定进程的 TCP 流量转发给抓包工具（`procproxy <进程名>` 的实现）。
+
+让目标进程以为自己在直连，实际每条 TCP 连接都被改道到本机 sink，
+再经你指定的上游代理（Yakit / Burp / Charles）转发出去。
+
+它替你做四件事：自检 → 生成配置 → 起数据面 → 收尾。
+
+## 用法
+
+    python procproxy.py WeChat.exe --port 8848
+    python procproxy.py Weixin.exe WeChatAppEx.exe --port 8848   # 多个进程
+    python procproxy.py WeChat.exe --port 8848 --check-only      # 只自检，不改流量
+
+## 边界
+
+UDP/QUIC 抓不到；按域名写的规则不命中；上游必须写 IP；默认只代理点名的进程。
+完整说明、三层成功判据与排错见 `docs/14-把进程流量转发给抓包工具.md`。
+"""
+
+from __future__ import annotations
+
+import _thread
+import argparse
+import contextlib
+import fnmatch
+import json
+import os
+import pathlib
+import sys
+import threading
+from typing import Any
+
+import yaml
+
+from proxycore.backend import BackendUnavailable, make_backend
+from proxycore.cli import runtime_dir
+from proxycore.config import Config, ConfigError, ConfigManager, port_in_use
+from proxycore.log import build_logger, get_logger
+from proxycore.runtime import Runtime
+
+from .probe import describe_listener, probe_http_proxy, probe_socks5
+
+DEFAULT_PORT = 8848  # Yakit 常用；Burp 8080、Charles 8888 自己传 --port
+DEFAULT_SINK_PORT = 19080
+PROBE_TARGET = ("www.baidu.com", 80)  # 只用来握一次手，不下载内容
+UPSTREAM_ALIAS = "capture"
+
+# 这些网段永远直连：代理它们没有意义，还会把内网探测流量灌进抓包工具。
+PRIVATE_RANGES = "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.0/8,169.254.0.0/16"
+
+
+def _default_out_dir() -> pathlib.Path:
+    """生成配置的默认落盘目录（`<仓库根>/build/proxy-process/`；已安装场景退回 cwd）。"""
+    from .cli import repo_root
+
+    root = repo_root() or pathlib.Path.cwd()
+    return root / "build" / "proxy-process"
+
+
+# ------------------------------------------------------------------ 小工具 ----
+def _harden_stdout() -> None:
+    """输出被重定向时（管道/文件）Python 用 locale 编码（中文 Windows 是 GBK），
+    碰上一个编不出的字符就抛 UnicodeEncodeError 把脚本打死，比乱码严重得多。
+    本文件的字符都挑过（GBK 全覆盖），这里再兜一层：编不出就退化成 '?'。"""
+    for stream in (sys.stdout, sys.stderr):
+        with contextlib.suppress(Exception):  # 老解释器/被重定向时可能没有 reconfigure
+            stream.reconfigure(errors="replace")  # type: ignore[union-attr]
+
+
+def _is_admin() -> bool:
+    if os.name != "nt":
+        return False
+    import ctypes
+
+    try:
+        return bool(ctypes.windll.shell32.IsUserAnAdmin())
+    except Exception:  # noqa: BLE001 - 探测失败一律按"不是管理员"处理，宁可多报一次
+        return False
+
+
+def _port_busy(host: str, port: int) -> bool:
+    # 与 config.port_in_use 共用实现（Windows 上 SO_REUSEADDR 会漏判占用）。
+    return port_in_use(port, host)
+
+
+def _pick_sink_port(host: str, preferred: int) -> tuple[int, str]:
+    """sink 是本地入口，占用冲突很常见（上一次没退干净）。换一个比报错友好。"""
+    if not _port_busy(host, preferred):
+        return preferred, ""
+    for candidate in range(preferred + 1, preferred + 40):
+        if not _port_busy(host, candidate):
+            return candidate, f"端口 {preferred} 被占用，改用 {candidate}"
+    return preferred, ""  # 全占了就交给启动时报错，别在这里猜
+
+
+def _split_names(values: list[str]) -> list[str]:
+    """`--process a --process b` 与 `--process "a;b,c"` 两种写法都收。"""
+    out: list[str] = []
+    for chunk in values:
+        for piece in chunk.replace(",", ";").split(";"):
+            name = piece.strip()
+            if name and name not in out:
+                out.append(name)
+    return out
+
+
+def _human_bytes(n: int) -> str:
+    step = float(n)
+    for unit in ("B", "KB", "MB", "GB"):
+        if step < 1024 or unit == "GB":
+            return f"{step:.0f}{unit}" if unit == "B" else f"{step:.1f}{unit}"
+        step /= 1024
+    return f"{step:.1f}GB"
+
+
+def _running_names() -> dict[str, list[int]]:
+    """当前在跑的进程：名字 → pid 列表。没装 psutil 就返回空表（绝不因此报错）。
+
+    psutil 本来是路线 A 的依赖之一，但不是所有环境都装了，这只是个提示功能，
+    拿不到就当没有，不能因此让入口脚本跑不起来。
+    """
+    try:
+        import psutil
+    except ImportError:
+        return {}
+    out: dict[str, list[int]] = {}
+    for proc in psutil.process_iter(["name", "pid"]):
+        try:
+            name = str(proc.info.get("name") or "")
+            pid = int(proc.info.get("pid") or 0)
+        except Exception:  # noqa: BLE001 - 单个进程取不到就跳过（权限/竞态都常见）
+            continue
+        if name and pid:
+            out.setdefault(name, []).append(pid)
+    return out
+
+
+def _check_names(names: list[str], running: dict[str, list[int]]) -> list[str]:
+    """点名了、但当前没有同名进程在跑：这是最常见的失败原因。
+
+    微信尤其容易踩：3.x 叫 `WeChat.exe`、4.x 叫 `Weixin.exe`；而规则里的精确名字
+    比的是完整 exe 名（`Weixin` 不匹配 `Weixin.exe`，实测确认）。所以这里主动提示形似名字，
+    省得用户盯着"走代理 0 条"猜半天。
+    """
+    if not running:
+        return []
+    hints: list[str] = []
+    for pattern in names:
+        if any(fnmatch.fnmatchcase(name.lower(), pattern.lower()) for name in running):
+            continue
+        stem = pattern.lower()[:-4] if pattern.lower().endswith(".exe") else pattern.lower()
+        similar = sorted(name for name in running if stem and stem in name.lower())
+        line = f"  [!] 当前没有进程叫 {pattern!r}"
+        if similar:
+            shown = "、".join(f"{name}({running[name][0]})" for name in similar[:4])
+            line += f"\n     形似的：{shown}"
+            if stem == pattern.lower():
+                line += "  ← 规则比的是完整 exe 名，写全（带 .exe）或用通配符"
+        hints.append(line)
+    return hints
+
+
+class _RunLedger:
+    r"""本次运行新产生的 `session_end` 记录合计（条数 + 上下行字节）。
+
+    为什么要自己数：`sessions.stats()` 里的 `bytes_up/bytes_down` 只统计此刻还活着
+    的会话（`sum(s.bytes_up for s in self._sessions.values())`，见 tunnel/sessions.py），
+    连接一关就归零。于是状态行会打印出"走代理 1 条 ｜ 字节 ↑0B ↓0B"这种自相矛盾的东西
+   ，实测一次 curl 明明过了 727KB，显示的却是 0B。
+
+    这里改成从 jsonl 里累加本次运行之后新写入的那些行，单调递增，和真实转发量对得上。
+    用二进制偏移量续读，避免文本模式 seek 的编码坑；半行（日志正在写）留到下一轮。
+
+    注意：jsonl 是按用户全局共享的（`%ProgramData%\ProcProxy\sessions.jsonl`）。
+    如果同时跑着第二个 ProcProxy 实例，它的 session_end 也会被算进来。
+    """
+
+    def __init__(self, path: str) -> None:
+        self.path = pathlib.Path(path)
+        self._lock = threading.Lock()
+        self._offset = self.path.stat().st_size if self.path.exists() else 0
+        self.count = 0
+        self.up = 0
+        self.down = 0
+
+    def refresh(self) -> None:
+        with self._lock:
+            try:
+                size = self.path.stat().st_size
+            except OSError:
+                return
+            if size < self._offset:  # 日志被轮转/清空过，从头再来
+                self._offset = 0
+            if size == self._offset:
+                return
+            try:
+                with open(self.path, "rb") as handle:
+                    handle.seek(self._offset)
+                    for raw in handle:
+                        if not raw.endswith(b"\n"):  # 半行：日志还在写，下轮再读
+                            break
+                        self._offset += len(raw)
+                        try:
+                            rec = json.loads(raw.decode("utf-8", "replace"))
+                        except ValueError:  # 不是 JSON 就当没看见，绝不因此打断转发
+                            continue
+                        if rec.get("event") != "session_end":
+                            continue
+                        self.count += 1
+                        self.up += int(rec.get("bytes_up") or 0)
+                        self.down += int(rec.get("bytes_down") or 0)
+            except OSError:  # 读日志失败只是统计不准，绝不能影响正在跑的转发
+                return
+
+
+# ------------------------------------------------------------------ 上游自检 ----
+def _probe_upstream(host: str, port: int, kind: str, timeout: float) -> tuple[str, str]:
+    """判断这个端口能不能当上游，并返回该用哪种协议。
+
+    为什么要先探：ProcProxy 的上游是"代理协议客户端"，不是裸端口转发。
+    抓包工具若只是普通 Web 服务，配置看着没错但每条连接都握手失败
+    那种失败在几百行日志里很难看出来。
+    """
+    if kind in {"auto", "http"}:
+        ok, detail = probe_http_proxy(host, port, PROBE_TARGET[0], PROBE_TARGET[1], timeout)
+        if ok:
+            return "http", detail
+        if kind == "http":
+            return "", detail
+        http_detail = detail
+    else:
+        http_detail = "（未试）"
+
+    if kind in {"auto", "socks5"}:
+        ok, detail = probe_socks5(host, port, timeout)
+        if ok:
+            return "socks5", detail
+        if kind == "socks5":
+            return "", detail
+        # 两种都失败：把各自的原因都报出来。两个 detail 必须分开放，
+        # 混用会让"HTTP 失败"后面跟着一句 socks5 的报错，看日志的人会查错方向。
+        return "", f"HTTP 代理语义: {http_detail} ／ SOCKS5 握手: {detail}"
+    return "", http_detail
+
+
+# ------------------------------------------------------------------ 配置生成 ----
+def build_config_doc(
+    *,
+    names: list[str],
+    upstream_host: str,
+    upstream_port: int,
+    kind: str,
+    sink_host: str,
+    sink_port: int,
+    backend: str,
+    log_level: str,
+    trace_payload: bool,
+) -> dict[str, Any]:
+    """生成配置。只写必要项：改动越少，出问题时越容易看懂。"""
+    return {
+        "version": 1,
+        "service": {
+            "sink": {"host": sink_host, "port": sink_port},
+            "backend": backend,
+            "max_sessions": 4000,
+            "loop_breaker": {"window_s": 5, "threshold": 50},
+            # 查不到进程归属时直连：不猜、不把别人的流量也拖进抓包工具。
+            "on_unknown_pid": "direct",
+            # 决策抛异常时不放行，放行等于漏真实 IP。
+            "on_decide_error": "block",
+            "log_level": log_level,
+            "enable_trace_payload": trace_payload,
+        },
+        "profile": {
+            "name": "capture-one-process",
+            # 没点名的进程一律直连。别改成 proxy：那会把整机流量灌进抓包工具，
+            # 真正要看的那条会被淹掉，抓包工具也可能被压垮。
+            "default_action": "direct",
+            "sticky_per_pid": True,
+            "handle_services": False,
+            "handle_other_users": False,
+            "dns_mode": "remote",
+        },
+        "upstreams": [
+            {
+                "alias": UPSTREAM_ALIAS,
+                "kind": kind,
+                "host": upstream_host,
+                "port": upstream_port,
+                "auth": "none",
+                # HTTP 代理没有 UDP ASSOCIATE；置 false 是明确的，不靠默认值。
+                "udp": False,
+            }
+        ],
+        "rules": [
+            # ① 私网直连，优先级最高：内网地址走代理没有意义。
+            {"id": "r-private-direct", "action": "direct", "targets": "*", "dst_ip": PRIVATE_RANGES},
+            # ② 点名进程 → 走抓包工具。
+            {"id": "r-watch", "action": "proxy", "upstream": UPSTREAM_ALIAS,
+             "targets": ";".join(names), "dst_port": "*"},
+            # ③ 其余由 profile.default_action = direct 兜底，不另写规则。
+        ],
+    }
+
+
+def _write_config(doc: dict[str, Any], out_path: pathlib.Path) -> str:
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(
+        yaml.safe_dump(doc, allow_unicode=True, sort_keys=False, default_flow_style=False),
+        encoding="utf-8",
+    )
+    return str(out_path)
+
+
+def _arm_timer(seconds: float) -> None:
+    """到点往主线程抛 KeyboardInterrupt：走的就是按 Ctrl+C 的同一条分支，
+    而不是另写一套停止逻辑（那样就等于测了个假东西）。"""
+
+    def _fire() -> None:
+        _thread.interrupt_main()
+
+    timer = threading.Timer(seconds, _fire)
+    timer.daemon = True
+    timer.start()
+
+
+# ------------------------------------------------------------------ 状态行 ----
+def _heartbeat(runtime: Runtime, ledger: _RunLedger, stop: threading.Event, every: float) -> None:
+    """定期打一行总账。只读快照，不碰任何热路径。"""
+    last = ""
+    while not stop.wait(every):
+        try:
+            snap = runtime.snapshot()
+        except Exception:  # noqa: BLE001 - 统计失败绝不能让运行中的服务受影响
+            continue
+        ledger.refresh()
+        backend_stats = snap.get("backend") or {}
+        sessions = snap.get("sessions") or {}
+        line = (
+            f"走代理 {sessions.get('created', 0)} 条（活跃 {sessions.get('active', 0)}）"
+            # backend 的 captured 是全机 TCP 连接数：规则只管点名进程，别的连接
+            # 只是被驱动看见后原样放行。不写清楚的话，用户会以为"抓到 22 条"是微信的。
+            f" ｜ 本机 TCP 路过 {backend_stats.get('captured', 0)} 条"
+            f"（其中直连放行 {backend_stats.get('direct', 0)}）"
+            f" ｜ 阻断 {backend_stats.get('blocked', 0)}"
+            f" ｜ 累计 ↑{_human_bytes(ledger.up)} ↓{_human_bytes(ledger.down)}"
+        )
+        if line != last:  # 没变化就不刷屏
+            print(f"  [状态] {line}", flush=True)
+            last = line
+
+
+# ------------------------------------------------------------------ 主流程 ----
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    ap = argparse.ArgumentParser(prog="procproxy forward",
+        description="把指定进程的 TCP 流量转发给抓包工具（Yakit / Burp / Charles …）",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "例子：\n"
+            "  python procproxy.py WeChat.exe --port 8848\n"
+            "  python procproxy.py Weixin.exe WeChatAppEx.exe --port 8848\n"
+            "  python procproxy.py WeChat.exe --port 8848 --check-only\n"
+        ),
+    )
+    ap.add_argument("--process", action="append", default=[], required=True,
+                    help="要抓的进程名，可重复；也支持 'a.exe;b.exe' 一次给多个。支持 * 通配符")
+    ap.add_argument("--port", type=int, default=DEFAULT_PORT, help=f"抓包工具的监听端口（默认 {DEFAULT_PORT}）")
+    ap.add_argument("--upstream-host", default="127.0.0.1",
+                    help="抓包工具所在主机。写 IP 不要写域名：环路守卫按字面量比对上游端点")
+    ap.add_argument("--kind", choices=["auto", "http", "socks5"], default="auto",
+                    help="上游代理协议。auto = 两种都探一次（默认）")
+    ap.add_argument("--backend", default="windivert", choices=["windivert", "null"],
+                    help="windivert = 真抓包改道（需管理员）；null = 不抓包只联调")
+    ap.add_argument("--sink-port", type=int, default=DEFAULT_SINK_PORT, help="本地 sink 端口（被占用时自动 +1）")
+    ap.add_argument("--log-level", default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR"])
+    ap.add_argument("--trace-payload", action="store_true", help="把 payload 也记进日志（含内容，注意隐私）")
+    ap.add_argument("--status-every", type=float, default=10.0, help="状态行间隔秒数；0 = 不打")
+    ap.add_argument("--duration", type=float, default=0.0,
+                    help="跑满 N 秒后自动停（等价于按 Ctrl+C）；0 = 一直跑到 Ctrl+C。做演示/自动化用")
+    ap.add_argument("--config-out", default="", help="生成配置的落盘路径（默认 build/proxy-process/）")
+    ap.add_argument("--check-only", action="store_true",
+                    help="只做自检 + 生成配置并打印，不启动、不改任何流量、不需要管理员")
+    ap.add_argument("--skip-probe", action="store_true", help="跳过上游端口探测（确认过端口没问题时用）")
+    return ap.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    _harden_stdout()
+    args = _parse_args(argv)
+    names = _split_names(args.process)
+
+    print()
+    print("=" * 78)
+    print(" 把进程流量转发给抓包工具")
+    print("=" * 78)
+    print(f"  目标进程 : {'; '.join(names)}")
+    print(f"  上游     : {args.upstream_host}:{args.port}  (协议 {args.kind})")
+    print(f"  后端     : {args.backend}")
+    if args.backend == "null":
+        print("             [!] backend=null 不抓包、不改道，只验证转发链路")
+    print()
+
+    # ---------------------------------------------------------- ① 权限自检
+    admin = _is_admin()
+    print("[1/5] 权限")
+    if args.backend == "windivert":
+        if admin:
+            print("  [ok] 管理员")
+        elif args.check_only:
+            print("  · 非管理员（--check-only 不需要，继续）")
+        else:
+            print("  [!!] 不是管理员。路线 A 要靠 WinDivert 驱动抓包，必须管理员。")
+            print("     → 右键 PowerShell「以管理员身份运行」后重试")
+            print("     → 只想先看配置：加 --check-only")
+            return 2
+    else:
+        print(f"  · 后端 {args.backend}：{'管理员' if admin else '非管理员'}")
+
+    # ---------------------------------------------------------- ② 上游自检
+    print()
+    print("[2/5] 上游端口自检（抓包工具是不是在'代理监听'模式）")
+    print(f"  谁在监听 {args.upstream_host}:{args.port}：{describe_listener(args.upstream_host, args.port)}")
+    kind = args.kind
+    if kind == "auto":
+        kind = "http"  # 探测失败时按 http 记录，下面的分支会给出真实结论
+    if args.skip_probe:
+        print("  · 已用 --skip-probe 跳过")
+    else:
+        kind, detail = _probe_upstream(args.upstream_host, args.port, args.kind, 5.0)
+        if not kind:
+            print(f"  [!!] 这个端口不能当上游：{detail}")
+            print()
+            print("  常见原因与处理：")
+            print("    · 端口填错 / 抓包工具没开监听 → 在抓包工具里确认 MITM 监听端口")
+            print("    · 那是 Web 管理端口而不是代理端口 → 找'代理/MITM 劫持'那个监听口")
+            print("    · 它要求代理认证 → 本脚本暂不支持带认证的上游，先在工具里关掉认证")
+            print("    · 确认过没问题只是想先跑起来 → 加 --skip-probe")
+            return 3
+        print(f"  [ok] 判为 {kind} 代理：{detail}")
+    print("  （这次探测会在抓包工具里留下一条到 "
+          f"{PROBE_TARGET[0]}:{PROBE_TARGET[1]} 的 CONNECT，属正常）")
+
+    # ---------------------------------------------------------- ③ 生成配置
+    print()
+    print("[3/5] 生成配置")
+    sink_host = "127.0.0.1"
+    sink_port, note = _pick_sink_port(sink_host, args.sink_port)
+    if note:
+        print(f"  · {note}")
+
+    doc = build_config_doc(
+        names=names,
+        upstream_host=args.upstream_host,
+        upstream_port=args.port,
+        kind=kind,
+        sink_host=sink_host,
+        sink_port=sink_port,
+        backend=args.backend,
+        log_level=args.log_level,
+        trace_payload=args.trace_payload,
+    )
+    if args.config_out:
+        out_path = pathlib.Path(args.config_out)
+    else:
+        stem = "-".join(n.split(".")[0] for n in names[:3]) or "watch"
+        out_path = _default_out_dir() / f"procproxy-{stem}.yaml"
+    cfg_path = _write_config(doc, out_path)
+    print(f"  写入 {cfg_path}")
+
+    try:
+        config = Config.load(cfg_path)  # 走一遍真校验：能加载 = 配置是合法的
+    except ConfigError as exc:
+        print(f"  [!!] 生成的配置没通过校验（这是脚本的 bug，请把上面那段贴给我）：{exc}")
+        return 4
+
+    print("  生效的规则：")
+    for rule in config.profile.rules:
+        target = f" → {rule.upstream}" if rule.upstream else ""
+        print(f"    {rule.id:<18} {rule.action.value:<6} targets={rule.targets!r} dst_ip={rule.dst_ip!r}{target}")
+    print(f"    （其余一律 {config.profile.default_action.value}）")
+
+    print()
+    print("[3.5/5] 点名进程在不在跑")
+    running = _running_names()  # 只枚举一次，别为了打印重复扫进程表
+    if not running:
+        print("  · 装个 psutil 就能顺手检查进程名（pip install psutil）；现在跳过")
+    else:
+        for name in names:
+            hit = sorted(n for n in running if fnmatch.fnmatchcase(n.lower(), name.lower()))
+            if hit:
+                print(f"  [ok] {name}：{', '.join(f'{n}({running[n][0]})' for n in hit[:3])}")
+        hints = _check_names(names, running)
+        for line in hints:
+            print(line)
+        if hints:
+            print("      （进程还没启动也没关系：规则按名字匹配，等它起来照样命中）")
+
+    if args.check_only:
+        print()
+        print("[check-only] 到此为止：没有启动、没有改任何流量")
+        print()
+        print("  去掉 --check-only 就是真跑。也可以先看一条模拟连接会命中哪条规则：")
+        print(f"    python -m proxycore rules --config \"{cfg_path}\" --trace "
+              f"--proc {names[0]} --dst 1.2.3.4 --port 443")
+        return 0
+
+    # ---------------------------------------------------------- ④ 起数据面
+    print()
+    print("[4/5] 启动数据面（Ctrl+C 停止）")
+    jsonl_path = str(runtime_dir() / "sessions.jsonl")
+    # 必须在起运行时先记住日志当前位置：本次运行的字节数=之后新增的那些行。
+    ledger = _RunLedger(jsonl_path)
+    build_logger("proxycore", level=config.service.log_level, jsonl_path=jsonl_path, console=True)
+    for child in ("runtime", "config", "sink", "upstream", "dns", "backend"):
+        get_logger(f"proxycore.{child}")
+
+    try:
+        backend = make_backend(config.service.backend, config=config)
+    except BackendUnavailable as exc:
+        # 绝不静默直连：装不了就明确报错收工。
+        print(f"  [!!] [E_BACKEND_UNAVAILABLE] {exc}", file=sys.stderr)
+        print("    路线 A 需要：Windows + 管理员 + pip install pydivert psutil", file=sys.stderr)
+        return 5
+
+    # ---- 数据面启动点：以上全是探测与生成配置，真正的运行时从这里开始 ----
+    runtime = Runtime(manager=ConfigManager(config), backend=backend)
+    runtime.start()
+
+    print()
+    print("  [ok] 已在运行。现在去操作那个进程（比如发一条微信消息），然后看：")
+    print("      抓包工具 : 应该出现 CONNECT 目标:端口 以及随后的报文")
+    print("      本终端   : 每条代理连接结束会打一行 session_end")
+    print()
+    print("  [!] UDP（含 QUIC）抓不到 —— 路线 A 的过滤器只抓 TCP，这部分流量直连出去。")
+    print()
+
+    stop_beat = threading.Event()
+    beat: threading.Thread | None = None
+    if args.status_every > 0:
+        beat = threading.Thread(target=_heartbeat, args=(runtime, ledger, stop_beat, args.status_every),
+                                name="ppx-status", daemon=True)
+        beat.start()
+    if args.duration > 0:
+        print(f"  （--duration {args.duration:g}：跑满就自己停）")
+        _arm_timer(args.duration)
+
+    try:
+        runtime.serve_forever()
+    except KeyboardInterrupt:
+        print("\n  收到停止信号，正在收尾…")
+    finally:
+        stop_beat.set()
+        with contextlib.suppress(Exception):
+            runtime.stop()
+
+    # ---------------------------------------------------------- ⑤ 收尾
+    print()
+    print("[5/5] 已停止")
+    ledger.refresh()
+    with contextlib.suppress(Exception):
+        snap = runtime.snapshot()
+        sessions = snap.get("sessions") or {}
+        print(f"  本次走代理 {sessions.get('created', 0)} 条连接（其中 "
+              f"{ledger.count} 条已结束并记账），"
+              f"字节 ↑{_human_bytes(ledger.up)} ↓{_human_bytes(ledger.down)}")
+        print(f"  会话明细（每条连接的 pid/进程/目标/上游/规则/字节数）：{jsonl_path}")
+        print(f"    python -m proxycore sessions --log \"{jsonl_path}\" --limit 50")
+    print(f"  本次生效的配置：{cfg_path}")
+    return 0
+
+if __name__ == "__main__":  # pragma: no cover - 也支持以模块方式直接运行
+    raise SystemExit(main())