procproxy 0.1.0__py3-none-any.whl

proxycore/config.py

@@ -0,0 +1,1010 @@
+"""Profile/Rule/Service 配置加载、校验（V1–V10）、原子热重载。
+
+负责配置 Schema 与 10 条校验规则，以及热重载的原子性
+（校验失败时保留旧配置）。
+
+设计约束：
+* 解析与校验分离（`Profile.from_dict` 只管结构，`validate()` 只管语义），便于单测；
+* 未知字段不报错，只收进 `Config.warnings`（V10 前向兼容）；
+* 热重载走 `写临时文件 → 校验 → os.replace`，任何失败都不动现网配置。
+"""
+
+from __future__ import annotations
+
+import copy
+import dataclasses
+import ipaddress
+import os
+import socket
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, ClassVar
+
+import yaml
+
+from .log import get_logger
+from .types import Action
+
+LOG = get_logger("proxycore.config")
+
+# ------------------------------------------------------------------ 错误码 ---
+E_CONFIG_VERSION_UNSUPPORTED = "config_version_unsupported"
+E_RULE_UPSTREAM_MISSING = "rule_upstream_missing"
+E_UPSTREAM_CHAIN_CYCLE = "upstream_chain_cycle"
+E_RULE_MATCH_INVALID = "rule_match_invalid"
+E_RULE_TARGETS_INVALID = "rule_targets_invalid"
+E_SINK_PORT_UNAVAILABLE = "sink_port_unavailable"
+E_LOOP_BREAKER_INVALID = "loop_breaker_invalid"
+E_DNS_MODE_INVALID = "dns_mode_invalid"
+E_RULE_ID_DUPLICATE = "rule_id_duplicate"
+E_CONFIG_UNKNOWN_FIELD = "config_unknown_field"
+E_PROFILE_OPTION_UNSUPPORTED = "profile_option_unsupported"
+# 运行时错误码
+E_BACKEND_UNAVAILABLE = "E_BACKEND_UNAVAILABLE"
+
+VALID_ACTIONS = {a.value for a in Action}
+VALID_DNS_MODES = {"local", "remote", "bypass"}
+VALID_UNKNOWN_PID_POLICIES = {"direct", "proxy", "block"}
+# 决策路径抛异常时的兜底（改道失败禁止静默直连，异常同理）。
+VALID_DECIDE_ERROR_POLICIES = {"direct", "proxy", "block"}
+VALID_UDP_POLICIES = {"direct", "proxy", "block",
+}
+VALID_UPSTREAM_KINDS = {"socks5", "socks4", "http", "https"}
+VALID_AUTHS = {"none", "basic", "ntlm", "unsupported"}
+MAX_TARGETS_LEN = 1024  # V5
+WILDCARD_LEN_LIMIT = 260  # 路径长度上限
+
+
+class ConfigError(Exception):
+    """配置校验失败。`code` 是稳定的错误码。"""
+
+    def __init__(self, code: str, message: str, *, field: str = "", value: Any = None) -> None:
+        super().__init__(f"[{code}] {message}")
+        self.code = code
+        self.message = message
+        self.field = field
+        self.value = value
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"code": self.code, "message": self.message, "field": self.field}
+
+
+# ------------------------------------------------------------------ 工具 ----
+def _as_bool(value: Any, default: bool = False) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    return bool(value)
+
+
+def _as_int(value: Any, default: int) -> int:
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except (TypeError, ValueError) as exc:
+        raise ConfigError(E_RULE_MATCH_INVALID, f"期望整数，得到 {value!r}", value=value) from exc
+
+
+def _as_mapping(value: Any, *, field: str) -> dict[str, Any]:
+    """配置节必须是映射；否则抛 `ConfigError`（而不是裸 AttributeError/ValueError）。
+
+    `Config.load()` 的契约是"任何失败抛 ConfigError、调用方保留旧配置"，
+    热重载只捕获 ConfigError，所以这里的边界检查是契约的一部分。
+    """
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ConfigError(
+            E_RULE_MATCH_INVALID, f"{field} 必须是映射，得到 {type(value).__name__}", field=field, value=value
+        )
+    return value
+
+
+def _known_fields(cls: type) -> set[str]:
+    return {f.name for f in dataclasses.fields(cls)}
+
+
+def _collect_unknown(cls: type, doc: dict[str, Any]) -> list[str]:
+    known = _known_fields(cls)
+    return sorted(k for k in doc if k not in known)
+
+
+def _split_multi(value: str, seps: str = ",;") -> list[str]:
+    out: list[str] = []
+    buf = ""
+    for ch in value:
+        if ch in seps:
+            if buf:
+                out.append(buf)
+            buf = ""
+        else:
+            buf += ch
+    if buf:
+        out.append(buf)
+    return out
+
+
+# ------------------------------------------------------------------ 上游 ----
+@dataclass(slots=True)
+class Upstream:
+    """上游配置。口令只以 `password_ref` 形式落盘。"""
+
+    alias: str
+    kind: str = "socks5"
+    host: str = ""
+    port: int = 1080
+    user: str = ""
+    password: str = ""  # 运行时解析后的明文，不序列化
+    chain: list[str] = field(default_factory=list)
+    auth: str = "none"
+    password_ref: str = ""
+    udp: bool = False
+    insecure: bool = False  # https 上游是否跳过证书校验（默认不跳过）
+
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any]) -> Upstream:
+        alias = str(doc.get("alias", "")).strip()
+        if not alias:
+            raise ConfigError(E_RULE_UPSTREAM_MISSING, "upstream 缺少 alias", field="upstreams.alias")
+        chain = doc.get("chain") or []
+        if isinstance(chain, str):
+            chain = _split_multi(chain)
+        elif not isinstance(chain, (list, tuple)):
+            raise ConfigError(
+                E_RULE_UPSTREAM_MISSING,
+                f"upstream {alias} 的 chain 必须是列表或字符串，得到 {type(chain).__name__}",
+                field="upstreams.chain",
+                value=chain,
+            )
+        auth = str(doc.get("auth", "none") or "none").lower()
+        if auth not in VALID_AUTHS:
+            raise ConfigError(E_RULE_MATCH_INVALID, f"未知 auth 类型 {auth!r}", field="upstreams.auth")
+        kind = str(doc.get("kind", "socks5")).lower()
+        if kind not in VALID_UPSTREAM_KINDS:
+            raise ConfigError(E_RULE_MATCH_INVALID, f"未知 upstream kind {kind!r}", field="upstreams.kind")
+        if auth == "ntlm":
+            # HTTP CONNECT 的 NTLM 需要 407 挑战 + 多轮 SSPI，尚未接线；
+            # 接受它只会让每条连接在运行期失败，必须在加载期明确拒绝。
+            raise ConfigError(
+                E_RULE_MATCH_INVALID,
+                "auth=ntlm 尚未实现；请改用 auth=basic，或标注 auth=unsupported",
+                field="upstreams.auth",
+            )
+        if kind == "socks4" and auth not in {"none", "unsupported"}:
+            auth = "unsupported"
+        return cls(
+            alias=alias,
+            kind=kind,
+            host=str(doc.get("host", "")),
+            port=_as_int(doc.get("port"), 1080),
+            user=str(doc.get("user", "") or ""),
+            chain=[str(c) for c in chain],
+            auth=auth,
+            password_ref=str(doc.get("password_ref", "") or ""),
+            udp=_as_bool(doc.get("udp"), default=(kind == "socks5")),
+            insecure=_as_bool(doc.get("insecure"), default=False),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "alias": self.alias,
+            "kind": self.kind,
+            "host": self.host,
+            "port": self.port,
+            "chain": list(self.chain),
+            "auth": self.auth,
+            # 始终输出：socks5 的默认值是 true，省略 `udp: false` 会在往返中反转它。
+            "udp": self.udp,
+            "insecure": self.insecure,
+        }
+        if self.user:
+            out["user"] = self.user
+        if self.password_ref:
+            out["password_ref"] = self.password_ref  # 引用，不是明文
+        return out
+
+    def resolve_password(self) -> str:
+        """按 `password_ref` 取口令：`env:` / `file:` / `dpapi:` / `keyring:`。
+
+        解析失败返回空串并记 ERROR（绝不把 hint 当口令用）。
+        """
+        if self.password:
+            return self.password
+        ref = self.password_ref
+        if not ref:
+            return ""
+        scheme, _, arg = ref.partition(":")
+        scheme = scheme.lower()
+        try:
+            if scheme == "env":
+                return os.environ.get(arg, "")
+            if scheme == "file":
+                return Path(arg).read_text(encoding="utf-8").strip()
+            if scheme == "dpapi":
+                return _dpapi_unprotect(arg)
+            if scheme == "keyring":
+                import keyring
+
+                return str(keyring.get_password("procproxy", arg) or "")
+        except Exception as exc:  # 凭据失败必须降级而不是崩溃（BLE001 已按文件豁免）
+            LOG.error(
+                "password_ref_resolve_failed",
+                extra={"event": "password_ref_resolve_failed", "fields": {"hint": scheme, "error": str(exc)}},
+            )
+            return ""
+        LOG.error(
+            "password_ref_unknown_scheme",
+            extra={"event": "password_ref_unknown_scheme", "fields": {"hint": scheme}},
+        )
+        return ""
+
+
+def _dpapi_unprotect(alias: str) -> str:
+    """Windows 用 DPAPI 解出凭据（`%ProgramData%\\ProcProxy\\creds\\<alias>.bin`）。"""
+    if os.name != "nt":
+        return ""
+    base = os.environ.get("PROGRAMDATA", r"C:\ProgramData")
+    path = Path(base) / "ProcProxy" / "creds" / f"{alias}.bin"
+    if not path.exists():
+        return ""
+    import ctypes
+    import ctypes.wintypes as wintypes
+
+    class DataBlob(ctypes.Structure):
+        _fields_ = [("cbData", wintypes.DWORD), ("pbData", ctypes.POINTER(ctypes.c_char))]
+
+    raw = path.read_bytes()
+    blob_in = DataBlob(len(raw), ctypes.cast(ctypes.create_string_buffer(raw), ctypes.POINTER(ctypes.c_char)))
+    blob_out = DataBlob()
+    crypt32 = ctypes.WinDLL("crypt32", use_last_error=True)
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    if not crypt32.CryptUnprotectData(
+        ctypes.byref(blob_in), None, None, None, None, 0, ctypes.byref(blob_out)
+    ):
+        return ""
+    try:
+        return bytes(ctypes.string_at(blob_out.pbData, blob_out.cbData)).decode("utf-8", "replace")
+    finally:
+        kernel32.LocalFree(blob_out.pbData)
+
+
+# ------------------------------------------------------------------ 规则 ----
+@dataclass(slots=True)
+class Rule:
+    id: str
+    action: Action
+    upstream: str = ""
+    targets: str = "*"
+    dst_ip: str = "*"
+    dst_port: str = "*"
+    dst_name: str = "*"
+    proto: str = "*"
+    enabled: bool = True
+    keep_private_proxied: bool = False
+
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any]) -> Rule:
+        rid = str(doc.get("id", "")).strip()
+        raw_action = str(doc.get("action", "direct")).strip().lower()
+        if raw_action not in VALID_ACTIONS:
+            raise ConfigError(E_RULE_MATCH_INVALID, f"未知 action {raw_action!r}", field=f"rules[{rid}].action")
+        proto = str(doc.get("proto", "*") or "*").strip().lower()
+        return cls(
+            id=rid,
+            action=Action(raw_action),
+            upstream=str(doc.get("upstream", "") or ""),
+            targets=str(doc.get("targets", "*") if doc.get("targets") is not None else "*"),
+            dst_ip=str(doc.get("dst_ip", "*") if doc.get("dst_ip") is not None else "*"),
+            dst_port=str(doc.get("dst_port", "*") if doc.get("dst_port") is not None else "*"),
+            dst_name=str(doc.get("dst_name", "*") if doc.get("dst_name") is not None else "*"),
+            proto=proto,
+            enabled=_as_bool(doc.get("enabled"), default=True),
+            keep_private_proxied=_as_bool(doc.get("keep_private_proxied"), default=False),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "action": self.action.value,
+            "upstream": self.upstream,
+            "targets": self.targets,
+            "dst_ip": self.dst_ip,
+            "dst_port": self.dst_port,
+            "dst_name": self.dst_name,
+            "proto": self.proto,
+            "enabled": self.enabled,
+            "keep_private_proxied": self.keep_private_proxied,
+        }
+
+
+# ---------------------------------------------------------------- Profile ---
+# 注意：不使用 slots=True，规则引擎的预编译缓存用 WeakKeyDictionary 按 Profile 缓存，
+# 热重载时旧 Profile 被回收即自动失效。
+@dataclass
+class Profile:
+    name: str
+    rules: list[Rule]
+    default_action: Action = Action.DIRECT
+    sticky_per_pid: bool = True  # 同 PID 固定上游
+    handle_services: bool = False  # ↔ ProcessServices
+    handle_other_users: bool = False  # ↔ ProcessOtherUsers
+    dns_mode: str = "remote"  # local | remote | bypass
+    dns_bypass: list[str] = field(default_factory=list)
+    upstreams: dict[str, Upstream] = field(default_factory=dict)
+    # 扩展字段：本地 DNS 走直连还是走代理，以及用哪个 DNS 服务器
+    dns_local_transport: str = "direct"  # direct；proxy 尚未实现，校验期拒绝
+    dns_local_server: str = ""  # 空 = 用系统解析器
+
+    @classmethod
+    def from_dict(
+        cls, doc: dict[str, Any], upstreams: dict[str, Upstream] | None = None
+    ) -> Profile:
+        doc = _as_mapping(doc, field="profile")
+        default_action = str(doc.get("default_action", "direct")).strip().lower()
+        if default_action not in VALID_ACTIONS:
+            raise ConfigError(
+                E_RULE_MATCH_INVALID, f"未知 default_action {default_action!r}", field="profile.default_action"
+            )
+        raw_rules = doc.get("rules") or []
+        if not isinstance(raw_rules, list):
+            raise ConfigError(E_RULE_MATCH_INVALID, "rules 必须是列表", field="profile.rules")
+        bypass = doc.get("dns_bypass") or []
+        if isinstance(bypass, str):
+            bypass = _split_multi(bypass)
+        return cls(
+            name=str(doc.get("name", "default")),
+            rules=[Rule.from_dict(r) for r in raw_rules],
+            default_action=Action(default_action),
+            sticky_per_pid=_as_bool(doc.get("sticky_per_pid"), default=True),
+            handle_services=_as_bool(doc.get("handle_services"), default=False),
+            handle_other_users=_as_bool(doc.get("handle_other_users"), default=False),
+            dns_mode=str(doc.get("dns_mode", "remote")).strip().lower(),
+            dns_bypass=[str(b) for b in bypass],
+            upstreams=dict(upstreams or {}),
+            dns_local_transport=str(doc.get("dns_local_transport", "direct")).strip().lower(),
+            dns_local_server=str(doc.get("dns_local_server", "") or ""),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "default_action": self.default_action.value,
+            "sticky_per_pid": self.sticky_per_pid,
+            "handle_services": self.handle_services,
+            "handle_other_users": self.handle_other_users,
+            "dns_mode": self.dns_mode,
+            "dns_bypass": list(self.dns_bypass),
+            "dns_local_transport": self.dns_local_transport,
+            "dns_local_server": self.dns_local_server,
+            "rules": [r.to_dict() for r in self.rules],
+        }
+
+    def upstream_endpoints(self) -> set[tuple[str, int]]:
+        """守卫 G3 用：上游代理端点集合。"""
+        return {(u.host, u.port) for u in self.upstreams.values() if u.host}
+
+    # dataclass(eq=True) 会把 __hash__ 置空；规则引擎的预编译缓存需要按身份哈希
+    # （语义上 Profile 是只读的：热重载时整体替换对象，绝不原地改字段）。
+    __hash__ = object.__hash__
+
+
+# ------------------------------------------------------------------ 服务 ----
+@dataclass(slots=True)
+class SinkConfig:
+    host: str = "127.0.0.1"
+    port: int = 19080
+
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any] | None) -> SinkConfig:
+        doc = _as_mapping(doc, field="service.sink")
+        return cls(host=str(doc.get("host", "127.0.0.1")), port=_as_int(doc.get("port"), 19080))
+
+
+@dataclass(slots=True)
+class LoopBreakerConfig:
+    window_s: float = 5.0
+    threshold: int = 50
+
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any] | None) -> LoopBreakerConfig:
+        doc = _as_mapping(doc, field="service.loop_breaker")
+        return cls(
+            window_s=float(doc.get("window_s", 5)),
+            threshold=_as_int(doc.get("threshold"), 50),
+        )
+
+
+@dataclass(slots=True)
+class UdpPolicy:
+    """：QUIC/HTTP-3 策略必须显式配置，不能默认蒙。"""
+
+    default: str = "direct"  # direct | proxy | block
+    by_port: dict[int, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any] | None) -> UdpPolicy:
+        doc = _as_mapping(doc, field="udp_policy")
+        default = str(doc.get("default", "direct")).strip().lower()
+        if default not in VALID_UDP_POLICIES:
+            raise ConfigError(E_DNS_MODE_INVALID, f"未知 udp_policy.default {default!r}", field="udp_policy.default")
+        by_port: dict[int, str] = {}
+        raw = doc.get("by_port") or {}
+        if not isinstance(raw, dict):
+            raise ConfigError(E_DNS_MODE_INVALID, "udp_policy.by_port 必须是映射", field="udp_policy.by_port")
+        for key, value in raw.items():
+            policy = str(value).strip().lower()
+            if policy not in VALID_UDP_POLICIES:
+                raise ConfigError(
+                    E_DNS_MODE_INVALID, f"未知 udp_policy.by_port[{key}]={policy!r}", field="udp_policy.by_port"
+                )
+            by_port[_as_int(key, 0)] = policy
+        return cls(default=default, by_port=by_port)
+
+    def for_port(self, port: int) -> str:
+        return self.by_port.get(port, self.default)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"default": self.default, "by_port": {str(k): v for k, v in self.by_port.items()}}
+
+
+@dataclass(slots=True)
+class ServiceConfig:
+    sink: SinkConfig = field(default_factory=SinkConfig)
+    backend: str = "windivert"  # windivert | null
+    max_sessions: int = 20000
+    loop_breaker: LoopBreakerConfig = field(default_factory=LoopBreakerConfig)
+    on_unknown_pid: str = "direct"  # direct | proxy | block
+    # 决策路径抛异常时怎么办。默认 block：异常意味着"不知道自己该干什么"，
+    # 放行等于把真实 IP 漏出去（"全代理"档下就是一次泄漏），而 block 只是这条连接失败。
+    on_decide_error: str = "block"  # direct | proxy | block
+    upstream_timeout_s: float = 15.0  # 上游握手（TCP+DNS+SOCKS5）
+    idle_timeout_s: float = 300.0  # 空闲无数据
+    half_close_timeout_s: float = 30.0  # TCP 半关闭后残留
+    udp_idle_timeout_s: float = 60.0  # UDP 会话
+    log_level: str = "INFO"
+    log_jsonl: str = ""
+    enable_trace_payload: bool = False
+    #: 允许连接 IPC 命名管道的本地组名（空 = 只有管理员 + SYSTEM，即默认行为）。
+    #: 被放行的组能读状态（status/sessions/rules）；改规则（reload）与停服务
+    #: （stop/panic）仍需管理员令牌：权限分离在 `ipc.ADMIN_ONLY_COMMANDS`，
+    #: 不靠 ACL（管道 ACL 是整体授权：能发命令就必须能写）。
+    ipc_allow_group: str = ""
+
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any] | None) -> ServiceConfig:
+        doc = dict(_as_mapping(doc, field="service"))
+        on_unknown = str(doc.get("on_unknown_pid", "direct")).strip().lower()
+        if on_unknown not in VALID_UNKNOWN_PID_POLICIES:
+            raise ConfigError(
+                E_RULE_MATCH_INVALID, f"未知 on_unknown_pid {on_unknown!r}", field="service.on_unknown_pid"
+            )
+        on_decide_error = str(doc.get("on_decide_error", "block")).strip().lower()
+        if on_decide_error not in VALID_DECIDE_ERROR_POLICIES:
+            raise ConfigError(
+                E_RULE_MATCH_INVALID,
+                f"未知 on_decide_error {on_decide_error!r}",
+                field="service.on_decide_error",
+            )
+        # `backend: null`（YAML 空值）在 PyYAML 里是 None，必须显式映射到 "null" 后端；
+        # 只有字段缺失时才回落到默认的 "windivert"。
+        raw_backend = doc.get("backend", "windivert")
+        backend = str(raw_backend).strip().lower() if raw_backend is not None else "null"
+        if backend in {"none", ""}:
+            backend = "null"
+        return cls(
+            sink=SinkConfig.from_dict(doc.get("sink")),
+            backend=backend,
+            max_sessions=_as_int(doc.get("max_sessions"), 20000),
+            loop_breaker=LoopBreakerConfig.from_dict(doc.get("loop_breaker")),
+            on_unknown_pid=on_unknown,
+            on_decide_error=on_decide_error,
+            upstream_timeout_s=float(doc.get("upstream_timeout_s", 15)),
+            idle_timeout_s=float(doc.get("idle_timeout_s", 300)),
+            half_close_timeout_s=float(doc.get("half_close_timeout_s", 30)),
+            udp_idle_timeout_s=float(doc.get("udp_idle_timeout_s", 60)),
+            log_level=str(doc.get("log_level", "INFO")),
+            log_jsonl=str(doc.get("log_jsonl", "") or ""),
+            enable_trace_payload=_as_bool(doc.get("enable_trace_payload"), False),
+            ipc_allow_group=str(doc.get("ipc_allow_group", "") or "").strip(),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "sink": {"host": self.sink.host, "port": self.sink.port},
+            "backend": self.backend,
+            "max_sessions": self.max_sessions,
+            "loop_breaker": {"window_s": self.loop_breaker.window_s, "threshold": self.loop_breaker.threshold},
+            "on_unknown_pid": self.on_unknown_pid,
+            "on_decide_error": self.on_decide_error,
+            "upstream_timeout_s": self.upstream_timeout_s,
+            "idle_timeout_s": self.idle_timeout_s,
+            "half_close_timeout_s": self.half_close_timeout_s,
+            "udp_idle_timeout_s": self.udp_idle_timeout_s,
+            "log_level": self.log_level,
+            "log_jsonl": self.log_jsonl,
+            "enable_trace_payload": self.enable_trace_payload,
+            "ipc_allow_group": self.ipc_allow_group,
+        }
+
+
+# --------------------------------------------------------------- Config -----
+@dataclass(slots=True)
+class Config:
+    version: int
+    service: ServiceConfig
+    profile: Profile
+    udp_policy: UdpPolicy = field(default_factory=UdpPolicy)
+    path: str = ""
+    raw: dict[str, Any] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+
+    _CONFIG_FIELDS: ClassVar[set[str]] = {"version", "service", "profile", "upstreams", "udp_policy"}
+
+    # ------------------------------------------------------------ 解析 ------
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any], *, path: str = "") -> Config:
+        doc = _as_mapping(doc, field="config")
+        version = _as_int(doc.get("version"), 0)
+        upstreams = _parse_upstreams(doc.get("upstreams"))
+        profile_doc = normalized_profile_doc(doc)
+        # 兼容两种排布：schema 里 rules 在 profile.* 下，samples/profiles/*.yaml 里在顶层。
+        profile_doc.setdefault("upstreams", upstreams)
+        profile = Profile.from_dict(profile_doc, upstreams)
+        config = cls(
+            version=version,
+            service=ServiceConfig.from_dict(doc.get("service")),
+            profile=profile,
+            udp_policy=UdpPolicy.from_dict(doc.get("udp_policy")),
+            path=path,
+            raw=copy.deepcopy(doc),
+        )
+        config.warnings.extend(config._unknown_field_warnings(doc))
+        return config
+
+    @classmethod
+    def load(cls, path: str | os.PathLike[str], *, check_sink: bool = False) -> Config:
+        """读取 + 解析 + 校验。任何失败抛 `ConfigError`，调用方保留旧配置。"""
+        p = Path(path)
+        try:
+            text = p.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ConfigError(E_CONFIG_VERSION_UNSUPPORTED, f"无法读取配置 {p}: {exc}") from exc
+        try:
+            doc = yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            raise ConfigError(E_CONFIG_UNKNOWN_FIELD, f"YAML 解析失败: {exc}") from exc
+        if not isinstance(doc, dict):
+            raise ConfigError(E_CONFIG_VERSION_UNSUPPORTED, "配置根节点必须是映射")
+        config = cls.from_dict(doc, path=str(p))
+        config.validate(check_sink=check_sink)
+        # 解析凭据引用（失败只记日志，不阻断加载，认证失败在拨号时归类为 E_UPSTREAM_AUTH）
+        for up in config.profile.upstreams.values():
+            up.password = up.resolve_password()
+        return config
+
+    # ------------------------------------------------------------ 校验 ------
+    def validate(self, *, check_sink: bool = False) -> None:
+        """实现 V1–V10。任一失败抛 `ConfigError`（携带错误码）。"""
+        self._validate_version()  # V1
+        self._validate_upstreams()  # V3
+        self._validate_rules()  # V2/V4/V5/V9
+        self._validate_profile_options()
+        if check_sink:
+            self._validate_sink()  # V6
+        self._validate_loop_breaker()  # V7
+        self._validate_dns()  # V8
+
+    def _validate_version(self) -> None:
+        if self.version != 1:
+            raise ConfigError(
+                E_CONFIG_VERSION_UNSUPPORTED,
+                f"只支持 version=1，当前 {self.version!r}",
+                field="version",
+                value=self.version,
+            )
+
+    def _validate_upstreams(self) -> None:
+        ups = self.profile.upstreams
+        for alias, up in ups.items():
+            if up.alias != alias:
+                raise ConfigError(
+                    E_RULE_UPSTREAM_MISSING, f"upstream 别名不一致: {alias!r} vs {up.alias!r}", field="upstreams"
+                )
+            if not up.host:
+                raise ConfigError(E_RULE_UPSTREAM_MISSING, f"upstream {alias} 缺少 host", field="upstreams.host")
+            if not (0 < up.port < 65536):
+                raise ConfigError(
+                    E_RULE_MATCH_INVALID, f"upstream {alias} 端口非法 {up.port}", field="upstreams.port"
+                )
+            for hop in up.chain:
+                if hop not in ups:
+                    raise ConfigError(
+                        E_RULE_UPSTREAM_MISSING,
+                        f"upstream {alias} 的链式跳 {hop!r} 未定义",
+                        field="upstreams.chain",
+                    )
+        self._check_chain_cycles()
+
+    def _check_chain_cycles(self) -> None:
+        ups = self.profile.upstreams
+
+        def walk(start: str) -> None:
+            seen: list[str] = []
+            node = start
+            while node:
+                if node in seen:
+                    cycle = " -> ".join([*seen, node])
+                    raise ConfigError(
+                        E_UPSTREAM_CHAIN_CYCLE, f"上游链成环: {cycle}", field="upstreams.chain", value=cycle
+                    )
+                seen.append(node)
+                if len(seen) > 8:
+                    raise ConfigError(
+                        E_UPSTREAM_CHAIN_CYCLE,
+                        f"上游链跳数超过 8（{start}）",
+                        field="upstreams.chain",
+                    )
+                up = ups.get(node)
+                node = up.chain[0] if up and up.chain else ""
+
+        for alias in ups:
+            walk(alias)
+
+    def _validate_rules(self) -> None:
+        seen: set[str] = set()
+        for rule in self.profile.rules:
+            if not rule.id:
+                raise ConfigError(E_RULE_ID_DUPLICATE, "规则缺少 id", field="rules.id")
+            if rule.id in seen:  # V9
+                raise ConfigError(E_RULE_ID_DUPLICATE, f"规则 id 重复: {rule.id}", field="rules.id", value=rule.id)
+            seen.add(rule.id)
+
+            if rule.action is Action.PROXY:  # V2
+                if not rule.upstream:
+                    raise ConfigError(
+                        E_RULE_UPSTREAM_MISSING,
+                        f"规则 {rule.id} action=proxy 但未给 upstream",
+                        field=f"rules[{rule.id}].upstream",
+                    )
+                if rule.upstream not in self.profile.upstreams:
+                    raise ConfigError(
+                        E_RULE_UPSTREAM_MISSING,
+                        f"规则 {rule.id} 引用了未定义的上游 {rule.upstream!r}",
+                        field=f"rules[{rule.id}].upstream",
+                        value=rule.upstream,
+                    )
+
+            if not rule.targets.strip():  # V5
+                raise ConfigError(
+                    E_RULE_TARGETS_INVALID, f"规则 {rule.id} 的 targets 为空", field=f"rules[{rule.id}].targets"
+                )
+            if len(rule.targets) > MAX_TARGETS_LEN:
+                raise ConfigError(
+                    E_RULE_TARGETS_INVALID,
+                    f"规则 {rule.id} 的 targets 超过 {MAX_TARGETS_LEN} 字符",
+                    field=f"rules[{rule.id}].targets",
+                )
+            for pattern in _split_multi(rule.targets, ";"):
+                if len(pattern) > WILDCARD_LEN_LIMIT:
+                    raise ConfigError(
+                        E_RULE_TARGETS_INVALID,
+                        f"规则 {rule.id} 的通配符超过 {WILDCARD_LEN_LIMIT} 字符",
+                        field=f"rules[{rule.id}].targets",
+                    )
+
+            if rule.proto not in {"*", "tcp", "udp"}:
+                raise ConfigError(
+                    E_RULE_MATCH_INVALID, f"规则 {rule.id} 的 proto 非法 {rule.proto!r}", field=f"rules[{rule.id}].proto"
+                )
+
+            _validate_ip_expr(rule)  # V4 (IP)
+            _validate_port_expr(rule)  # V4 (端口段 lo<=hi)
+
+    def _validate_profile_options(self) -> None:
+        """拒绝"已解析但尚未接入数据面"的选项。
+
+        `handle_services` / `handle_other_users` 的判定函数 `should_handle()`
+        目前只有测试在调用；接受 true 会让用户以为服务/其他用户的流量已被
+        按预期过滤，实际行为完全没变。宁可加载失败，也不做假承诺。
+        """
+        for name in ("handle_services", "handle_other_users"):
+            if getattr(self.profile, name):
+                raise ConfigError(
+                    E_PROFILE_OPTION_UNSUPPORTED,
+                    f"profile.{name}=true 尚未接入数据面（保持 false）",
+                    field=f"profile.{name}",
+                )
+
+    def _validate_sink(self) -> None:
+        sink = self.service.sink
+        if not (1024 <= sink.port <= 65535):
+            raise ConfigError(
+                E_SINK_PORT_UNAVAILABLE,
+                f"sink.port 必须在 1024-65535，当前 {sink.port}",
+                field="service.sink.port",
+                value=sink.port,
+            )
+        if port_in_use(sink.port, sink.host):
+            raise ConfigError(
+                E_SINK_PORT_UNAVAILABLE,
+                f"sink 端口 {sink.host}:{sink.port} 已被占用/不可用",
+                field="service.sink.port",
+                value=sink.port,
+            )
+
+    def _validate_loop_breaker(self) -> None:
+        lb = self.service.loop_breaker
+        if lb.threshold <= 0 or lb.window_s <= 0:
+            raise ConfigError(
+                E_LOOP_BREAKER_INVALID,
+                f"loop_breaker 必须为正数（window_s={lb.window_s}, threshold={lb.threshold}）",
+                field="service.loop_breaker",
+            )
+        if self.service.max_sessions <= 0:
+            raise ConfigError(E_LOOP_BREAKER_INVALID, "max_sessions 必须为正数", field="service.max_sessions")
+
+    def _validate_dns(self) -> None:
+        if self.profile.dns_mode not in VALID_DNS_MODES:
+            raise ConfigError(
+                E_DNS_MODE_INVALID,
+                f"未知 dns_mode {self.profile.dns_mode!r}",
+                field="profile.dns_mode",
+                value=self.profile.dns_mode,
+            )
+        if self.profile.dns_mode == "bypass" and not self.profile.dns_bypass:
+            raise ConfigError(
+                E_DNS_MODE_INVALID, "dns_mode=bypass 时 dns_bypass 不能为空", field="profile.dns_bypass"
+            )
+        if self.profile.dns_local_transport not in {"direct", "proxy"}:
+            raise ConfigError(
+                E_DNS_MODE_INVALID,
+                f"未知 dns_local_transport {self.profile.dns_local_transport!r}",
+                field="profile.dns_local_transport",
+            )
+        if self.profile.dns_local_transport == "proxy":
+            # 解析器没有接代理通道，接受它等于承诺一件做不到的事（DNS 仍会直连）。
+            raise ConfigError(
+                E_DNS_MODE_INVALID,
+                "dns_local_transport=proxy 尚未实现（本地 DNS 只能直连）；"
+                "请改用 direct 或把 dns_mode 设为 remote",
+                field="profile.dns_local_transport",
+            )
+
+    # ------------------------------------------------------- 未知字段 ------
+    def _unknown_field_warnings(self, doc: dict[str, Any]) -> list[str]:
+        """V10：未知字段只警告。"""
+        out: list[str] = []
+        for key in sorted(set(doc) - self._CONFIG_FIELDS):
+            if key in {"rules", "upstreams"}:
+                continue  # 顶层 rules/upstreams 是 samples 的等价写法，已在 from_dict 归一化
+            out.append(f"{E_CONFIG_UNKNOWN_FIELD}: 顶层未知字段 {key!r}（已忽略，前向兼容）")
+        for key in _collect_unknown(ServiceConfig, doc.get("service") or {}):
+            out.append(f"{E_CONFIG_UNKNOWN_FIELD}: service.{key} 未知（已忽略）")
+        profile_doc = normalized_profile_doc(doc)
+        for key in _collect_unknown(Profile, profile_doc):
+            out.append(f"{E_CONFIG_UNKNOWN_FIELD}: profile.{key} 未知（已忽略）")
+        for rule_doc in profile_doc.get("rules") or []:
+            if not isinstance(rule_doc, dict):
+                continue
+            for key in _collect_unknown(Rule, rule_doc):
+                out.append(
+                    f"{E_CONFIG_UNKNOWN_FIELD}: rules[{rule_doc.get('id', '?')}].{key} 未知（已忽略）"
+                )
+        return out
+
+    # ----------------------------------------------------------- 输出 ------
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "version": self.version,
+            "service": self.service.to_dict(),
+            "profile": self.profile.to_dict(),
+            "upstreams": [u.to_dict() for u in self.profile.upstreams.values()],
+            "udp_policy": self.udp_policy.to_dict(),
+        }
+
+    def dump_yaml(self) -> str:
+        return yaml.safe_dump(self.to_dict(), allow_unicode=True, sort_keys=False)
+
+
+# ------------------------------------------------------------------ 校验辅助 -
+def _validate_ip_expr(rule: Rule) -> None:
+    if rule.dst_ip.strip() in {"", "*"}:
+        return
+    for item in _split_multi(rule.dst_ip, ","):
+        item = item.strip()
+        if not item or item == "*":
+            continue
+        try:
+            if "/" in item:
+                ipaddress.ip_network(item, strict=False)
+            else:
+                ipaddress.ip_address(item)
+        except ValueError as exc:
+            raise ConfigError(
+                E_RULE_MATCH_INVALID,
+                f"规则 {rule.id} 的 dst_ip 非法: {item!r}",
+                field=f"rules[{rule.id}].dst_ip",
+                value=item,
+            ) from exc
+
+
+def _validate_port_expr(rule: Rule) -> None:
+    expr = rule.dst_port.strip()
+    if expr in {"", "*"}:
+        return
+    for item in _split_multi(expr, ","):
+        item = item.strip()
+        if not item or item == "*":
+            continue
+        if "-" in item:
+            lo_s, _, hi_s = item.partition("-")
+            try:
+                lo, hi = int(lo_s), int(hi_s)
+            except ValueError as exc:
+                raise ConfigError(
+                    E_RULE_MATCH_INVALID,
+                    f"规则 {rule.id} 的端口段非法: {item!r}",
+                    field=f"rules[{rule.id}].dst_port",
+                    value=item,
+                ) from exc
+            if not (0 < lo <= hi <= 65535):
+                raise ConfigError(
+                    E_RULE_MATCH_INVALID,
+                    f"规则 {rule.id} 的端口段非法（要求 0<lo<=hi<=65535）: {item!r}",
+                    field=f"rules[{rule.id}].dst_port",
+                    value=item,
+                )
+        else:
+            try:
+                port = int(item)
+            except ValueError as exc:
+                raise ConfigError(
+                    E_RULE_MATCH_INVALID,
+                    f"规则 {rule.id} 的端口非法: {item!r}",
+                    field=f"rules[{rule.id}].dst_port",
+                    value=item,
+                ) from exc
+            if not (0 < port <= 65535):
+                raise ConfigError(
+                    E_RULE_MATCH_INVALID,
+                    f"规则 {rule.id} 的端口超出范围: {item!r}",
+                    field=f"rules[{rule.id}].dst_port",
+                    value=item,
+                )
+
+
+def normalized_profile_doc(doc: dict[str, Any]) -> dict[str, Any]:
+    """把配置归一化成"profile 下含 rules/upstreams"的形态。
+
+     的 schema 把 `rules` 放在 `profile.*` 下，而 `samples/profiles/*.yaml`
+    放在顶层；两种写法都必须支持（dev.yaml 是官方样例，不能改）。
+    """
+    profile_doc = dict(_as_mapping(doc.get("profile"), field="profile"))
+    if "rules" not in profile_doc and "rules" in doc:
+        profile_doc["rules"] = doc.get("rules")
+    return profile_doc
+
+
+def _parse_upstreams(doc: Any) -> dict[str, Upstream]:
+    if doc is None:
+        return {}
+    items: list[Any]
+    if isinstance(doc, dict):
+        # 也允许 {alias: {...}} 形态
+        items = []
+        for alias, body in doc.items():
+            body = dict(_as_mapping(body, field=f"upstreams.{alias}"))
+            body.setdefault("alias", alias)
+            items.append(body)
+    elif isinstance(doc, list):
+        items = list(doc)
+    else:
+        raise ConfigError(E_RULE_UPSTREAM_MISSING, "upstreams 必须是列表或映射", field="upstreams")
+    out: dict[str, Upstream] = {}
+    for item in items:
+        if not isinstance(item, dict):
+            raise ConfigError(E_RULE_UPSTREAM_MISSING, "upstreams 每一项必须是映射", field="upstreams")
+        up = Upstream.from_dict(item)
+        if up.alias in out:
+            raise ConfigError(E_RULE_UPSTREAM_MISSING, f"上游别名重复: {up.alias}", field="upstreams.alias")
+        out[up.alias] = up
+    return out
+
+
+def port_in_use(port: int, host: str = "127.0.0.1") -> bool:
+    """检测端口是否已被占用（V6）。
+
+    Windows 上用 `SO_EXCLUSIVEADDRUSE`（`SO_REUSEADDR` 在 Windows 上允许重复绑定，
+    会漏判）；POSIX 上用默认语义（不提 SO_REUSEADDR 即为独占）。
+    """
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        if hasattr(socket, "SO_EXCLUSIVEADDRUSE"):  # Windows
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
+        sock.bind((host, port))
+        return False
+    except OSError:
+        return True
+    finally:
+        sock.close()
+
+
+# ------------------------------------------------------------ 热重载 -------
+class ConfigManager:
+    """持有当前生效配置，支持原子热重载。
+
+    红线：
+    * 校验失败 → 保留旧配置并抛出 `ConfigError`（调用方决定是否告警）；
+    * `sink.port`/`backend` 变化 → 明确拒绝热改（要求重启服务）。
+    """
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._lock = threading.Lock()
+        self._generation = 1
+
+    @property
+    def config(self) -> Config:
+        """读取当前配置（无锁读引用，热路径安全）。"""
+        return self._config
+
+    @property
+    def generation(self) -> int:
+        return self._generation
+
+    def reload(self, path: str | os.PathLike[str] | None = None, *, check_sink: bool = False) -> Config:
+        target = Path(path or self._config.path)
+        new = Config.load(target, check_sink=check_sink)
+        old = self._config
+        self._guard_restart_only(old, new)
+        with self._lock:
+            self._config = new
+            self._generation += 1
+        LOG.info(
+            "config_reloaded",
+            extra={
+                "event": "config_reloaded",
+                "fields": {
+                    "rules": len(new.profile.rules),
+                    "from_rules": len(old.profile.rules),
+                    "generation": self._generation,
+                    "path": str(target),
+                },
+            },
+        )
+        return new
+
+    @staticmethod
+    def _guard_restart_only(old: Config, new: Config) -> None:
+        if old.service.sink.port != new.service.sink.port:
+            raise ConfigError(
+                E_SINK_PORT_UNAVAILABLE,
+                "sink.port 不支持热改（需要重建监听），请重启服务",
+                field="service.sink.port",
+                value=new.service.sink.port,
+            )
+        if old.service.backend != new.service.backend:
+            raise ConfigError(
+                E_RULE_MATCH_INVALID,
+                f"backend 不支持热改（{old.service.backend} → {new.service.backend}），请重启服务",
+                field="service.backend",
+                value=new.service.backend,
+            )
+
+
+# 原子写配置
+
+def atomic_write(config: Config, path: str | os.PathLike[str]) -> None:
+    """写 `*.tmp` → 校验 → `os.replace`（防止半截配置被读到）。"""
+    target = Path(path)
+    tmp = target.with_suffix(target.suffix + ".tmp")
+    tmp.write_text(config.dump_yaml(), encoding="utf-8")
+    Config.load(tmp)  # 校验：失败则不动现网文件
+    os.replace(tmp, target)
+
+