procproxy 0.1.4.1__tar.gz → 0.1.4.2__tar.gz

{procproxy-0.1.4.1/src/procproxy.egg-info → procproxy-0.1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: procproxy
-Version: 0.1.4.1
+Version: 0.1.4.2
 Summary: ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理
 Author: Longersking
 License-Expression: MIT
@@ -507,6 +507,24 @@ finally:
 `start_proxy()` 会启动后台维护线程；`run_forever()` 会阻塞到 Ctrl+C。
 请在主线程使用，并在退出时 `stop()`（或使用 `with`）。
 
+### 后台常驻（父进程可退出）
+
+```python
+from proxycore.api import get_status, start_proxy, stop_proxy
+
+bg = start_proxy("D:/cfg/chrome.yaml", background=True)
+print(bg.pid, bg.config_path, bg.runtime_dir)
+# 父进程可以退出；独立子进程继续运行
+
+print(get_status(bg.runtime_dir))   # 跨进程读 state.json
+print(stop_proxy(bg.runtime_dir))   # 写 control.json 并等待退出
+```
+
+- 状态目录默认 `~/.procproxy-app`（可用 `runtime_dir=` 或 `PROCPROXY_RUNTIME_DIR` 覆盖）
+- 文件协议：`state.json`（数据面写）、`control.json`（应用写 `stop`/`panic`）
+- `start_proxy(background=True, replace=True)` 可替换同目录下已在跑的数据面
+- 子进程继承父进程权限；`backend="windivert"` 仍需管理员启动
+
 ### 错误处理
 
 配置 / 后端 / 启动失败统一抛 `ProxyStartError`，`code` 是稳定的机器可读标识：
@@ -528,6 +546,9 @@ except ProxyStartError as exc:
 | `config_version_unsupported` | `version != 1` |
 | `rule_upstream_missing` 等 | 规则或上游校验失败（完整列表见文档） |
 | `E_BACKEND_UNAVAILABLE` | 后端不可用（未知后端、WinDivert 不可加载等） |
+| `already_running` | 后台模式同一 runtime_dir 已有存活数据面 |
+| `background_start_failed` / `background_start_timeout` | 后台子进程启动失败 / 超时 |
+| `runtime_dir_unavailable` | 后台状态目录无法创建或写入 |
 
 `api.load_config()` 同样抛 `ProxyStartError`，不是 `ConfigError`。
 
@@ -590,7 +611,7 @@ src/proxycore/          核心包
 samples/                mock 服务 + 示例配置
 examples/               纯 Python 示例（proxy_process.py / verify_sdk.py）
 docs/                   文档（00 架构 / 07 规则 / 11 排错 / 14 抓包 / 15 SDK）
-tests/                  测试套件（625 passed / 4 skipped）
+tests/                  测试套件（633 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -621,7 +642,7 @@ tests/                  测试套件（625 passed / 4 skipped）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 625 passed / 4 skipped（非管理员 Windows）
+python -m pytest -q tests/                     # 633 passed / 4 skipped（非管理员 Windows）
 python -m ruff check src tests
 python -m mypy src/proxycore
 ```

{procproxy-0.1.4.1 → procproxy-0.1.4.2}/README.md

@@ -468,6 +468,24 @@ finally:
 `start_proxy()` 会启动后台维护线程；`run_forever()` 会阻塞到 Ctrl+C。
 请在主线程使用，并在退出时 `stop()`（或使用 `with`）。
 
+### 后台常驻（父进程可退出）
+
+```python
+from proxycore.api import get_status, start_proxy, stop_proxy
+
+bg = start_proxy("D:/cfg/chrome.yaml", background=True)
+print(bg.pid, bg.config_path, bg.runtime_dir)
+# 父进程可以退出；独立子进程继续运行
+
+print(get_status(bg.runtime_dir))   # 跨进程读 state.json
+print(stop_proxy(bg.runtime_dir))   # 写 control.json 并等待退出
+```
+
+- 状态目录默认 `~/.procproxy-app`（可用 `runtime_dir=` 或 `PROCPROXY_RUNTIME_DIR` 覆盖）
+- 文件协议：`state.json`（数据面写）、`control.json`（应用写 `stop`/`panic`）
+- `start_proxy(background=True, replace=True)` 可替换同目录下已在跑的数据面
+- 子进程继承父进程权限；`backend="windivert"` 仍需管理员启动
+
 ### 错误处理
 
 配置 / 后端 / 启动失败统一抛 `ProxyStartError`，`code` 是稳定的机器可读标识：
@@ -489,6 +507,9 @@ except ProxyStartError as exc:
 | `config_version_unsupported` | `version != 1` |
 | `rule_upstream_missing` 等 | 规则或上游校验失败（完整列表见文档） |
 | `E_BACKEND_UNAVAILABLE` | 后端不可用（未知后端、WinDivert 不可加载等） |
+| `already_running` | 后台模式同一 runtime_dir 已有存活数据面 |
+| `background_start_failed` / `background_start_timeout` | 后台子进程启动失败 / 超时 |
+| `runtime_dir_unavailable` | 后台状态目录无法创建或写入 |
 
 `api.load_config()` 同样抛 `ProxyStartError`，不是 `ConfigError`。
 
@@ -551,7 +572,7 @@ src/proxycore/          核心包
 samples/                mock 服务 + 示例配置
 examples/               纯 Python 示例（proxy_process.py / verify_sdk.py）
 docs/                   文档（00 架构 / 07 规则 / 11 排错 / 14 抓包 / 15 SDK）
-tests/                  测试套件（625 passed / 4 skipped）
+tests/                  测试套件（633 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -582,7 +603,7 @@ tests/                  测试套件（625 passed / 4 skipped）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 625 passed / 4 skipped（非管理员 Windows）
+python -m pytest -q tests/                     # 633 passed / 4 skipped（非管理员 Windows）
 python -m ruff check src tests
 python -m mypy src/proxycore
 ```

{procproxy-0.1.4.1 → procproxy-0.1.4.2}/docs/15-/347/274/226/347/250/213/346/216/245/345/217/243/344/270/216SDK.md

@@ -5,8 +5,8 @@
 > 发行包名是 `procproxy`，导入名是 `proxycore`。`pip install procproxy` 同时安装
 > 库和可选的 CLI；CLI 只是库的外壳，不使用它也能完成初始化、代理、查询和停止。
 
-本文既是使用教程，也是**行为契约**。对应 `proxycore 0.1.4.1`；§10 的验收脚本
-`examples/verify_sdk.py`（25 项断言）可以直接用来检查一份实现是否与本文一致。
+本文既是使用教程，也是**行为契约**。对应 `proxycore 0.1.4.2`；§10 的验收脚本
+`examples/verify_sdk.py`（31 项断言，含后台进程）可以直接用来检查一份实现是否与本文一致。
 
 ---
 
@@ -429,7 +429,111 @@ ppx.stop()             # 或在 with 退出时自动停止
 
 停止后不再捕获新连接；已经建立的连接由关闭流程处理。
 
-### 6.7 没有管理员怎么办
+### 6.7 后台常驻：父进程退出后继续运行
+
+适合"应用只负责拉起数据面，随后退出"的场景。
+
+```python
+from proxycore.api import get_status, start_proxy, stop_proxy
+
+bg = start_proxy("D:/cfg/chrome.yaml", background=True)
+print(bg.pid)            # 后台数据面 PID
+print(bg.config_path)    # 生效配置的绝对路径
+print(bg.runtime_dir)    # state.json / control.json 所在目录
+
+# 父进程可以退出；数据面继续运行
+state = get_status(bg.runtime_dir)      # 读 state.json（跨进程、只读文件）
+result = stop_proxy(bg.runtime_dir)     # 写 control.json，等待子进程退出
+print(result.to_dict())
+```
+
+`start_proxy(background=True)` 的完整签名（其余参数与前台一致）：
+
+```python
+def start_proxy(
+    config=None,
+    *,
+    backend="",
+    sink_test_target="",
+    upstream="",
+    log_level="",
+    log_jsonl="",
+    background: bool = False,
+    runtime_dir: str | os.PathLike[str] | None = None,
+    wait_timeout_s: float = 10.0,
+    replace: bool = False,
+) -> ProxyHandle | BackgroundProxy: ...
+```
+
+返回的 `BackgroundProxy`：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `pid` | `int` | 后台数据面进程 PID |
+| `config_path` | `str` | 子进程实际加载的配置绝对路径 |
+| `runtime_dir` | `str` | 状态/控制文件目录 |
+| `state_path` | `str` | `<runtime_dir>/state.json` |
+| `control_path` | `str` | `<runtime_dir>/control.json` |
+| `log_path` | `str` | `<runtime_dir>/daemon.log`（子进程 stdout/stderr） |
+| `backend` | `str` | `null` / `windivert` |
+| `started_at` | `float` | 启动时间戳 |
+
+`BackgroundProxy.to_dict()` 返回上述字段的字典。
+
+#### 文件协议（与 CLI 完全一致）
+
+| 文件 | 方向 | 内容 |
+|---|---|---|
+| `state.json` | 数据面 → 应用 | 周期性状态；含 `pid`、`backend`、`started_at`、`config`、会话/计数等 |
+| `control.json` | 应用 → 数据面 | `{"action": "stop"}` 或 `{"action": "panic", "ts": ...}`；数据面 1 秒内消费并删除 |
+| `sessions.jsonl` | 数据面 → 应用 | 会话日志（CLI 默认路径） |
+| `daemon.log` | 数据面 → 应用 | 子进程 stdout/stderr，启动失败时看这里 |
+
+`runtime_dir` 解析顺序：
+
+1. `start_proxy(..., runtime_dir=...)` 显式参数；
+2. 环境变量 `PROCPROXY_RUNTIME_DIR`；
+3. `~/.procproxy-app`。
+
+子进程启动时会被显式设置 `PROCPROXY_RUNTIME_DIR=<解析后的绝对路径>`，
+所以父进程和应用侧的 `get_status` / `stop_proxy` 只要使用同一个目录即可。
+
+#### 行为细节
+
+- **父进程退出不影响子进程**：Windows 使用 `DETACHED_PROCESS`，POSIX 使用
+  `start_new_session=True`；子进程 stdout/stderr 重定向到 `daemon.log`；
+- **配置对象会被落盘**：传 `Config` 对象时写到 `<runtime_dir>/config.yaml`，
+  再由子进程加载；传路径时直接使用该绝对路径；
+- **重复启动**：同一 `runtime_dir` 已有存活数据面时抛
+  `ProxyStartError(code="already_running")`；`replace=True` 会先停止旧进程；
+- **启动失败**：子进程退出或超时分别抛 `background_start_failed` /
+  `background_start_timeout`，异常文本附带 `daemon.log` 最后 20 行；
+- **权限**：子进程继承父进程权限；`backend="windivert"` 仍然要求父进程以管理员启动；
+- **停止不强制杀进程**：`stop_proxy` 只写控制文件并等待；超时返回
+  `StopResult(stopped=False, reason="timeout")`，不会静默杀掉别人的进程。
+
+#### 跨进程查询/停止的独立函数
+
+```python
+from proxycore.api import get_status, is_running, resolve_runtime_dir, stop_proxy
+
+get_status(runtime_dir=None) -> dict | None   # 读 state.json；不存在/非法返回 None
+is_running(runtime_dir=None) -> bool          # state.json 的 pid 是否存活
+stop_proxy(runtime_dir=None, *, timeout_s=10.0) -> StopResult
+resolve_runtime_dir(runtime_dir=None) -> Path # 显式 → 环境变量 → ~/.procproxy-app
+```
+
+`StopResult` 字段：`stopped: bool`、`pid: int`、`runtime_dir: str`、
+`control_path: str`、`reason: str`（`stopped` / `not_running` / `timeout`）。
+
+> 你现有的 `get_status` / `stop_proxy` 只要使用同一个 `runtime_dir` 和上述
+> 文件名，就与 SDK 完全兼容；不需要改 state.json / control.json 的格式。
+>
+> CLI 的 `procproxy stop` 使用 CLI 自己的 runtime_dir；要停止 SDK 后台数据面，
+> 请设置 `PROCPROXY_RUNTIME_DIR=<runtime_dir>` 后再执行，或直接调用
+> `proxycore.api.stop_proxy(runtime_dir)`。
+
+### 6.8 没有管理员怎么办
 
 只能做联调：
 
@@ -629,6 +733,41 @@ class ProxyStartError(RuntimeError):
 
 `str(exc)` 是给人看的中文信息；程序判断请用 `exc.code`。
 
+### 7.8 后台常驻 API
+
+```python
+def start_proxy_background(
+    config: Config | str | os.PathLike[str] | None = None,
+    *,
+    backend: str = "",
+    sink_test_target: str = "",
+    upstream: str = "",
+    log_level: str = "",
+    log_jsonl: str = "",
+    runtime_dir: str | os.PathLike[str] | None = None,
+    wait_timeout_s: float = 10.0,
+    replace: bool = False,
+) -> BackgroundProxy: ...
+
+def get_status(runtime_dir=None) -> dict | None: ...
+def is_running(runtime_dir=None) -> bool: ...
+def stop_proxy(runtime_dir=None, *, timeout_s: float = 10.0) -> StopResult: ...
+def resolve_runtime_dir(runtime_dir=None) -> Path: ...
+```
+
+`start_proxy(..., background=True, runtime_dir=..., wait_timeout_s=..., replace=...)`
+是同一入口；`start_proxy_background()` 便于类型明确的调用方直接使用。
+
+异常码：
+
+| code | 触发条件 |
+|---|---|
+| `already_running` | 同一 runtime_dir 已有存活数据面，且 `replace=False` |
+| `background_start_failed` | 子进程在写出 state.json 前退出（附 daemon.log 末尾） |
+| `background_start_timeout` | 等待 state.json 超时；子进程会被终止 |
+| `runtime_dir_unavailable` | runtime_dir 无法创建/写入 |
+| `config_not_found` 等 | 配置阶段失败，与前台一致 |
+
 ---
 
 ## 8. 配置参考
@@ -783,7 +922,7 @@ udp_policy:
 ## 10. 验收清单（给实现方/文档校验）
 
 仓库里的 [`examples/verify_sdk.py`](https://github.com/Longersking/procproxy/blob/master/examples/verify_sdk.py)
-是一个 25 项断言的可执行契约：
+是一个 31 项断言的可执行契约：
 
 ```bash
 python examples/verify_sdk.py
@@ -802,7 +941,10 @@ python examples/verify_sdk.py
 9. `start_proxy(path)` 的 `config_source == "explicit"`；
 10. `status()` 含 `backend/rules/sessions/breaker/dns/udp/config_path/config_source/running`；
 11. `reload()` 返回递增的 generation；
-12. 显式路径不存在 → `ProxyStartError.code == "config_not_found"`。
+12. 显式路径不存在 → `ProxyStartError.code == "config_not_found"`；
+13. `start_proxy(background=True)` 返回 pid/config_path/runtime_dir；
+14. `get_status()` 能跨进程读到同一个 pid；
+15. `is_running()` 为 True，`stop_proxy()` 写 control.json 后变为 False。
 
 参考实现：
 
@@ -833,6 +975,10 @@ python examples/verify_sdk.py
 | `profile_option_unsupported` | `handle_services` / `handle_other_users=true` |
 | `E_BACKEND_UNAVAILABLE` | 未知后端、非管理员、驱动不可加载 |
 | `config_path_missing` | 对内存配置调用无参 `reload()` |
+| `already_running` | 后台模式同一 runtime_dir 已有存活数据面 |
+| `background_start_failed` | 后台子进程在写出 state.json 前退出 |
+| `background_start_timeout` | 后台子进程未在超时内写出 state.json |
+| `runtime_dir_unavailable` | 后台 runtime_dir 无法创建/写入 |
 
 `config_unknown_field` 只出现在 `Config.warnings`，不阻止加载。
 

{procproxy-0.1.4.1 → procproxy-0.1.4.2}/examples/verify_sdk.py

@@ -25,9 +25,12 @@ os.environ.pop("PROCPROXY_CONFIG", None)
 from proxycore import __version__  # noqa: E402
 from proxycore.api import (  # noqa: E402
     ProxyStartError,
+    get_status,
     init_config,
+    is_running,
     make_runtime,
     start_proxy,
+    stop_proxy,
 )
 from proxycore.config import Config, atomic_write  # noqa: E402
 from proxycore.types import ConnRequest, Endpoint, ProcInfo, Proto  # noqa: E402
@@ -143,6 +146,25 @@ def main() -> int:
     else:
         raise AssertionError("缺失配置未被拒绝")
 
+    # 7. 后台常驻：独立进程 + state.json / control.json
+    bg_config = write_config(work / "background.yaml", port=19135)
+    bg = start_proxy(
+        bg_config,
+        background=True,
+        runtime_dir=work / "background-rt",
+        wait_timeout_s=20.0,
+    )
+    try:
+        check("background pid", bg.pid > 0, str(bg.pid))
+        check("background config path", bg.config_path == str(bg_config.resolve()))
+        state = get_status(bg.runtime_dir)
+        check("background state pid", bool(state) and state.get("pid") == bg.pid)
+        check("background is_running", is_running(bg.runtime_dir))
+    finally:
+        result = stop_proxy(bg.runtime_dir, timeout_s=20.0)
+        check("background stopped", result.stopped, result.reason)
+    check("background not running", not is_running(bg.runtime_dir))
+
     print(f"\n全部通过：{len(PASSED)} 项检查")
     for name in PASSED:
         print(f"  [OK] {name}")

{procproxy-0.1.4.1 → procproxy-0.1.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "procproxy"
-version = "0.1.4.1"
+version = "0.1.4.2"
 description = "ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理"
 readme = "README.md"
 requires-python = ">=3.10"

{procproxy-0.1.4.1 → procproxy-0.1.4.2/src/procproxy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: procproxy
-Version: 0.1.4.1
+Version: 0.1.4.2
 Summary: ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理
 Author: Longersking
 License-Expression: MIT
@@ -507,6 +507,24 @@ finally:
 `start_proxy()` 会启动后台维护线程；`run_forever()` 会阻塞到 Ctrl+C。
 请在主线程使用，并在退出时 `stop()`（或使用 `with`）。
 
+### 后台常驻（父进程可退出）
+
+```python
+from proxycore.api import get_status, start_proxy, stop_proxy
+
+bg = start_proxy("D:/cfg/chrome.yaml", background=True)
+print(bg.pid, bg.config_path, bg.runtime_dir)
+# 父进程可以退出；独立子进程继续运行
+
+print(get_status(bg.runtime_dir))   # 跨进程读 state.json
+print(stop_proxy(bg.runtime_dir))   # 写 control.json 并等待退出
+```
+
+- 状态目录默认 `~/.procproxy-app`（可用 `runtime_dir=` 或 `PROCPROXY_RUNTIME_DIR` 覆盖）
+- 文件协议：`state.json`（数据面写）、`control.json`（应用写 `stop`/`panic`）
+- `start_proxy(background=True, replace=True)` 可替换同目录下已在跑的数据面
+- 子进程继承父进程权限；`backend="windivert"` 仍需管理员启动
+
 ### 错误处理
 
 配置 / 后端 / 启动失败统一抛 `ProxyStartError`，`code` 是稳定的机器可读标识：
@@ -528,6 +546,9 @@ except ProxyStartError as exc:
 | `config_version_unsupported` | `version != 1` |
 | `rule_upstream_missing` 等 | 规则或上游校验失败（完整列表见文档） |
 | `E_BACKEND_UNAVAILABLE` | 后端不可用（未知后端、WinDivert 不可加载等） |
+| `already_running` | 后台模式同一 runtime_dir 已有存活数据面 |
+| `background_start_failed` / `background_start_timeout` | 后台子进程启动失败 / 超时 |
+| `runtime_dir_unavailable` | 后台状态目录无法创建或写入 |
 
 `api.load_config()` 同样抛 `ProxyStartError`，不是 `ConfigError`。
 
@@ -590,7 +611,7 @@ src/proxycore/          核心包
 samples/                mock 服务 + 示例配置
 examples/               纯 Python 示例（proxy_process.py / verify_sdk.py）
 docs/                   文档（00 架构 / 07 规则 / 11 排错 / 14 抓包 / 15 SDK）
-tests/                  测试套件（625 passed / 4 skipped）
+tests/                  测试套件（633 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -621,7 +642,7 @@ tests/                  测试套件（625 passed / 4 skipped）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 625 passed / 4 skipped（非管理员 Windows）
+python -m pytest -q tests/                     # 633 passed / 4 skipped（非管理员 Windows）
 python -m ruff check src tests
 python -m mypy src/proxycore
 ```

{procproxy-0.1.4.1 → procproxy-0.1.4.2}/src/procproxy.egg-info/SOURCES.txt

@@ -18,12 +18,14 @@ src/procproxy.egg-info/top_level.txt
 src/proxycore/__init__.py
 src/proxycore/__main__.py
 src/proxycore/api.py
+src/proxycore/background.py
 src/proxycore/canproxy.py
 src/proxycore/checkroute.py
 src/proxycore/cli.py
 src/proxycore/config.py
 src/proxycore/config_init.py
 src/proxycore/config_source.py
+src/proxycore/errors.py
 src/proxycore/forward.py
 src/proxycore/ipc.py
 src/proxycore/log.py

{procproxy-0.1.4.1 → procproxy-0.1.4.2}/src/proxycore/__init__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.4.1"
+__version__ = "0.1.4.2"
 
 __all__ = ["__version__"]

{procproxy-0.1.4.1 → procproxy-0.1.4.2}/src/proxycore/api.py

@@ -49,9 +49,19 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+from .background import (
+    BackgroundProxy,
+    StopResult,
+    get_status,
+    is_running,
+    resolve_runtime_dir,
+    start_proxy_background,
+    stop_proxy,
+)
 from .config import Config, ConfigError, ConfigManager
 from .config_init import create_config_file
 from .config_source import ORIGIN_EXPLICIT, ORIGIN_OBJECT, normalize_config_path, resolve_config_source
+from .errors import ProxyStartError
 from .log import EventLogger, build_logger, get_logger
 from .runtime import Runtime
 from .types import ConnRequest, Decision
@@ -59,18 +69,6 @@ from .types import ConnRequest, Decision
 LOG = EventLogger(get_logger("proxycore.api"))
 
 
-class ProxyStartError(RuntimeError):
-    """启动失败（配置非法 / 后端不可用 / sink 端口占用）。
-
-    `code` 是稳定的机器可读标识：配置错误沿用 `ConfigError.code`
-    （如 `config_not_found`），后端不可用为 `E_BACKEND_UNAVAILABLE`。
-    """
-
-    def __init__(self, message: str, *, code: str = "") -> None:
-        super().__init__(message)
-        self.code = code
-
-
 def _wrap_config_error(exc: ConfigError) -> ProxyStartError:
     return ProxyStartError(f"配置无效：[{exc.code}] {exc.message}", code=exc.code)
 
@@ -285,17 +283,45 @@ def start_proxy(
     upstream: str = "",
     log_level: str = "",
     log_jsonl: str = "",
-) -> ProxyHandle:
-    """启动 ProcProxy 数据面（后端 + 规则 + 会话表，必要时监听 sink）。
+    background: bool = False,
+    runtime_dir: str | os.PathLike[str] | None = None,
+    wait_timeout_s: float = 10.0,
+    replace: bool = False,
+) -> ProxyHandle | BackgroundProxy:
+    """启动 ProcProxy 数据面。
+
+    前台（默认，`background=False`）：在当前进程里启动，返回 `ProxyHandle`；
+    进程退出即停止，适合 `with` / 嵌入程序 / 测试。
+
+    后台（`background=True`）：拉起独立子进程并立即返回 `BackgroundProxy`
+    （含 `pid` / `config_path` / `runtime_dir` / `state_path` / `control_path`）。
+    父进程可以退出，数据面继续运行；用 `get_status()` 查询、`stop_proxy()` 停止。
+    子进程的 `PROCPROXY_RUNTIME_DIR` 固定为解析后的 runtime_dir
+    （默认 `~/.procproxy-app`），状态/控制文件跨进程一致。
+
+    其它参数：
 
     * `config=None`：按来源优先级自动选择；pip 安装后默认使用内置配置
       （`backend=null`，不抓包、不改道），且不会创建任何文件；
-    * 返回的 `ProxyHandle` 支持 `with`，退出会自动 stop；
     * `backend=""` 用配置里的 backend；`backend="null"` 用于联调（不抓包）；
     * `sink_test_target` 非空 = 测试模式：sink 把所有连接转发到该固定目标；
       注意 backend=null 且不传 `sink_test_target`/`upstream` 时**不会**监听 sink；
-    * 后端不可用（WinDivert 不可加载/非管理员）→ 抛 `ProxyStartError`，不会静默直连。
+    * 后端不可用（WinDivert 不可加载/非管理员）→ 抛 `ProxyStartError`，不会静默直连；
+    * 后台模式的 `replace=True`：同一 runtime_dir 已有存活数据面时先停掉再启动，
+      否则抛 `already_running`。
     """
+    if background:
+        return start_proxy_background(
+            config,
+            backend=backend,
+            sink_test_target=sink_test_target,
+            upstream=upstream,
+            log_level=log_level,
+            log_jsonl=log_jsonl,
+            runtime_dir=runtime_dir,
+            wait_timeout_s=wait_timeout_s,
+            replace=replace,
+        )
     runtime = make_runtime(
         config,
         backend=backend,
@@ -325,6 +351,11 @@ def start_proxy(
 def run_forever(config: Config | str | os.PathLike[str] | None = None, **kwargs: Any) -> int:
     """启动并阻塞（等价于 `cli run`），Ctrl+C 退出。返回进程退出码。"""
     handle = start_proxy(config, **kwargs)
+    if not isinstance(handle, ProxyHandle):
+        raise ProxyStartError(
+            "run_forever 不支持 background=True；后台模式请直接调用 start_proxy(background=True)",
+            code="invalid_argument",
+        )
     try:
         handle.runtime.serve_forever(reload_watch=True)
     except KeyboardInterrupt:
@@ -335,11 +366,18 @@ def run_forever(config: Config | str | os.PathLike[str] | None = None, **kwargs:
 
 
 __all__ = [
+    "BackgroundProxy",
     "ProxyHandle",
     "ProxyStartError",
+    "StopResult",
+    "get_status",
     "init_config",
+    "is_running",
     "load_config",
     "make_runtime",
+    "resolve_runtime_dir",
     "run_forever",
     "start_proxy",
+    "start_proxy_background",
+    "stop_proxy",
 ]

procproxy-0.1.4.2/src/proxycore/background.py

@@ -0,0 +1,461 @@
+"""后台常驻数据面：独立进程 + state.json / control.json 文件协议。
+
+与前台 `start_proxy()` 的区别：
+
+* 前台：在当前进程里启动后端/线程，返回 `ProxyHandle`，进程退出即停止；
+* 后台：用当前 Python 解释器拉起一个**脱离父进程**的
+  `python -m proxycore run` 子进程，等它写出 `state.json` 后返回
+  `BackgroundProxy`。父进程可以直接退出，数据面继续跑。
+
+跨进程协议（与 CLI `stop` 完全一致）：
+
+* `<runtime_dir>/state.json`：数据面周期性写出的状态（含 `pid`）；
+* `<runtime_dir>/control.json`：外部写入 `{"action": "stop"|"panic"}`，
+  数据面在 1 秒内读取并删除，然后自行退出；
+* `<runtime_dir>/sessions.jsonl`：会话日志（CLI 默认）；
+* `<runtime_dir>/daemon.log`：子进程 stdout/stderr。
+
+`runtime_dir` 优先级：显式参数 → `PROCPROXY_RUNTIME_DIR` → `~/.procproxy-app`。
+子进程启动时会把解析后的绝对路径写入 `PROCPROXY_RUNTIME_DIR`，保证父子
+使用同一组状态文件。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .config import Config, ConfigError, atomic_write
+from .config_source import resolve_config_source
+from .errors import ProxyStartError
+
+RUNTIME_DIR_ENV = "PROCPROXY_RUNTIME_DIR"
+APP_RUNTIME_DIR = ".procproxy-app"
+STATE_FILE = "state.json"
+CONTROL_FILE = "control.json"
+LOG_FILE = "daemon.log"
+DEFAULT_WAIT_TIMEOUT_S = 10.0
+DEFAULT_STOP_TIMEOUT_S = 10.0
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundProxy:
+    """后台数据面的启动凭证。父进程退出后这些信息仍然有效。"""
+
+    pid: int
+    config_path: str
+    runtime_dir: str
+    state_path: str
+    control_path: str
+    log_path: str
+    backend: str
+    started_at: float
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "pid": self.pid,
+            "config_path": self.config_path,
+            "runtime_dir": self.runtime_dir,
+            "state_path": self.state_path,
+            "control_path": self.control_path,
+            "log_path": self.log_path,
+            "backend": self.backend,
+            "started_at": self.started_at,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class StopResult:
+    """一次停止请求的结果；`reason`: stopped / not_running / timeout。"""
+
+    stopped: bool
+    pid: int
+    runtime_dir: str
+    control_path: str
+    reason: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "stopped": self.stopped,
+            "pid": self.pid,
+            "runtime_dir": self.runtime_dir,
+            "control_path": self.control_path,
+            "reason": self.reason,
+        }
+
+
+# ------------------------------------------------------------ 路径解析 ----
+def resolve_runtime_dir(runtime_dir: str | os.PathLike[str] | None = None) -> Path:
+    """显式参数 → `PROCPROXY_RUNTIME_DIR` → `~/.procproxy-app`（绝对路径）。"""
+    raw = runtime_dir if runtime_dir is not None else os.environ.get(RUNTIME_DIR_ENV, "")
+    if raw is None or (isinstance(raw, str) and not raw.strip()):
+        path = Path.home() / APP_RUNTIME_DIR
+    else:
+        path = Path(os.path.expandvars(os.fspath(raw))).expanduser()
+    if not path.is_absolute():
+        path = (Path.cwd() / path).resolve()
+    return path.resolve()
+
+
+def state_path(runtime_dir: str | os.PathLike[str] | None = None) -> Path:
+    return resolve_runtime_dir(runtime_dir) / STATE_FILE
+
+
+def control_path(runtime_dir: str | os.PathLike[str] | None = None) -> Path:
+    return resolve_runtime_dir(runtime_dir) / CONTROL_FILE
+
+
+def log_path(runtime_dir: str | os.PathLike[str] | None = None) -> Path:
+    return resolve_runtime_dir(runtime_dir) / LOG_FILE
+
+
+# ------------------------------------------------------------ 状态读取 ----
+def get_status(runtime_dir: str | os.PathLike[str] | None = None) -> dict[str, Any] | None:
+    """读取 `state.json` 原始内容；文件不存在或非法返回 `None`。
+
+    这是跨进程查询的唯一入口：不连接子进程、不需要权限，只读文件。
+    """
+    path = state_path(runtime_dir)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def is_running(runtime_dir: str | os.PathLike[str] | None = None) -> bool:
+    """`state.json` 里的 pid 是否仍然存活。"""
+    state = get_status(runtime_dir)
+    if not state:
+        return False
+    try:
+        pid = int(state.get("pid") or 0)
+    except (TypeError, ValueError):
+        return False
+    return _pid_alive(pid)
+
+
+# ------------------------------------------------------------ 启动/停止 ----
+def start_proxy_background(
+    config: Config | str | os.PathLike[str] | None = None,
+    *,
+    backend: str = "",
+    sink_test_target: str = "",
+    upstream: str = "",
+    log_level: str = "",
+    log_jsonl: str = "",
+    runtime_dir: str | os.PathLike[str] | None = None,
+    wait_timeout_s: float = DEFAULT_WAIT_TIMEOUT_S,
+    replace: bool = False,
+) -> BackgroundProxy:
+    """拉起独立后台数据面并立即返回；父进程退出后它继续运行。
+
+    参数与 `start_proxy()` 同名参数含义一致。额外参数：
+
+    * `runtime_dir`：状态/控制文件目录；默认 `~/.procproxy-app`；
+    * `wait_timeout_s`：等待子进程写出 `state.json` 的最长时间；
+    * `replace`：发现同一 runtime_dir 已有存活数据面时，先停掉它再启动；
+      否则抛 `ProxyStartError(code="already_running")`。
+
+    `config` 传 `Config` 对象时会落到 `<runtime_dir>/config.yaml` 再由子进程读取；
+    传路径时直接使用该绝对路径。
+    """
+    root = resolve_runtime_dir(runtime_dir)
+    try:
+        root.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise ProxyStartError(
+            f"无法创建 runtime_dir {root}: {exc}", code="runtime_dir_unavailable"
+        ) from exc
+
+    _handle_existing(root, replace=replace, stop_timeout_s=wait_timeout_s)
+
+    cfg_path = _materialize_config(config, root)
+    cmd = [sys.executable, "-m", "proxycore", "run", "--config", str(cfg_path)]
+    if backend:
+        cmd += ["--backend", backend]
+    if sink_test_target:
+        cmd += ["--sink-test-target", sink_test_target]
+    if upstream:
+        cmd += ["--upstream", upstream]
+    if log_level:
+        cmd += ["--log-level", log_level]
+    if log_jsonl:
+        cmd += ["--log-jsonl", log_jsonl]
+
+    env = dict(os.environ)
+    env[RUNTIME_DIR_ENV] = str(root)
+    env["PYTHONIOENCODING"] = "utf-8"
+    env["PYTHONUNBUFFERED"] = "1"
+    # 保证子进程加载与父进程同一份 proxycore（源码树/PYTHONPATH 场景尤其需要）
+    package_root = Path(__file__).resolve().parent.parent
+    old_pythonpath = env.get("PYTHONPATH", "")
+    env["PYTHONPATH"] = str(package_root) + (os.pathsep + old_pythonpath if old_pythonpath else "")
+
+    log_file = root / LOG_FILE
+    with open(log_file, "ab", buffering=0) as log:
+        kwargs: dict[str, Any] = {
+            "stdin": subprocess.DEVNULL,
+            "stdout": log,
+            "stderr": subprocess.STDOUT,
+            "env": env,
+            "close_fds": True,
+        }
+        if os.name == "nt":
+            kwargs["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+        else:
+            kwargs["start_new_session"] = True
+        proc = subprocess.Popen(cmd, **kwargs)
+
+    # 注意：Windows venv 的 python.exe 可能是一个启动器，会再拉起真实解释器，
+    # 因此 Popen.pid 不一定等于 state.json 里的数据面 pid。就绪判断以 state.json
+    # 为准；`proc.poll()` 只用来尽早发现"子进程根本没跑起来"。
+    spawn_time = time.time()
+    deadline = time.monotonic() + max(0.1, float(wait_timeout_s))
+    while time.monotonic() < deadline:
+        ready = _background_ready(root, spawn_time, cfg_path)
+        if ready is not None:
+            return ready
+        returncode = proc.poll()
+        if returncode is not None:
+            # 启动器可能已退出、真实数据面仍在写 state；给它一个短暂的宽限。
+            time.sleep(0.3)
+            ready = _background_ready(root, spawn_time, cfg_path)
+            if ready is not None:
+                return ready
+            tail = _tail(log_file)
+            raise ProxyStartError(
+                f"后台数据面启动失败（退出码 {returncode}）\n{tail}",
+                code="background_start_failed",
+            )
+        time.sleep(0.05)
+
+    state = get_status(root)
+    state_pid = _state_pid(state)
+    _terminate(proc, state_pid)
+    raise ProxyStartError(
+        f"后台数据面在 {wait_timeout_s:.1f}s 内未写出有效 state.json；"
+        f"日志见 {log_file}",
+        code="background_start_timeout",
+    )
+
+
+def stop_proxy(
+    runtime_dir: str | os.PathLike[str] | None = None,
+    *,
+    timeout_s: float = DEFAULT_STOP_TIMEOUT_S,
+) -> StopResult:
+    """写入 control.json 请求停止，并等待子进程退出。
+
+    不强制杀进程：超时返回 `StopResult(stopped=False, reason="timeout")`，
+    调用方可以决定是否升级处理。control.json 与 CLI `procproxy stop` 同格式。
+    """
+    root = resolve_runtime_dir(runtime_dir)
+    ctrl = root / CONTROL_FILE
+    state = get_status(root)
+    if state is None:
+        return StopResult(False, 0, str(root), str(ctrl), "not_running")
+    pid = _state_pid(state)
+    if pid <= 0 or not _pid_alive(pid):
+        return StopResult(False, pid, str(root), str(ctrl), "not_running")
+
+    try:
+        _write_json_atomic(ctrl, {"action": "stop", "ts": time.time()})
+    except OSError as exc:
+        raise ProxyStartError(
+            f"无法写入控制文件 {ctrl}: {exc}", code="runtime_dir_unavailable"
+        ) from exc
+
+    deadline = time.monotonic() + max(0.1, float(timeout_s))
+    while time.monotonic() < deadline:
+        if not _pid_alive(pid):
+            return StopResult(True, pid, str(root), str(ctrl), "stopped")
+        time.sleep(0.1)
+    return StopResult(False, pid, str(root), str(ctrl), "timeout")
+
+
+# ------------------------------------------------------------ 内部工具 ----
+def _state_pid(state: dict[str, Any] | None) -> int:
+    if not state:
+        return 0
+    try:
+        return int(state.get("pid") or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _background_ready(
+    root: Path, spawn_time: float, config_path: Path
+) -> BackgroundProxy | None:
+    """state.json 是否已由本次启动的数据面写出。
+
+    不能用 `Popen.pid` 比对：Windows venv 的 python.exe 可能是启动器，
+    真正跑数据面的是它的子进程。用 pid 存活 + started_at 判断。
+    """
+    state = get_status(root)
+    pid = _state_pid(state)
+    if state is None or pid <= 0 or not _pid_alive(pid):
+        return None
+    try:
+        started_at = float(state.get("started_at") or 0.0)
+    except (TypeError, ValueError):
+        started_at = 0.0
+    # 正常情况下 _handle_existing 已清掉残留；这个判断只防极小概率的旧文件。
+    if started_at and started_at < spawn_time - 5.0:
+        return None
+    return BackgroundProxy(
+        pid=pid,
+        config_path=str(state.get("config") or config_path),
+        runtime_dir=str(root),
+        state_path=str(root / STATE_FILE),
+        control_path=str(root / CONTROL_FILE),
+        log_path=str(root / LOG_FILE),
+        backend=str(state.get("backend") or ""),
+        started_at=started_at or time.time(),
+    )
+
+
+def _handle_existing(root: Path, *, replace: bool, stop_timeout_s: float) -> None:
+    state = get_status(root)
+    if state is None:
+        return
+    pid = _state_pid(state)
+    if pid <= 0 or not _pid_alive(pid):
+        # 上次异常退出的残留：清掉状态与控制文件，避免新进程被旧指令影响
+        for path in (root / STATE_FILE, root / CONTROL_FILE):
+            with contextlib.suppress(OSError):
+                path.unlink()
+        return
+    if not replace:
+        raise ProxyStartError(
+            f"后台数据面已在运行（pid={pid}, runtime_dir={root}）；"
+            "如需替换请传 replace=True",
+            code="already_running",
+        )
+    result = stop_proxy(root, timeout_s=stop_timeout_s)
+    if not result.stopped:
+        raise ProxyStartError(
+            f"替换旧数据面失败（pid={pid}, reason={result.reason}）",
+            code="stop_timeout" if result.reason == "timeout" else "already_running",
+        )
+
+
+def _materialize_config(config: Config | str | os.PathLike[str] | None, root: Path) -> Path:
+    """把 Config 对象写成 runtime_dir/config.yaml；路径则直接校验后使用。"""
+    try:
+        if isinstance(config, Config):
+            config.validate()
+            target = root / "config.yaml"
+            atomic_write(config, target)
+            return target
+        source = resolve_config_source(config)
+        Config.load(source.path)  # 尽早失败：子进程启动前就暴露配置错误
+        return source.path
+    except ConfigError as exc:
+        raise ProxyStartError(
+            f"配置无效：[{exc.code}] {exc.message}", code=exc.code
+        ) from exc
+
+
+def _write_json_atomic(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def _pid_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    if os.name == "nt":
+        import ctypes
+
+        process_query_limited_information = 0x1000
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.OpenProcess(process_query_limited_information, False, pid)
+        if not handle:
+            return False
+        try:
+            exit_code = ctypes.c_ulong()
+            if not kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
+                return False
+            return exit_code.value == 259  # STILL_ACTIVE
+        finally:
+            kernel32.CloseHandle(handle)
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+
+
+def _tail(path: Path, lines: int = 20) -> str:
+    try:
+        content = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return ""
+    return "\n".join(content[-lines:])
+
+
+def _kill_pid(pid: int) -> None:
+    if pid <= 0 or not _pid_alive(pid):
+        return
+    if os.name == "nt":
+        import ctypes
+
+        process_terminate = 0x0001
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.OpenProcess(process_terminate, False, pid)
+        if handle:
+            try:
+                kernel32.TerminateProcess(handle, 1)
+            finally:
+                kernel32.CloseHandle(handle)
+        return
+    with contextlib.suppress(OSError):
+        os.kill(pid, 15)
+
+
+def _terminate(proc: subprocess.Popen[Any], state_pid: int = 0) -> None:
+    # 先杀 state.json 里的真实数据面（venv 启动器场景 Popen.pid 可能是另一个进程）
+    _kill_pid(state_pid)
+    with contextlib.suppress(OSError):
+        proc.terminate()
+    try:
+        proc.wait(timeout=2.0)
+        return
+    except subprocess.TimeoutExpired:
+        pass
+    with contextlib.suppress(OSError):
+        proc.kill()
+    with contextlib.suppress(subprocess.TimeoutExpired):
+        proc.wait(timeout=2.0)
+
+
+__all__ = [
+    "APP_RUNTIME_DIR",
+    "DEFAULT_STOP_TIMEOUT_S",
+    "DEFAULT_WAIT_TIMEOUT_S",
+    "RUNTIME_DIR_ENV",
+    "BackgroundProxy",
+    "StopResult",
+    "control_path",
+    "get_status",
+    "is_running",
+    "log_path",
+    "resolve_runtime_dir",
+    "start_proxy_background",
+    "state_path",
+    "stop_proxy",
+]

procproxy-0.1.4.2/src/proxycore/errors.py

@@ -0,0 +1,20 @@
+"""公共异常类型。
+
+`ProxyStartError` 独立成模块，避免 `api` 与 `background` 互相导入。
+"""
+
+from __future__ import annotations
+
+
+class ProxyStartError(RuntimeError):
+    """启动/停止失败。
+
+    `code` 是稳定的机器可读标识：配置错误沿用 `ConfigError.code`
+    （如 `config_not_found`），后端不可用为 `E_BACKEND_UNAVAILABLE`，
+    后台模式另有 `background_start_failed` / `background_start_timeout` /
+    `already_running` / `runtime_dir_unavailable`。
+    """
+
+    def __init__(self, message: str, *, code: str = "") -> None:
+        super().__init__(message)
+        self.code = code

{procproxy-0.1.4.1 → procproxy-0.1.4.2}/src/proxycore/runtime.py

@@ -130,6 +130,8 @@ class Runtime:
 
         self._maintenance = threading.Thread(target=self._maintenance_loop, name="ppx-maintenance", daemon=True)
         self._maintenance.start()
+        # 后台启动器靠 state.json 判断“已就绪”，不能等第一次周期写（最长 5s）。
+        self._write_state(reason="started")
         self.log.info(
             "runtime_started",
             backend=self.backend.name,