procproxy 0.1.4__tar.gz → 0.1.4.2__tar.gz

{procproxy-0.1.4/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
+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/                  测试套件（624 passed / 4 skipped）
+tests/                  测试套件（633 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -621,7 +642,7 @@ tests/                  测试套件（624 passed / 4 skipped）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 624 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 → 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/                  测试套件（624 passed / 4 skipped）
+tests/                  测试套件（633 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -582,7 +603,7 @@ tests/                  测试套件（624 passed / 4 skipped）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 624 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 → procproxy-0.1.4.2}/docs/11-/350/260/203/350/257/225/346/216/222/351/224/231/346/211/213/345/206/214.md

@@ -100,6 +100,16 @@ sc stop WinDivert                          # 极端情况：直接卸掉 WinDive
 
 > `version != 1` 仍然报 `config_version_unsupported`，与读取错误分开。
 
+### 2.9 升级 pydivert 4.0.0 后，改道成功但连接卡在 SYN_SENT
+
+| 项 | 内容 |
+|---|---|
+| 症状 | 日志有 `redirect`，但应用一直 SYN_SENT、curl 超时、sink/Yakit 收不到包；上游 0 条 CONNECT |
+| 根因 | pydivert 4.0.0 的 `send()` 默认调用 `recalculate_checksums()`，后者在 Windows 上先执行 `_populate_wd_addr()`，按**构造期缓存**重建 `WINDIVERT_ADDRESS`。旧实现先构造 `Packet` 再直接改 `wd_addr.Loopback/IfIdx`，重建时被清零 → 回环 SYN 被内核丢弃。3.1.3 不做这次重建，所以 3.x 正常 |
+| 修复 | 0.1.4.1 起：`Loopback` / `IfIdx` / `direction` 通过 `Packet(...)` 构造参数传入，并且 `send(..., recalculate_checksum=False)`（校验和已由 `pkt.py` 算好）；同时兼容 3.x / 4.x |
+| 快速确认 | `python -c "import pydivert; print(pydivert.__version__)"`；4.x 且有上述症状就升级 proxycore |
+| 临时绕过 | 不要长期 monkey patch；可在验证阶段把 pydivert 固定到 `3.1.3`，或直接使用含修复的 proxycore |
+
 ## 3. 抓包与验证技巧
 
 ```powershell

{procproxy-0.1.4 → 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`；§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 → 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 → procproxy-0.1.4.2}/pyproject.toml

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

{procproxy-0.1.4 → 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
+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/                  测试套件（624 passed / 4 skipped）
+tests/                  测试套件（633 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -621,7 +642,7 @@ tests/                  测试套件（624 passed / 4 skipped）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 624 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 → 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 → procproxy-0.1.4.2}/src/proxycore/__init__.py

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

{procproxy-0.1.4 → 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 → procproxy-0.1.4.2}/src/proxycore/backend/windivert/__init__.py

@@ -610,23 +610,25 @@ class WinDivertBackend(BaseBackend):
         if direction is None:  # pragma: no cover - start() 里已缓存
             direction = pydivert.Direction.OUTBOUND if outbound else pydivert.Direction.INBOUND
 
-        out = pydivert.Packet(raw, direction=direction)
+        # 没显式给就沿用原包的接口索引；生产路径两个方向都会显式传。
+        idx = int(self._ifidx(packet) if ifidx is None else ifidx)
+
+        # 元数据必须在构造期传入，不能事后改 wd_addr：
+        # pydivert 4.0.0 的 send() 默认会调用 recalculate_checksums()，而它在 Windows
+        # 上先执行 _populate_wd_addr()，按构造期缓存的 _loopback/_interface/_direction
+        # 重建 WINDIVERT_ADDRESS。直接写 out.wd_addr.Loopback/IfIdx 会被清零，
+        # 回环 SYN 被内核丢弃，应用卡在 SYN_SENT（3.x 不做这次重建，所以以前没暴露）。
+        out = pydivert.Packet(
+            raw,
+            interface=(idx, 0),
+            direction=direction,
+            loopback=outbound,
+        )
         # 用改写后的报文挑句柄（地址族与原始包一致，但这里的数据更权威）
         handle = self._handle_for(out) or handle
-        addr = getattr(out, "wd_addr", None)
-        if addr is not None:
-            addr.Outbound = 1 if outbound else 0
-            # 回环流量要置 Loopback 位：内核据此把它当本机回环报文处理
-            addr.Loopback = 1 if outbound else 0
-            addr.Sniffed = 0
-            addr.Impostor = 0
-            # 没显式给就沿用原包的接口索引（老行为，够用）；生产路径两个方向都会显式传
-            idx = self._ifidx(packet) if ifidx is None else ifidx
-            if idx:
-                addr.Network.IfIdx = int(idx)
-        # 校验和交给 pydivert 重算兜底（wd_addr 上的 *Checksum 标志会影响 helper 的行为，
-        # 让它自己算最稳）；我们 pkt.py 的校验和另有单测保证正确性。
-        handle.send(out)
+        # pkt.py 的 redirect/reflect 已经算好校验和；关掉 pydivert 的重算，
+        # 既避免重复计算，也避免 4.0.0 重建地址时依赖构造期缓存的隐式行为。
+        handle.send(out, recalculate_checksum=False)
 
     # ------------------------------------------------------------ 统计 -----
     def stats(self) -> dict[str, Any]: