norain 0.2.0.dev0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. norain/__init__.py +3 -0
  2. norain/__main__.py +5 -0
  3. norain/block.py +281 -0
  4. norain/boot.py +142 -0
  5. norain/cli.py +748 -0
  6. norain/control.py +703 -0
  7. norain/defaults.py +42 -0
  8. norain/generate.py +264 -0
  9. norain/install.py +312 -0
  10. norain/maintain.py +313 -0
  11. norain/model.py +409 -0
  12. norain/monitor.py +314 -0
  13. norain/paths.py +124 -0
  14. norain/probe.py +158 -0
  15. norain/proxy.py +136 -0
  16. norain/repair.py +278 -0
  17. norain/routing.py +332 -0
  18. norain/rules.py +214 -0
  19. norain/runner.py +59 -0
  20. norain-0.2.0.dev0.dist-info/METADATA +99 -0
  21. norain-0.2.0.dev0.dist-info/RECORD +53 -0
  22. norain-0.2.0.dev0.dist-info/WHEEL +5 -0
  23. norain-0.2.0.dev0.dist-info/entry_points.txt +3 -0
  24. norain-0.2.0.dev0.dist-info/licenses/LICENSE +21 -0
  25. norain-0.2.0.dev0.dist-info/top_level.txt +3 -0
  26. norain_core/__init__.py +4 -0
  27. norain_core/apply.py +70 -0
  28. norain_core/atomic.py +80 -0
  29. norain_core/cliutil.py +68 -0
  30. norain_core/daemonctl.py +192 -0
  31. norain_core/errors.py +60 -0
  32. norain_core/fetch.py +158 -0
  33. norain_core/log.py +104 -0
  34. norain_core/migrate.py +86 -0
  35. norain_core/osutil.py +332 -0
  36. norain_core/redact.py +60 -0
  37. norain_core/secrets.py +87 -0
  38. norain_core/singbox.py +93 -0
  39. norain_core/state.py +97 -0
  40. norain_core/supervisor.py +352 -0
  41. norain_core/sysproxy.py +112 -0
  42. norain_core/tomlio.py +86 -0
  43. norain_server/__init__.py +3 -0
  44. norain_server/__main__.py +5 -0
  45. norain_server/cert.py +276 -0
  46. norain_server/cli.py +477 -0
  47. norain_server/deploy.py +604 -0
  48. norain_server/firewall.py +226 -0
  49. norain_server/generate.py +112 -0
  50. norain_server/model.py +272 -0
  51. norain_server/paths.py +101 -0
  52. norain_server/runner.py +123 -0
  53. norain_server/service.py +83 -0
norain_core/redact.py ADDED
@@ -0,0 +1,60 @@
1
+ """统一脱敏。所有日志、错误输出和外部命令输出在显示前都要经过 redact()。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+
7
+ MASK = "***"
8
+
9
+ _PEM_KEY = re.compile(
10
+ r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?-----END [A-Z ]*PRIVATE KEY-----", re.S
11
+ )
12
+ _AUTH_URL = re.compile(r"\b([a-zA-Z][a-zA-Z0-9+.-]*://)[^/\s@]+@")
13
+ _KEY_VALUE = re.compile(
14
+ r"""(["']?(?:password|passwd|token|secret|private_key|mac_key)["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,}]+)""",
15
+ re.I,
16
+ )
17
+ _KEY_HINT = re.compile(r"passw|token|secret|_key", re.I) # _KEY_VALUE 能命中的必要条件
18
+ _SECRET_KEYS = {"password", "passwd", "token", "secret", "private_key", "mac_key", "key"}
19
+
20
+
21
+ class Redactor:
22
+ def __init__(self) -> None:
23
+ self._secrets: set[str] = set()
24
+ self._ordered: tuple[str, ...] = ()
25
+
26
+ def register(self, value: str) -> None:
27
+ if value and value not in self._secrets:
28
+ self._secrets.add(value)
29
+ # 长的在前,避免一个秘密是另一个的子串时泄漏剩余部分;只在登记时排序一次
30
+ self._ordered = tuple(sorted(self._secrets, key=len, reverse=True))
31
+
32
+ def redact(self, text: str) -> str:
33
+ # 每一行日志都会经过这里:先用便宜的子串检查排除绝大多数不含敏感内容的行
34
+ for secret in self._ordered:
35
+ if secret in text:
36
+ text = text.replace(secret, MASK)
37
+ if "PRIVATE KEY-----" in text:
38
+ text = _PEM_KEY.sub(MASK, text)
39
+ if "://" in text and "@" in text:
40
+ text = _AUTH_URL.sub(lambda m: m.group(1) + MASK + "@", text)
41
+ if _KEY_HINT.search(text):
42
+ text = _KEY_VALUE.sub(lambda m: m.group(1) + MASK, text)
43
+ return text
44
+
45
+ def redact_obj(self, obj):
46
+ if isinstance(obj, str):
47
+ return self.redact(obj)
48
+ if isinstance(obj, dict):
49
+ return {
50
+ k: (MASK if isinstance(k, str) and k.lower() in _SECRET_KEYS and isinstance(v, str)
51
+ else self.redact_obj(v))
52
+ for k, v in obj.items()
53
+ }
54
+ if isinstance(obj, (list, tuple)):
55
+ return [self.redact_obj(v) for v in obj]
56
+ return obj
57
+
58
+
59
+ REDACTOR = Redactor()
60
+ redact = REDACTOR.redact
norain_core/secrets.py ADDED
@@ -0,0 +1,87 @@
1
+ """credential_ref 解析。语法和权限要求见 docs/decisions/0014。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import os
7
+ import secrets as _secrets
8
+ import stat
9
+ from dataclasses import dataclass
10
+ from pathlib import Path
11
+
12
+ from .errors import BIZ_CONFIG, EXIT_CONFLICT, EXIT_PERMISSION, FieldError, NorainError, config_error
13
+ from .redact import REDACTOR
14
+
15
+ COMPAT_ENV = "NORAIN_PASSWORD"
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class Secret:
20
+ value: str
21
+ source: str # 例如 "file:/etc/…" 或 "env:NORAIN_PASSWORD",不含秘密值
22
+
23
+ @property
24
+ def fingerprint(self) -> str:
25
+ return hashlib.sha256(self.value.encode()).hexdigest()[:8]
26
+
27
+
28
+ def check_private_file(path: Path, *, field: str) -> None:
29
+ """要求文件只对属主可读写(POSIX)。Windows ACL 检查在客户端阶段实现。"""
30
+ if os.name != "posix":
31
+ return
32
+ st = path.stat()
33
+ if st.st_mode & (stat.S_IRWXG | stat.S_IRWXO):
34
+ raise config_error([FieldError(
35
+ field, f"{path} 的权限过宽({stat.S_IMODE(st.st_mode):04o}),要求不宽于 0600")])
36
+ if st.st_uid != os.geteuid() and os.geteuid() != 0:
37
+ raise config_error([FieldError(field, f"{path} 的属主不是当前运行用户")])
38
+
39
+
40
+ def resolve(ref: str, *, field: str = "auth.credential_ref") -> Secret:
41
+ ref = (ref or "").strip()
42
+ if not ref:
43
+ if os.environ.get(COMPAT_ENV):
44
+ ref = f"env:{COMPAT_ENV}"
45
+ else:
46
+ raise config_error([FieldError(
47
+ field, "未设置。使用 file:<路径> 或 env:<变量名>,或运行 secret generate")])
48
+ scheme, _, rest = ref.partition(":")
49
+ if scheme == "file" and rest:
50
+ path = Path(rest).expanduser()
51
+ if not path.is_file():
52
+ raise config_error([FieldError(field, f"秘密文件不存在:{path}")])
53
+ check_private_file(path, field=field)
54
+ try:
55
+ lines = path.read_text(encoding="utf-8").splitlines()
56
+ except PermissionError:
57
+ raise NorainError(f"无权读取秘密文件:{path}", exit_code=EXIT_PERMISSION,
58
+ business_code=BIZ_CONFIG, module="secrets") from None
59
+ value = lines[0].strip() if lines else ""
60
+ source = f"file:{path}"
61
+ elif scheme == "env" and rest:
62
+ value = os.environ.get(rest, "").strip()
63
+ if not value:
64
+ raise config_error([FieldError(field, f"环境变量 {rest} 未设置或为空")])
65
+ source = f"env:{rest}"
66
+ else:
67
+ raise config_error([FieldError(
68
+ field, "格式不支持。当前只支持 file:<路径> 和 env:<变量名>")])
69
+ if not value:
70
+ raise config_error([FieldError(field, f"秘密为空({source})")])
71
+ REDACTOR.register(value)
72
+ return Secret(value=value, source=source)
73
+
74
+
75
+ def generate_to_file(path: Path, *, force: bool = False) -> Secret:
76
+ path = path.expanduser()
77
+ if path.exists() and not force:
78
+ raise NorainError(f"{path} 已存在。确认要覆盖时加 --force",
79
+ exit_code=EXIT_CONFLICT, module="secrets")
80
+ path.parent.mkdir(parents=True, exist_ok=True)
81
+ value = _secrets.token_urlsafe(24)
82
+ fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
83
+ with os.fdopen(fd, "w", encoding="utf-8") as f:
84
+ f.write(value + "\n")
85
+ os.chmod(path, 0o600)
86
+ REDACTOR.register(value)
87
+ return Secret(value=value, source=f"file:{path}")
norain_core/singbox.py ADDED
@@ -0,0 +1,93 @@
1
+ """sing-box 二进制定位、版本检查和 check 包装。锁定策略见 docs/decisions/0002。
2
+
3
+ 已用真实 sing-box 1.14.4 验证:版本探测、check 校验、rule-set match。
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import os
9
+ import re
10
+ import shutil
11
+ import subprocess
12
+ from dataclasses import dataclass
13
+ from pathlib import Path
14
+
15
+ from .errors import (BIZ_BINARY_MISSING, BIZ_CONFIG, EXIT_DEPENDENCY, EXIT_EXTERNAL,
16
+ EXIT_TIMEOUT, NorainError)
17
+ from .redact import redact
18
+
19
+ # 必须与 third_party/singbox.lock.toml 一致(tests/test_singbox_lock.py 检查)
20
+ PINNED_VERSION = "1.14.4"
21
+ DEFAULT_PATH = "/usr/local/bin/sing-box"
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class BinaryInfo:
26
+ path: Path
27
+ version: str
28
+ tags: frozenset[str]
29
+
30
+
31
+ def locate(explicit: str | None = None, *, defaults: tuple[str, ...] = (DEFAULT_PATH,),
32
+ env_name: str = "NORAIN_SERVER_SINGBOX") -> Path:
33
+ """显式路径只认它自己;否则依次查默认位置和 PATH。"""
34
+ candidates = [explicit] if explicit else [*defaults, shutil.which("sing-box")]
35
+ for c in candidates:
36
+ if c and Path(c).is_file() and os.access(c, os.X_OK):
37
+ return Path(c)
38
+ if explicit:
39
+ msg = f"sing-box 不存在或不可执行:{explicit}"
40
+ else:
41
+ msg = f"找不到 sing-box(已查找 {'、'.join(defaults)} 和 PATH)"
42
+ raise NorainError(msg, exit_code=EXIT_DEPENDENCY, business_code=BIZ_BINARY_MISSING,
43
+ module="singbox",
44
+ hint=f"安装 sing-box {PINNED_VERSION},或用 {env_name} 指定路径")
45
+
46
+
47
+ def _run(args: list[str], *, timeout: float) -> subprocess.CompletedProcess:
48
+ try:
49
+ # 显式 UTF-8:Windows 上 locale 是 GBK,按 GBK 解码会抛 UnicodeDecodeError,
50
+ # 读线程一崩 stdout/stderr 就变成 None,后面的判断全部失效。
51
+ return subprocess.run(args, capture_output=True, text=True, encoding="utf-8",
52
+ errors="replace", timeout=timeout)
53
+ except subprocess.TimeoutExpired:
54
+ raise NorainError(f"{args[0]} {args[1]} 超时({timeout:.0f} 秒)", exit_code=EXIT_TIMEOUT,
55
+ module="singbox", retryable=True) from None
56
+ except OSError as e:
57
+ raise NorainError(f"无法执行 sing-box:{e}", exit_code=EXIT_DEPENDENCY,
58
+ business_code=BIZ_BINARY_MISSING, module="singbox") from None
59
+
60
+
61
+ def inspect(path: Path, *, timeout: float = 10.0) -> BinaryInfo:
62
+ proc = _run([str(path), "version"], timeout=timeout)
63
+ out = proc.stdout + proc.stderr
64
+ m = re.search(r"sing-box version\s+v?(\S+)", out)
65
+ if proc.returncode != 0 or not m:
66
+ raise NorainError("无法识别 sing-box 版本输出", exit_code=EXIT_DEPENDENCY,
67
+ business_code=BIZ_BINARY_MISSING, module="singbox")
68
+ tags = re.search(r"^Tags:\s*(.*)$", out, re.M)
69
+ tag_set = frozenset(t.strip() for t in tags.group(1).split(",") if t.strip()) if tags else frozenset()
70
+ return BinaryInfo(path=path, version=m.group(1), tags=tag_set)
71
+
72
+
73
+ def require(info: BinaryInfo, *, need_tags: set[str]) -> None:
74
+ if info.version != PINNED_VERSION and not os.environ.get("NORAIN_ALLOW_UNPINNED_SINGBOX"):
75
+ raise NorainError(
76
+ f"sing-box 版本是 {info.version},但 Norain 锁定的是 {PINNED_VERSION}",
77
+ exit_code=EXIT_DEPENDENCY, business_code=BIZ_BINARY_MISSING, module="singbox",
78
+ hint="安装锁定版本。仅调试时可设置 NORAIN_ALLOW_UNPINNED_SINGBOX=1 跳过")
79
+ missing = need_tags - info.tags
80
+ if missing:
81
+ raise NorainError(
82
+ f"sing-box 缺少构建标签:{', '.join(sorted(missing))}",
83
+ exit_code=EXIT_DEPENDENCY, business_code=BIZ_BINARY_MISSING, module="singbox")
84
+
85
+
86
+ def check(path: Path, config: Path, *, timeout: float = 30.0) -> None:
87
+ """运行 `sing-box check -c <配置>`。失败时抛出带脱敏输出的错误。"""
88
+ proc = _run([str(path), "check", "-c", str(config)], timeout=timeout)
89
+ if proc.returncode != 0:
90
+ detail = redact((proc.stderr or proc.stdout).strip())[-2000:]
91
+ raise NorainError(f"sing-box check 未通过:{detail}", exit_code=EXIT_EXTERNAL,
92
+ business_code=BIZ_CONFIG, module="singbox",
93
+ hint="上一份可用配置没有被覆盖")
norain_core/state.py ADDED
@@ -0,0 +1,97 @@
1
+ """期望状态和操作锁。模型见 docs/decisions/0013。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ import time
8
+ from contextlib import contextmanager
9
+ from pathlib import Path
10
+
11
+ from .atomic import atomic_write
12
+ from .errors import EXIT_CONFLICT, NorainError
13
+
14
+ RUNNING, STOPPED = "running", "stopped"
15
+
16
+
17
+ def read_json(path: Path) -> dict | None:
18
+ try:
19
+ return json.loads(path.read_text(encoding="utf-8"))
20
+ except (OSError, ValueError):
21
+ return None
22
+
23
+
24
+ def write_json(path: Path, obj: dict, *, durable: bool = True) -> None:
25
+ """durable=False:不 fsync,用于每隔几秒就改写一次的运行状态文件。"""
26
+ atomic_write(path, json.dumps(obj, ensure_ascii=False, sort_keys=True, indent=2).encode(),
27
+ durable=durable)
28
+
29
+
30
+ def get_desired(path: Path) -> str:
31
+ """没有记录时视为 stopped:没有人要求过启动。"""
32
+ data = read_json(path) or {}
33
+ return data.get("desired") if data.get("desired") in (RUNNING, STOPPED) else STOPPED
34
+
35
+
36
+ def set_desired(path: Path, desired: str, *, op_id: str) -> None:
37
+ assert desired in (RUNNING, STOPPED)
38
+ write_json(path, {"desired": desired, "op_id": op_id,
39
+ "updated_at": time.strftime("%Y-%m-%dT%H:%M:%S%z")})
40
+
41
+
42
+ def pid_alive(pid: int) -> bool:
43
+ # 不用 os.kill(pid, 0):在 Windows 上它不是「探测」,会影响目标进程
44
+ import psutil
45
+ try:
46
+ return pid > 0 and psutil.Process(pid).status() != psutil.STATUS_ZOMBIE
47
+ except psutil.Error:
48
+ return False
49
+
50
+
51
+ def lock_holder(path: Path) -> dict | None:
52
+ """返回有效的持锁者;锁过期或持锁进程已死时返回 None。"""
53
+ data = read_json(path)
54
+ if not data:
55
+ return None
56
+ if data.get("expires_at", 0) < time.time() or not pid_alive(int(data.get("pid", 0))):
57
+ return None
58
+ return data
59
+
60
+
61
+ def _just_created(path: Path, *, within: float = 2.0) -> bool:
62
+ try:
63
+ return time.time() - path.stat().st_mtime < within
64
+ except OSError:
65
+ return False
66
+
67
+
68
+ @contextmanager
69
+ def op_lock(path: Path, *, op: str, op_id: str, timeout: float = 120.0):
70
+ """互斥执行 start/stop/restart 等操作。失效的锁会被接管。"""
71
+ path.parent.mkdir(parents=True, exist_ok=True)
72
+ payload = json.dumps({"op": op, "op_id": op_id, "pid": os.getpid(),
73
+ "expires_at": time.time() + timeout}).encode()
74
+ for attempt in (1, 2):
75
+ try:
76
+ fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
77
+ break
78
+ except FileExistsError:
79
+ holder = lock_holder(path)
80
+ if holder is None and attempt == 1 and read_json(path) is None and _just_created(path):
81
+ # 对方刚用 O_EXCL 建出锁文件、内容还没写进去:这是一把有效的锁,不能当成失效锁接管
82
+ holder = {"op": "刚开始的操作", "op_id": "?"}
83
+ if holder or attempt == 2:
84
+ raise NorainError(
85
+ f"另一个操作正在进行:{(holder or {}).get('op', '未知')}"
86
+ f"(操作 ID {(holder or {}).get('op_id', '?')})",
87
+ exit_code=EXIT_CONFLICT, retryable=True, module="state",
88
+ hint="稍后重试") from None
89
+ path.unlink(missing_ok=True) # 接管失效的锁
90
+ with os.fdopen(fd, "wb") as f:
91
+ f.write(payload)
92
+ try:
93
+ yield
94
+ finally:
95
+ mine = read_json(path)
96
+ if mine and mine.get("op_id") == op_id:
97
+ path.unlink(missing_ok=True)
@@ -0,0 +1,352 @@
1
+ """sing-box 子进程监督器,客户端和服务端共用。
2
+
3
+ - 启动 sing-box,定时检查进程、端口监听和 fatal 日志;
4
+ - 异常时重启,连续重启超过上限后以 EXIT_RESTART_LIMIT 退出;
5
+ - 停止请求有两种来源:停止请求文件(跨平台)和 SIGTERM/SIGINT(POSIX)。
6
+ Windows 上向进程发信号等于强制结束,所以必须用停止请求文件才能干净退出。
7
+ - 重载请求(重载请求文件或 request_reload()):重启子进程以加载新配置,不计入失败次数。
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import errno
13
+ import hashlib
14
+ import os
15
+ import re
16
+ import signal
17
+ import socket
18
+ import subprocess
19
+ import threading
20
+ import time
21
+ from dataclasses import dataclass
22
+ from pathlib import Path
23
+ from typing import Callable
24
+
25
+ import psutil
26
+
27
+ from .errors import (BIZ_PORT_IN_USE, BIZ_PROCESS_EXITED, BIZ_RESTART_LIMIT, EXIT_EXTERNAL,
28
+ EXIT_OK, EXIT_PERMISSION, EXIT_RESTART_LIMIT, NorainError)
29
+ from .log import Logger, RotatingFile
30
+ from .redact import redact
31
+ from .state import write_json
32
+
33
+ _FATAL = re.compile(r"\bFATAL\b|\bpanic:", re.I)
34
+ STOP_GRACE_SECONDS = 10
35
+
36
+ RELOAD = "<reload>" # _supervise 的返回值:按请求重启子进程,不算故障
37
+
38
+ Listener = tuple[str, str, int] # (监听地址, "tcp" | "udp", 端口)
39
+
40
+
41
+ @dataclass
42
+ class Spec:
43
+ binary: Path
44
+ config_json: Path
45
+ config_version: str
46
+ listeners: list[Listener]
47
+ check_interval: float
48
+ restart_limit: int
49
+ backoff: float
50
+ log_file: Path
51
+ log_max_bytes: int
52
+ log_keep: int
53
+ log_level: str
54
+ runner_file: Path
55
+ last_error_file: Path
56
+ stop_file: Path
57
+ reload_file: Path | None = None # 出现该文件时重启子进程(不计失败)
58
+ on_line: Callable[[str], None] | None = None # 每行(已脱敏的)sing-box 输出的回调
59
+
60
+
61
+ def check_ports_free(listeners: list[Listener]) -> None:
62
+ for listen, proto, port in listeners:
63
+ family = socket.AF_INET6 if ":" in listen else socket.AF_INET
64
+ kind = socket.SOCK_DGRAM if proto == "udp" else socket.SOCK_STREAM
65
+ with socket.socket(family, kind) as s:
66
+ if proto == "tcp" and os.name == "posix":
67
+ s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
68
+ try:
69
+ s.bind((listen, port))
70
+ except OSError as e:
71
+ in_use = e.errno in (errno.EADDRINUSE, getattr(errno, "WSAEADDRINUSE", -1))
72
+ denied = e.errno in (errno.EACCES, getattr(errno, "WSAEACCES", -1))
73
+ if in_use:
74
+ msg, hint = f"端口 {port}/{proto} 已被占用", "换一个端口,或关闭占用它的程序"
75
+ elif denied:
76
+ msg, hint = f"没有权限监听 {port}/{proto}", "用更高的端口,或以管理员/root 运行"
77
+ else:
78
+ msg, hint = f"无法监听 {listen}:{port}/{proto}:{e}", ""
79
+ raise NorainError(msg, exit_code=EXIT_PERMISSION if denied else EXIT_EXTERNAL,
80
+ business_code=BIZ_PORT_IN_USE, module="daemon", hint=hint) from None
81
+
82
+
83
+ def missing_listeners(pid: int, listeners: list[Listener]) -> list[str] | None:
84
+ """返回没有在监听的端口;无法检查时返回 None。"""
85
+ try:
86
+ proc = psutil.Process(pid)
87
+ conns = []
88
+ for p in (proc, *proc.children(recursive=True)):
89
+ fn = getattr(p, "net_connections", None) or p.connections
90
+ conns += fn(kind="inet")
91
+ except (psutil.Error, OSError):
92
+ return None
93
+ have = {("udp" if c.type == socket.SOCK_DGRAM else "tcp", c.laddr.port)
94
+ for c in conns if c.laddr and (c.type == socket.SOCK_DGRAM or c.status == psutil.CONN_LISTEN)}
95
+ return [f"{port}/{proto}" for _, proto, port in listeners if (proto, port) not in have]
96
+
97
+
98
+ def record_error(path: Path, business_code: int, message: str) -> None:
99
+ try:
100
+ write_json(path, {"business_code": business_code, "message": redact(message),
101
+ "time": time.strftime("%Y-%m-%dT%H:%M:%S%z")})
102
+ except OSError:
103
+ pass
104
+
105
+
106
+ def _safe_unlink(path: Path, *, attempts: int = 4) -> None:
107
+ """删除短生命周期的状态文件,不让 Windows 的短暂文件锁打崩守护进程。"""
108
+ for n in range(attempts):
109
+ try:
110
+ path.unlink(missing_ok=True)
111
+ return
112
+ except FileNotFoundError:
113
+ return
114
+ except OSError:
115
+ if n + 1 == attempts:
116
+ return
117
+ time.sleep(0.05)
118
+
119
+
120
+ class Supervisor:
121
+ def __init__(self, spec: Spec) -> None:
122
+ self.spec = spec
123
+ self._stop = threading.Event()
124
+ self._reload = threading.Event()
125
+ self._wake = threading.Event() # 停止或重载请求到来时立刻唤醒监督循环
126
+ self._child: subprocess.Popen | None = None
127
+ self._fatal: str | None = None
128
+ self.total_restarts = 0
129
+ self.ready = False # 当前子进程的端口是否都已开始监听
130
+
131
+ def request_stop(self, *_args) -> None:
132
+ self._stop.set()
133
+ self._wake.set()
134
+
135
+ def request_reload(self) -> None:
136
+ self._reload.set()
137
+ self._wake.set()
138
+
139
+ @property
140
+ def child_pid(self) -> int | None:
141
+ child = self._child
142
+ return child.pid if child is not None and child.poll() is None else None
143
+
144
+ def _reload_requested(self) -> bool:
145
+ rf = self.spec.reload_file
146
+ hit = self._reload.is_set()
147
+ if rf is not None and rf.exists():
148
+ _safe_unlink(rf)
149
+ hit = True
150
+ self._reload.clear()
151
+ return hit
152
+
153
+ def _stop_requested(self, wait: float) -> bool:
154
+ """最多等 wait 秒,返回是否收到停止请求。
155
+
156
+ 进程内的请求(request_stop / request_reload)立刻唤醒;停止请求文件每 0.5 秒看一次,
157
+ 这样长时间的退避等待期间 Windows 上的 `stop` 也能及时生效。有重载请求时提前返回 False。
158
+ """
159
+ deadline = time.monotonic() + wait
160
+ while True:
161
+ remaining = deadline - time.monotonic()
162
+ if remaining > 0 and not self._stop.is_set() and not self._reload.is_set():
163
+ self._wake.wait(min(remaining, 0.5))
164
+ self._wake.clear()
165
+ if self._stop.is_set():
166
+ return True
167
+ if self.spec.stop_file.exists():
168
+ self._stop.set()
169
+ return True
170
+ if remaining <= 0.5 or self._reload.is_set():
171
+ return False
172
+
173
+ def _pump(self, child: subprocess.Popen, sink: RotatingFile) -> None:
174
+ assert child.stdout is not None
175
+ for raw in child.stdout:
176
+ line = redact(raw.rstrip("\n"))
177
+ sink.write_line(line)
178
+ if _FATAL.search(line):
179
+ self._fatal = line[-500:]
180
+ if self.spec.on_line is not None:
181
+ try:
182
+ self.spec.on_line(line)
183
+ except Exception: # noqa: BLE001 回调出错不能中断日志泵
184
+ pass
185
+
186
+ @staticmethod
187
+ def _terminate(child: subprocess.Popen) -> None:
188
+ # 先记下整棵子孙树:Windows 上子进程可能是个启动器(.cmd、包装脚本、
189
+ # 安装器壳)。即使启动器已经退出,真正的进程也可能还占着端口。
190
+ try:
191
+ procs = psutil.Process(child.pid).children(recursive=True)
192
+ except (psutil.Error, OSError):
193
+ procs = []
194
+ if child.poll() is None:
195
+ try:
196
+ child.terminate()
197
+ except OSError:
198
+ pass
199
+ try:
200
+ child.wait(STOP_GRACE_SECONDS)
201
+ except subprocess.TimeoutExpired:
202
+ try:
203
+ child.kill()
204
+ child.wait(5)
205
+ except (OSError, subprocess.TimeoutExpired):
206
+ pass
207
+ for p in procs:
208
+ try:
209
+ if p.is_running():
210
+ p.terminate()
211
+ except (psutil.Error, OSError):
212
+ continue
213
+ try:
214
+ p.wait(2)
215
+ except (psutil.TimeoutExpired, OSError):
216
+ try:
217
+ p.kill()
218
+ except (psutil.Error, OSError):
219
+ pass
220
+
221
+ def _write_runner(self, child_pid: int | None, consecutive: int, ready: bool = False) -> None:
222
+ self.ready = ready
223
+ record = {
224
+ "pid": os.getpid(), "child_pid": child_pid, "ready": ready,
225
+ "started_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
226
+ "restarts": self.total_restarts, "consecutive_restarts": consecutive,
227
+ "config_version": self._config_version(), "log_file": str(self.spec.log_file),
228
+ }
229
+ # 运行状态文件丢了可以重建,不需要 fsync;写失败(磁盘满、Windows 上的瞬时文件锁)
230
+ # 不能让监督器退出——那会把一个正常运行的 sing-box 判成故障
231
+ for attempt in (1, 2):
232
+ try:
233
+ write_json(self.spec.runner_file, record, durable=False)
234
+ return
235
+ except OSError:
236
+ if attempt == 1:
237
+ time.sleep(0.1)
238
+
239
+ def _config_version(self) -> str:
240
+ """重载后配置文件内容会变,版本号以磁盘上的当前配置为准。"""
241
+ try:
242
+ return hashlib.sha256(self.spec.config_json.read_bytes()).hexdigest()[:12]
243
+ except OSError:
244
+ return self.spec.config_version
245
+
246
+ def _supervise(self, child: subprocess.Popen, log: Logger, consecutive: int) -> str | None:
247
+ """阻塞到子进程需要处理为止。返回故障原因;用户要求停止时返回 None。"""
248
+ spec = self.spec
249
+ started = time.monotonic()
250
+ next_check = started + spec.check_interval
251
+ ready = False
252
+ while True:
253
+ # 就绪之前轮询得快一些(尽早报告就绪);就绪之后放慢,减少空转
254
+ if self._stop_requested(0.5 if ready else 0.2):
255
+ self._terminate(child)
256
+ return None
257
+ if self._reload_requested():
258
+ self._terminate(child)
259
+ return RELOAD
260
+ rc = child.poll()
261
+ if rc is not None:
262
+ return f"sing-box 退出,退出码 {rc}"
263
+ if not ready:
264
+ # 就绪:端口都在监听;无法检查端口时,存活满 1 秒视为就绪
265
+ missing = missing_listeners(child.pid, spec.listeners)
266
+ if missing == [] or (missing is None and time.monotonic() - started >= 1):
267
+ ready = True
268
+ self._write_runner(child.pid, consecutive, ready=True)
269
+ log.info("singbox.ready", pid=child.pid)
270
+ if time.monotonic() < next_check:
271
+ continue
272
+ next_check = time.monotonic() + spec.check_interval
273
+ if self._fatal:
274
+ reason = f"日志出现 fatal:{self._fatal}"
275
+ else:
276
+ missing = missing_listeners(child.pid, spec.listeners)
277
+ if missing is None:
278
+ log.warn("health.ports_unknown")
279
+ reason = f"端口没有在监听:{', '.join(missing)}" if missing else None
280
+ if reason:
281
+ self._terminate(child)
282
+ return reason
283
+ log.debug("health.ok")
284
+
285
+ def run(self) -> int:
286
+ spec = self.spec
287
+ sink = RotatingFile(spec.log_file, max_bytes=spec.log_max_bytes, keep=spec.log_keep)
288
+ log = Logger("daemon", sink=sink, level=spec.log_level)
289
+ _safe_unlink(spec.stop_file)
290
+ if spec.reload_file is not None:
291
+ _safe_unlink(spec.reload_file)
292
+ try:
293
+ signal.signal(signal.SIGTERM, self.request_stop)
294
+ signal.signal(signal.SIGINT, self.request_stop)
295
+ except ValueError:
296
+ pass # 不在主线程(测试中)
297
+
298
+ stable_after = max(2 * spec.check_interval, 60.0)
299
+ consecutive = 0
300
+ popen_extra = {}
301
+ if os.name == "nt":
302
+ popen_extra["creationflags"] = subprocess.CREATE_NO_WINDOW
303
+ try:
304
+ while True:
305
+ self._fatal = None
306
+ self._reload_requested() # 马上要用最新配置启动:之前积压的重载请求已经满足
307
+ child = subprocess.Popen(
308
+ [str(spec.binary), "run", "-c", str(spec.config_json)],
309
+ stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
310
+ text=True, encoding="utf-8", errors="replace", **popen_extra)
311
+ self._child = child
312
+ started = time.monotonic()
313
+ self._write_runner(child.pid, consecutive)
314
+ log.info("singbox.started", pid=child.pid, config_version=self._config_version(),
315
+ restarts=self.total_restarts)
316
+ pump = threading.Thread(target=self._pump, args=(child, sink), daemon=True)
317
+ pump.start()
318
+
319
+ reason = self._supervise(child, log, consecutive)
320
+ self.ready = False
321
+ pump.join(2)
322
+ if reason is None:
323
+ log.info("daemon.stopped", reason="stop requested")
324
+ return EXIT_OK
325
+ if reason == RELOAD:
326
+ log.info("singbox.reloading")
327
+ consecutive = 0
328
+ continue
329
+
330
+ record_error(spec.last_error_file, BIZ_PROCESS_EXITED, reason)
331
+ log.error("singbox.failed", reason=reason, business_code=BIZ_PROCESS_EXITED)
332
+ if time.monotonic() - started >= stable_after:
333
+ consecutive = 0
334
+ consecutive += 1
335
+ if consecutive > spec.restart_limit:
336
+ msg = f"连续重启 {spec.restart_limit} 次后仍然失败,停止重启。最后原因:{reason}"
337
+ record_error(spec.last_error_file, BIZ_RESTART_LIMIT, msg)
338
+ log.error("daemon.restart_limit", limit=spec.restart_limit,
339
+ business_code=BIZ_RESTART_LIMIT)
340
+ return EXIT_RESTART_LIMIT
341
+ self.total_restarts += 1
342
+ delay = min(spec.backoff * 2 ** (consecutive - 1), 300)
343
+ log.warn("singbox.restarting", attempt=consecutive, limit=spec.restart_limit,
344
+ delay_seconds=delay)
345
+ if self._stop_requested(delay):
346
+ log.info("daemon.stopped", reason="stop requested during backoff")
347
+ return EXIT_OK
348
+ finally:
349
+ if self._child is not None:
350
+ self._terminate(self._child)
351
+ _safe_unlink(spec.runner_file)
352
+ _safe_unlink(spec.stop_file)