procproxy 0.1.0__py3-none-any.whl

proxycore/service/__init__.py

@@ -0,0 +1,536 @@
+"""服务化：Windows 服务 / systemd 单元 / systemd-like 前台。
+
+设计：
+* 数据面只跑在服务进程里：服务持有 WinDivert 句柄、sink 监听、上游连接；
+* CLI/GUI 只通过 IPC 读状态与改配置；
+* 服务在 Session 0 运行，因此"其他用户/服务"的流量也能被统一处理。
+
+崩溃自愈：进程一死，内核句柄随之释放，拦截自动失效、流量恢复直连
+这是 WinDivert 方案天然具备的性质，不需要额外写"全量放行"逻辑。
+服务重启后由本模块重新装载配置与句柄。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import signal
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..config import Config, ConfigError, ConfigManager
+from ..ipc import (
+    CMD_PANIC,
+    CMD_RELOAD,
+    CMD_RULES,
+    CMD_SESSIONS,
+    CMD_STATUS,
+    CMD_STOP,
+    IpcRequest,
+    make_server,
+    resolve_group_sid,
+)
+from ..log import EventLogger, build_logger, get_logger
+from ..proc import IS_LINUX, IS_WINDOWS
+
+LOG = EventLogger(get_logger("proxycore.service"))
+
+SERVICE_NAME = "procproxysvc"  # 服务名（自研，避免与其它产品冲突）
+SERVICE_DISPLAY = "ProcProxy Service"
+SERVICE_DESC = "ProcProxy —— 进程级代理（拦截与转发数据面）"
+
+
+@dataclass(slots=True)
+class ServiceContext:
+    """服务运行时状态（IPC handler 从这里读）。"""
+
+    manager: ConfigManager
+    runtime: Any = None
+    ipc: Any = None
+    started_at: float = field(default_factory=time.time)
+    restarts: int = 0
+    stop_requested: bool = False
+
+
+class ProcProxyService:
+    """服务主体：装配 Runtime + IPC，并处理生命周期。"""
+
+    def __init__(self, config: Config, *, backend_name: str = "") -> None:
+        self.config = config
+        self.manager = ConfigManager(config)
+        self.backend_name = backend_name or config.service.backend
+        self._stop = threading.Event()
+        self._ctx: ServiceContext | None = None
+        self._threads: list[threading.Thread] = []
+
+    # ------------------------------------------------------------ 生命周期 --
+    def start(self) -> ServiceContext:
+        from ..backend import BackendUnavailable, make_backend
+        from ..runtime import Runtime
+
+        try:
+            backend = make_backend(self.backend_name, config=self.config)
+        except BackendUnavailable as exc:
+            # 绝不静默直连，服务启动失败，并给出可操作提示
+            LOG.error(
+                "service_backend_unavailable",
+                backend=self.backend_name,
+                code=getattr(exc, "code", "E_BACKEND_UNAVAILABLE"),
+                error=str(exc),
+            )
+            raise
+
+        runtime = Runtime(self.manager, backend)
+        runtime.start()
+        ipc = make_server(allow_sids=self._allowed_ipc_sids())
+        self._register_handlers(ipc, runtime)
+        ipc.start()
+
+        self._ctx = ServiceContext(manager=self.manager, runtime=runtime, ipc=ipc)
+        self._threads.append(
+            threading.Thread(target=self._watchdog, daemon=True, name="ppx-watchdog")
+        )
+        self._threads[-1].start()
+        LOG.info(
+            "service_started",
+            service=SERVICE_NAME,
+            backend=backend.name,
+            sink=f"{self.config.service.sink.host}:{self.config.service.sink.port}",
+            session_id=os.getpid(),
+        )
+        return self._ctx
+
+    def stop(self, *, reason: str = "stop") -> None:
+        self._stop.set()
+        ctx = self._ctx
+        if ctx is None:
+            return
+        if ctx.ipc is not None:
+            ctx.ipc.stop()
+        if ctx.runtime is not None:
+            ctx.runtime.stop(reason=reason)
+        LOG.info("service_stopped", reason=reason, uptime_s=round(time.time() - ctx.started_at, 1))
+
+    def serve_forever(self) -> None:
+        self._install_signal_handlers()
+        try:
+            while not self._stop.wait(1.0):
+                pass
+        finally:
+            self.stop(reason="signal")
+
+    def _install_signal_handlers(self) -> None:
+        def handler(signum: int, _frame: Any) -> None:  # pragma: no cover - 信号路径
+            LOG.warn("service_signal", signum=signum)
+            self._stop.set()
+
+        for name in ("SIGINT", "SIGTERM"):
+            sig = getattr(signal, name, None)
+            if sig is None:
+                continue
+            with contextlib.suppress(ValueError, OSError):  # pragma: no cover
+                signal.signal(sig, handler)
+
+    def _watchdog(self) -> None:
+        """每 5s 检查后端是否还活着；后端失效 → 明确停止代理（不静默直连）。"""
+        ctx = self._ctx
+        if ctx is None:  # pragma: no cover
+            return
+        while not self._stop.wait(5.0):
+            backend = getattr(ctx.runtime, "backend", None)
+            if backend is None:
+                continue
+            if not getattr(backend, "running", False):
+                LOG.error(
+                    "backend_stopped_unexpectedly",
+                    backend=getattr(backend, "name", "?"),
+                    hint="后端句柄失效；不静默直连，服务将停止代理",
+                )
+                ctx.runtime.stop(reason="backend-lost")
+                self._stop.set()
+                return
+
+    # ------------------------------------------------------------ IPC ------
+    def _allowed_ipc_sids(self) -> tuple[str, ...]:
+        """把 `service.ipc_allow_group` 解析成 SID 列表（解析不了就不放行）。
+
+        默认配置（空）→ 返回空 → 管道 ACL 保持"只允许管理员 + SYSTEM"。
+        配了组名但解析失败（组不存在 / 拼错 / 无权限查询）→ 记 ERROR 并返回空，
+        即退回管理员专属，而不是"配了但静默不放行"或更糟的"放宽成 Everyone"。
+        """
+        group = getattr(self.config.service, "ipc_allow_group", "") or ""
+        if not group:
+            return ()
+        sid = resolve_group_sid(group)
+        if not sid:
+            LOG.error(
+                "ipc_allow_group_invalid",
+                group=group,
+                code="E_IPC_GROUP_UNRESOLVED",
+                hint="组名解析失败 → IPC 保持仅管理员可用（不放宽）",
+            )
+            return ()
+        LOG.warn(
+            "ipc_allow_group_active",
+            group=group,
+            sid=sid,
+            hint="该组的成员可连 IPC 读状态；reload/stop/panic 仍需管理员令牌",
+        )
+        return (sid,)
+
+    def _register_handlers(self, ipc: Any, runtime: Any) -> None:
+        def status(_request: IpcRequest) -> dict[str, Any]:
+            snapshot = runtime.snapshot()
+            ctx = self._ctx
+            return {
+                "service": SERVICE_NAME,
+                "pid": os.getpid(),
+                "backend": snapshot["backend"],
+                "rules": snapshot["rules"],
+                "sessions": snapshot["sessions"],
+                "breaker": snapshot["breaker"],
+                "uptime_s": round(time.time() - (ctx.started_at if ctx else time.time()), 1),
+            }
+
+        def sessions(request: IpcRequest) -> dict[str, Any]:
+            limit = int(request.args.get("limit", 50))
+            rows = [s.to_dict() for s in runtime.sessions.all()][-limit:]
+            return {"sessions": rows, "active": runtime.sessions.count()}
+
+        def rules(_request: IpcRequest) -> dict[str, Any]:
+            profile = runtime.config.profile
+            return {
+                "profile": profile.name,
+                "rules": [r.to_dict() for r in profile.rules],
+                "upstreams": sorted(profile.upstreams),
+            }
+
+        def reload(request: IpcRequest) -> dict[str, Any]:
+            path = str(request.args.get("path") or runtime.config.path)
+            try:
+                new = self.manager.reload(path)
+            except ConfigError as exc:
+                LOG.error("ipc_reload_rejected", code=exc.code, message=exc.message)
+                return {"ok": False, "error": f"[{exc.code}] {exc.message}"}
+            # 与文件监视器 / api.ProxyHandle.reload() 走同一个收口：
+            # DNS、UDP 策略、守卫、粘性迁移都必须一起换，否则重载只生效一半。
+            runtime.apply_profile()
+            LOG.info("ipc_reload_ok", rules=len(new.profile.rules), generation=self.manager.generation)
+            return {"generation": self.manager.generation, "rules": len(new.profile.rules)}
+
+        def stop(_request: IpcRequest) -> dict[str, Any]:
+            ctx = self._ctx
+            if ctx is not None:
+                ctx.stop_requested = True
+            threading.Thread(target=self.stop, kwargs={"reason": "ipc-stop"}, daemon=True).start()
+            return {"stopping": True}
+
+        def panic(_request: IpcRequest) -> dict[str, Any]:
+            """紧急停止：尽快停掉数据面，恢复直连。
+
+            注意：WinDivert 后端没有"驱动层开关"可拨，它靠句柄存活，
+            进程一退句柄就释放、拦截随之失效。所以这里只需把服务停掉。
+            """
+            LOG.warn("ipc_panic", hint="紧急停止：停掉数据面并退出")
+            threading.Thread(target=self.stop, kwargs={"reason": "panic"}, daemon=True).start()
+            return {"panic": True, "hint": "服务正在停止；进程退出后 WinDivert 句柄会自动释放"}
+
+        ipc.register(CMD_STATUS, status)
+        ipc.register(CMD_SESSIONS, sessions)
+        ipc.register(CMD_RULES, rules)
+        ipc.register(CMD_RELOAD, reload)
+        ipc.register(CMD_STOP, stop)
+        ipc.register(CMD_PANIC, panic)
+
+
+# ------------------------------------------------------- 多用户 / Session 0 -
+@dataclass(slots=True)
+class ServiceProfileDecision:
+    """`handle_services` / `handle_other_users` 的判定结果。"""
+
+    handled: bool
+    reason: str
+    profile_name: str
+
+
+def should_handle(
+    proc_session_id: int,
+    proc_user: str,
+    *,
+    service_session_id: int,
+    handle_services: bool,
+    handle_other_users: bool,
+) -> ServiceProfileDecision:
+    """决定一条"服务进程 / 其他用户"的连接要不要按本 Profile 处理。
+
+    对应 Windows 的 `ProcessServices` / `ProcessOtherUsers` 选项：
+    * Session 0 的进程 = 服务；`handle_services=false` 时不代理（只直连）；
+    * 非本服务账户 = 其他用户；`handle_other_users=false` 时不代理。
+    """
+    if proc_session_id == service_session_id == 0:
+        return ServiceProfileDecision(
+            handled=handle_services,
+            reason="service-session" if handle_services else "service-session-skipped",
+            profile_name="ServiceProfile" if handle_services else "default",
+        )
+    if proc_session_id < 0:
+        return ServiceProfileDecision(handled=False, reason="unknown-session", profile_name="default")
+    if proc_session_id == 0:
+        return ServiceProfileDecision(
+            handled=handle_services,
+            reason="session0" if handle_services else "session0-skipped",
+            profile_name="ServiceProfile" if handle_services else "default",
+        )
+    if not proc_user or proc_user.lower().endswith("system"):
+        return ServiceProfileDecision(
+            handled=handle_services,
+            reason="system-user" if handle_services else "system-user-skipped",
+            profile_name="ServiceProfile" if handle_services else "default",
+        )
+    return ServiceProfileDecision(
+        handled=handle_other_users,
+        reason="other-user" if handle_other_users else "other-user-skipped",
+        profile_name="UserProfile" if handle_other_users else "default",
+    )
+
+
+# ---------------------------------------------------- Windows 服务封装 -------
+def _write_service_crash(config_path: str, exc: BaseException) -> None:
+    """把服务启动失败的完整 traceback 落盘。
+
+    服务在 Session 0 跑、没有控制台，而日志系统这时可能还没配好，异常就这么
+    凭空消失，外部只看到 SCM 报一句 `1066 服务特定错误`，完全不知道原因。
+
+    本函数把它写到 `<运行目录>/service-error.log`（`%ProgramData%\\ProcProxy\\`），
+    让"为什么起不来"变成可读的。
+    （同一个教训：失败必须写在可读的地方，不能只 DbgPrint。）
+    """
+    import traceback
+
+    try:
+        from ..cli import runtime_dir
+
+        path = runtime_dir() / "service-error.log"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(f"\n===== {time.strftime('%Y-%m-%d %H:%M:%S')}  config={config_path} =====\n")
+            fh.write("".join(traceback.format_exception(type(exc), exc, exc.__traceback__)))
+    except Exception:
+        pass
+
+
+try:  # pragma: no cover - 只在 Windows + pywin32 下有意义
+    import win32service
+    import win32serviceutil
+
+    class ProcProxyServiceFramework(win32serviceutil.ServiceFramework):
+        """SCM 宿主入口：`service install` 注册的就是这个类。
+
+        为什么必须有它：SCM 要求服务映像自己按 SCM 协议握手
+        （`StartServiceCtrlDispatcher` → `ReportServiceStatus(SERVICE_RUNNING)`）。
+        直接把 `python.exe -m proxycore.service run ...` 注册成服务是不行的
+        那是个前台程序、不握手，SCM 等约 30 秒后按 **1053"服务没有及时响应启动
+        或控制请求"**把它杀掉（本机实测过）。pywin32 的 `pythonservice.exe`
+        负责握手，再回调到本类。
+        """
+
+        _svc_name_ = SERVICE_NAME
+        _svc_display_name_ = SERVICE_DISPLAY
+        _svc_description_ = SERVICE_DESC
+
+        def __init__(self, args: Any) -> None:
+            win32serviceutil.ServiceFramework.__init__(self, args)
+            self._service: ProcProxyService | None = None
+            self._stop_requested = threading.Event()
+
+        def SvcStop(self) -> None:
+            # 不能在 SCM 的回调里阻塞：立刻进 STOP_PENDING，再把停止丢给线程
+            self.ReportServiceStatus(win32service.SERVICE_STOP_PENDING)
+            self._stop_requested.set()
+            service = self._service
+            if service is not None:
+                threading.Thread(
+                    target=service.stop, kwargs={"reason": "service-stop"}, daemon=True
+                ).start()
+
+        def SvcDoRun(self) -> None:
+            config_path = str(
+                win32serviceutil.GetServiceCustomOption(SERVICE_NAME, "config") or ""
+            )
+            try:
+                config = Config.load(config_path)
+                build_logger(
+                    "proxycore",
+                    level=config.service.log_level,
+                    jsonl_path=config.service.log_jsonl or None,
+                    console=False,  # 服务里没有控制台
+                )
+                service = ProcProxyService(config)
+                self._service = service
+                service.start()
+                self.ReportServiceStatus(win32service.SERVICE_RUNNING)
+                if self._stop_requested.is_set():  # 起的过程中就被要求停了
+                    service.stop(reason="service-stop-before-run")
+                    return
+                service.serve_forever()
+            except Exception as exc:
+                LOG.error("service_framework_failed", config=config_path, error=str(exc))
+                _write_service_crash(config_path, exc)
+                # 必须显式告诉 SCM 失败了，不报的话它会一直以为还在启动，
+                # 最后仍以 1053 收场，而真正的错误反而看不到。
+                self.ReportServiceStatus(win32service.SERVICE_STOPPED, win32ExitCode=1066)
+except ImportError:  # pragma: no cover - 没装 pywin32
+    pass
+
+
+def install_windows_service(*, python_exe: str = "", config_path: str = "") -> tuple[bool, str]:
+    """注册 Windows 服务（需要管理员；用 `pywin32`）。
+
+     第一个参数是 `pythonClassString`（pywin32 的位置参数），注册的是
+    `ProcProxyServiceFramework`；由 `pythonservice.exe` 承载 SCM 握手。
+    原先写的是 `pythonClassString=None` + `exeName=python.exe` + `exeArgs='-m ... run'`
+   ，那等于把前台运行器注册成服务，`sc start` 必返 1053。
+    """
+    if not IS_WINDOWS:
+        return False, "仅 Windows 支持"
+    try:
+        import win32service
+        import win32serviceutil
+    except ImportError:
+        return False, "需要 pywin32（pip install pywin32）"
+    target = os.path.abspath(config_path or "samples/profiles/dev.yaml")
+    if not os.path.isfile(target):
+        return False, f"配置文件不存在：{target}"
+    try:
+        win32serviceutil.InstallService(
+            "proxycore.service.ProcProxyServiceFramework",
+            SERVICE_NAME,
+            SERVICE_DISPLAY,
+            # `SERVICE_DEMAND_START` 在 `win32service` 里，不在 `win32serviceutil`
+            # （原先写的是后者 → AttributeError，即安装路径从来没跑通过）
+            startType=win32service.SERVICE_DEMAND_START,
+            description=SERVICE_DESC,
+        )
+        # 配置路径走注册表：pythonservice.exe 只从注册表读 `PythonClass`，
+        # 额外参数用 CustomOption 带最稳（不依赖命令行/argv 的传递约定）。
+        win32serviceutil.SetServiceCustomOption(SERVICE_NAME, "config", target)
+    except Exception as exc:
+        return False, f"安装失败：{exc}（是否以管理员运行？）"
+    return True, f"已注册服务 {SERVICE_NAME}（配置：{target}）"
+
+
+def uninstall_windows_service() -> tuple[bool, str]:
+    if not IS_WINDOWS:
+        return False, "仅 Windows 支持"
+    try:
+        import win32serviceutil
+    except ImportError:
+        return False, "需要 pywin32"
+    try:
+        win32serviceutil.RemoveService(SERVICE_NAME)
+    except Exception as exc:
+        return False, f"卸载失败：{exc}"
+    return True, f"已删除服务 {SERVICE_NAME}"
+
+
+def service_status() -> tuple[bool, str]:
+    """查询服务状态（不依赖 pywin32：直接用 `sc query`）。"""
+    if not IS_WINDOWS:
+        return False, "仅 Windows 支持"
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            ["sc", "query", SERVICE_NAME],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return False, f"查询失败：{exc}"
+    out = (result.stdout or "") + (result.stderr or "")
+    running = "RUNNING" in out.upper()
+    return running, out.strip().splitlines()[0] if out.strip() else "无输出"
+
+
+SYSTEMD_UNIT = """\
+[Unit]
+Description={desc}
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart={python} -m proxycore.service run --config {config}
+Restart=on-failure
+RestartSec=2
+NoNewPrivileges=true
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+"""
+
+
+def render_systemd_unit(*, python_exe: str = "", config_path: str = "") -> str:
+    return SYSTEMD_UNIT.format(
+        desc=SERVICE_DESC,
+        python=python_exe or sys.executable,
+        config=config_path or "/etc/procproxy/config.yaml",
+    )
+
+
+def write_systemd_unit(path: str = "/etc/systemd/system/procproxy.service", **kwargs: Any) -> tuple[bool, str]:
+    if not IS_LINUX:
+        return False, "仅 Linux 支持"
+    try:
+        with open(path, "w", encoding="utf-8") as handle:
+            handle.write(render_systemd_unit(**kwargs))
+    except OSError as exc:
+        return False, f"写入失败：{exc}（是否 root？）"
+    return True, f"已写入 {path}；执行 `systemctl daemon-reload && systemctl enable --now procproxy`"
+
+
+# ------------------------------------------------------------- 入口 --------
+def run_service(config_path: str, *, backend: str = "", log_jsonl: str = "") -> int:
+    try:
+        config = Config.load(config_path)
+    except ConfigError as exc:
+        print(f"配置无效：[{exc.code}] {exc.message}", file=sys.stderr)
+        return 2
+    build_logger(
+        "proxycore",
+        level=config.service.log_level,
+        jsonl_path=log_jsonl or config.service.log_jsonl or None,
+        console=True,
+    )
+    service = ProcProxyService(config, backend_name=backend)
+    try:
+        service.start()
+    except Exception as exc:
+        print(f"服务启动失败：{exc}", file=sys.stderr)
+        return 2
+    service.serve_forever()
+    return 0
+
+
+__all__ = [
+    "SERVICE_DESC",
+    "SERVICE_DISPLAY",
+    "SERVICE_NAME",
+    "ProcProxyService",
+    "ProcProxyServiceFramework",
+    "ServiceContext",
+    "ServiceProfileDecision",
+    "install_windows_service",
+    "render_systemd_unit",
+    "run_service",
+    "service_status",
+    "should_handle",
+    "uninstall_windows_service",
+    "write_systemd_unit",
+]

proxycore/service/__main__.py

@@ -0,0 +1,124 @@
+"""`python -m proxycore.service` 入口（Windows 服务 / systemd / 前台）。
+
+用法：
+    python -m proxycore.service run --config samples/profiles/dev.yaml
+    python -m proxycore.service install --config samples/profiles/dev.yaml   # Windows
+    python -m proxycore.service status
+    python -m proxycore.service uninstall
+    python -m proxycore.service unit --config /etc/procproxy/config.yaml     # Linux systemd
+    python -m proxycore.service ipc-status                                   # 通过 IPC 查询
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from proxycore.ipc import CMD_PANIC, CMD_RELOAD, CMD_STATUS, IpcClient
+from proxycore.service import (
+    SERVICE_NAME,
+    install_windows_service,
+    run_service,
+    service_status,
+    uninstall_windows_service,
+    write_systemd_unit,
+)
+
+
+def _check_ipc_group(config_path: str) -> None:
+    """装之前先校验一遍 `service.ipc_allow_group`。
+
+    组名写错要当场报出来，而不是等服务启动后去日志里翻，那时表现是
+    "IPC 仍然只有管理员能连"，很容易被当成"配了没生效"。
+    空值 = 只允许管理员（默认行为），此时不打印任何东西。
+    """
+    try:
+        from proxycore.config import Config
+
+        config = Config.load(config_path)
+    except Exception as exc:
+        print(f"[!] 读配置失败，跳过 IPC 放行组校验：{exc}", file=sys.stderr)
+        return
+    group = getattr(config.service, "ipc_allow_group", "") or ""
+    if not group:
+        return
+    from proxycore.ipc import resolve_group_sid
+
+    sid = resolve_group_sid(group)
+    if sid:
+        print(f"[i] IPC 放行组：{group} → {sid}")
+        print("    该组成员可读状态；reload / stop / panic 仍需管理员令牌。")
+    else:
+        print(
+            f"[!] IPC 放行组 {group!r} 解析失败（组不存在？）→ 服务将只允许管理员连接",
+            file=sys.stderr,
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="proxycore.service", description="ProcProxy 服务管理")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_run = sub.add_parser("run", help="前台运行服务（调试/容器用）")
+    p_run.add_argument("--config", default="samples/profiles/dev.yaml")
+    p_run.add_argument("--backend", default="", choices=["", "null", "windivert"])
+    p_run.add_argument("--log-jsonl", default="")
+
+    p_install = sub.add_parser("install", help="注册 Windows 服务（需管理员）")
+    p_install.add_argument("--config", default="samples/profiles/dev.yaml")
+
+    sub.add_parser("uninstall", help="删除 Windows 服务（需管理员）")
+    sub.add_parser("status", help="查询服务状态")
+
+    p_unit = sub.add_parser("unit", help="生成 Linux systemd 单元")
+    p_unit.add_argument("--config", default="/etc/procproxy/config.yaml")
+    p_unit.add_argument("--write", action="store_true", help="直接写入 /etc/systemd/system/")
+
+    p_ipc = sub.add_parser("ipc-status", help="通过 IPC 查询运行中的服务")
+    p_ipc.add_argument("--cmd", default=CMD_STATUS, choices=[CMD_STATUS, CMD_RELOAD, CMD_PANIC])
+    p_ipc.add_argument("--path", default="")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "run":
+        return run_service(args.config, backend=args.backend, log_jsonl=args.log_jsonl)
+
+    if args.command == "install":
+        _check_ipc_group(args.config)
+        ok, detail = install_windows_service(config_path=args.config)
+        print(detail)
+        return 0 if ok else 1
+
+    if args.command == "uninstall":
+        ok, detail = uninstall_windows_service()
+        print(detail)
+        return 0 if ok else 1
+
+    if args.command == "status":
+        running, detail = service_status()
+        print(f"{SERVICE_NAME}: {'RUNNING' if running else 'NOT RUNNING'}")
+        print(detail)
+        return 0 if running else 1
+
+    if args.command == "unit":
+        if args.write:
+            ok, detail = write_systemd_unit(config_path=args.config)
+            print(detail)
+            return 0 if ok else 1
+        from proxycore.service import render_systemd_unit
+
+        print(render_systemd_unit(config_path=args.config))
+        return 0
+
+    if args.command == "ipc-status":
+        result = IpcClient(path=args.path).call(args.cmd)
+        import json
+
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0 if result.get("ok") else 1
+
+    return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

proxycore/tunnel/__init__.py

@@ -0,0 +1,8 @@
+"""tunnel 层：sink（本地拦截端口）、relay（双向转发）、sessions（会话表）。"""
+
+from __future__ import annotations
+
+from .relay import relay_bidirectional
+from .sessions import SessionTable
+
+__all__ = ["SessionTable", "relay_bidirectional"]