kitty-logger 0.1.0__tar.gz → 0.2.0.dev0__tar.gz

kitty_logger-0.2.0.dev0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: kitty_logger
+Version: 0.2.0.dev0
+Summary: Cross-process logging via a dedicated log server process and SocketHandler.
+Author: Kitty
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# kitty_logger
+
+单机跨进程的 Python 日志库。主进程启动一个独立的"日志服务"子进程，所有
+通过 `spawn` 创建的子进程把 `LogRecord` 经 `logging.handlers.SocketHandler`
+发到这里，由它统一落盘 / 输出到 `stderr`，**不会出现多进程并发写文件的
+错行或丢失问题**。
+
+**适用范围。** 公司内部研发协作环境：单台主机、本机所有进程都互相信任、
+追求"用起来简单"而不是"对抗外部威胁"。**不适用于**生产部署或多租户机器
+等不能信任本机其他进程的场景。
+
+## 安装
+
+```bash
+pip install kitty-logger
+```
+
+## 用法
+
+```python
+# main.py
+import multiprocessing as mp
+import kitty_logger
+
+def worker(i):
+    log = kitty_logger.getLogger(f"worker.{i}")
+    log.info("hello from worker %d", i)
+
+if __name__ == "__main__":
+    kitty_logger.setup_logging(log_file="app.log")
+    log = kitty_logger.getLogger("main")
+    log.info("starting")
+
+    with mp.get_context("spawn").Pool(4) as pool:
+        pool.map(worker, range(4))
+```
+
+`setup_logging` 会写入环境变量
+`KITTY_LOGGER_HOST` / `KITTY_LOGGER_PORT` / `KITTY_LOGGER_LEVEL`；任意层级
+`spawn` 出来的后代进程会自动继承，从而能在零配置的情况下连上日志服务。
+
+## API
+
+- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=True) -> (host, port)`
+  启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
+  `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
+  **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
+- `getLogger(name=None) -> logging.Logger`
+  返回一个挂好 `SocketHandler`、指向日志服务的 logger。
+- `shutdown_logging()` — 显式停止日志服务子进程。
+
+## 为什么只支持 spawn
+
+`fork` 出来的子进程会继承父进程已经建立的 `SocketHandler` 及其底层 TCP
+连接。父子进程会在同一个 socket 上交叉写 pickle 字节流，导致服务端反
+序列化必然失败。此外 `fork` 在多线程父进程中不安全（其他线程持有的锁
+会原样留在子进程里，引发死锁），且在 Windows 上不被支持。
+
+请使用 `multiprocessing.get_context("spawn")`，或在顶层用
+`if __name__ == "__main__":` 守卫配合 Python 默认行为。
+
+## 注意事项
+
+- **不要**在 `setup_logging(attach_main_logger=True)` 之前调用
+  `logging.basicConfig()`（或自行给 root logger 挂 `StreamHandler`）——
+  否则主进程会把每条记录输出两次：一次走本地 root handler，一次走日志
+  服务。要么让 kitty_logger 做唯一的配置入口，要么传
+  `attach_main_logger=False` 自行管理主进程的 handler。
+- `shutdown_logging()` 会卸载本进程内 kitty_logger 自己挂的
+  `SocketHandler`，并清理 `KITTY_LOGGER_*` 环境变量，确保进程状态与
+  `setup_logging` 对称。如果你额外挂了别的 handler，仍由你自己负责清理。
+
+## 安全性
+
+服务端用 `pickle.loads` 反序列化收到的字节流——这等价于在本机上对攻击者
+可控的输入做"任意代码执行"。为了让这个能力**永远不会跨出本机**，
+`setup_logging` 在打开 socket 之前就会**直接拒绝任何非 loopback 绑定**
+（`ValueError`）。监听端口仅本机可达；请把它视为受信任的内部接口，**不要**
+在不能信任本机其他进程的多租户机器上运行。

kitty_logger-0.2.0.dev0/README.md

@@ -0,0 +1,79 @@
+# kitty_logger
+
+单机跨进程的 Python 日志库。主进程启动一个独立的"日志服务"子进程，所有
+通过 `spawn` 创建的子进程把 `LogRecord` 经 `logging.handlers.SocketHandler`
+发到这里，由它统一落盘 / 输出到 `stderr`，**不会出现多进程并发写文件的
+错行或丢失问题**。
+
+**适用范围。** 公司内部研发协作环境：单台主机、本机所有进程都互相信任、
+追求"用起来简单"而不是"对抗外部威胁"。**不适用于**生产部署或多租户机器
+等不能信任本机其他进程的场景。
+
+## 安装
+
+```bash
+pip install kitty-logger
+```
+
+## 用法
+
+```python
+# main.py
+import multiprocessing as mp
+import kitty_logger
+
+def worker(i):
+    log = kitty_logger.getLogger(f"worker.{i}")
+    log.info("hello from worker %d", i)
+
+if __name__ == "__main__":
+    kitty_logger.setup_logging(log_file="app.log")
+    log = kitty_logger.getLogger("main")
+    log.info("starting")
+
+    with mp.get_context("spawn").Pool(4) as pool:
+        pool.map(worker, range(4))
+```
+
+`setup_logging` 会写入环境变量
+`KITTY_LOGGER_HOST` / `KITTY_LOGGER_PORT` / `KITTY_LOGGER_LEVEL`；任意层级
+`spawn` 出来的后代进程会自动继承，从而能在零配置的情况下连上日志服务。
+
+## API
+
+- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=True) -> (host, port)`
+  启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
+  `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
+  **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
+- `getLogger(name=None) -> logging.Logger`
+  返回一个挂好 `SocketHandler`、指向日志服务的 logger。
+- `shutdown_logging()` — 显式停止日志服务子进程。
+
+## 为什么只支持 spawn
+
+`fork` 出来的子进程会继承父进程已经建立的 `SocketHandler` 及其底层 TCP
+连接。父子进程会在同一个 socket 上交叉写 pickle 字节流，导致服务端反
+序列化必然失败。此外 `fork` 在多线程父进程中不安全（其他线程持有的锁
+会原样留在子进程里，引发死锁），且在 Windows 上不被支持。
+
+请使用 `multiprocessing.get_context("spawn")`，或在顶层用
+`if __name__ == "__main__":` 守卫配合 Python 默认行为。
+
+## 注意事项
+
+- **不要**在 `setup_logging(attach_main_logger=True)` 之前调用
+  `logging.basicConfig()`（或自行给 root logger 挂 `StreamHandler`）——
+  否则主进程会把每条记录输出两次：一次走本地 root handler，一次走日志
+  服务。要么让 kitty_logger 做唯一的配置入口，要么传
+  `attach_main_logger=False` 自行管理主进程的 handler。
+- `shutdown_logging()` 会卸载本进程内 kitty_logger 自己挂的
+  `SocketHandler`，并清理 `KITTY_LOGGER_*` 环境变量，确保进程状态与
+  `setup_logging` 对称。如果你额外挂了别的 handler，仍由你自己负责清理。
+
+## 安全性
+
+服务端用 `pickle.loads` 反序列化收到的字节流——这等价于在本机上对攻击者
+可控的输入做"任意代码执行"。为了让这个能力**永远不会跨出本机**，
+`setup_logging` 在打开 socket 之前就会**直接拒绝任何非 loopback 绑定**
+（`ValueError`）。监听端口仅本机可达；请把它视为受信任的内部接口，**不要**
+在不能信任本机其他进程的多租户机器上运行。

{kitty_logger-0.1.0 → kitty_logger-0.2.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kitty_logger"
-version = "0.1.0"
+version = "0.2.0.dev0"
 description = "Cross-process logging via a dedicated log server process and SocketHandler."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -19,6 +19,7 @@ test = ["pytest>=7"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["src"]
 
 [tool.black]
-line-length = 2048
+line-length = 88

kitty_logger-0.2.0.dev0/src/kitty_logger/__init__.py

@@ -0,0 +1,31 @@
+"""kitty_logger：单机跨进程的 Python 日志库。
+
+面向内部研发协作环境（**不针对生产 / 多租户场景**）。主进程调用一次
+:func:`setup_logging`，之后任意 ``spawn`` 出来的子进程直接调用
+:func:`getLogger` 即可——后代进程会自动通过环境变量找到日志服务，所有
+日志收敛到主进程指定的文件 / ``stderr`` 中，不会因多进程并发写文件而
+错行或丢失。
+
+典型用法::
+
+    # main.py
+    import multiprocessing as mp
+    import kitty_logger
+
+    def worker(i: int) -> None:
+        log = kitty_logger.getLogger(f"worker.{i}")
+        log.info("hello from worker %d", i)
+
+    if __name__ == "__main__":
+        kitty_logger.setup_logging(log_file="app.log")
+        log = kitty_logger.getLogger("main")
+        log.info("starting")
+        with mp.get_context("spawn").Pool(4) as pool:
+            pool.map(worker, range(4))
+"""
+
+from ._client import getLogger
+from ._setup import setup_logging, shutdown_logging
+
+__all__ = ["setup_logging", "shutdown_logging", "getLogger"]
+__version__ = "0.2.0.dev0"

kitty_logger-0.2.0.dev0/src/kitty_logger/_client.py

@@ -0,0 +1,102 @@
+"""子进程侧 API：:func:`getLogger`。
+
+子进程通过环境变量
+``KITTY_LOGGER_HOST`` / ``KITTY_LOGGER_PORT`` / ``KITTY_LOGGER_LEVEL``
+找到日志服务地址；这些环境变量是父进程在 :func:`setup_logging` 时写入的，
+``spawn`` 出来的后代进程会自动继承。
+"""
+
+import logging
+import logging.handlers
+import os
+import threading
+
+from ._env import ENV_HOST, ENV_LEVEL, ENV_PORT
+
+# 保护下面这个模块级集合的并发访问。
+_lock = threading.Lock()
+
+# 已挂过 SocketHandler 的 logger 名集合，用于在同一进程内做去重。
+# root logger 在集合里以空字符串 ``""`` 作为 key。
+_configured_loggers: set[str] = set()
+
+
+def _read_endpoint() -> tuple[str, int]:
+    """从环境变量读出 ``(host, port)``；未设置则抛出友好错误。"""
+    host = os.environ.get(ENV_HOST)
+    port = os.environ.get(ENV_PORT)
+    if not host or not port:
+        raise RuntimeError(
+            "kitty_logger 尚未在当前进程树中初始化。"
+            + "请先在主进程调用 kitty_logger.setup_logging()，"
+            + "再创建（spawn）子进程或调用 getLogger()。"
+        )
+    return host, int(port)
+
+
+def _read_level() -> int:
+    """从环境变量解析默认 level。优先按整数解析，失败则按级别名解析。"""
+    raw = os.environ.get(ENV_LEVEL)
+    if raw is None:
+        return logging.INFO
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    return logging.getLevelNamesMapping().get(raw.upper(), logging.INFO)
+
+
+def _attach_socket_handler(
+    logger: logging.Logger,
+    host: str,
+    port: int,
+    level: int,
+) -> None:
+    """给 ``logger`` 挂上指向日志服务的 :class:`SocketHandler`。
+
+    .. note::
+       :class:`logging.handlers.SocketHandler` 直接 pickle ``LogRecord``
+       发送，由接收端格式化；在这里给 handler 设置 ``formatter`` 没有
+       任何效果，会被服务端忽略。
+    """
+    SocketHandler = logging.handlers.SocketHandler
+
+    # 同一 logger 上避免重复挂指向相同端点的 SocketHandler——例如模块被
+    # 重新 import、或测试用例反复 setup 的场景。
+    for h in logger.handlers:
+        if isinstance(h, SocketHandler) and (h.host, h.port) == (host, port):
+            return
+
+    logger.addHandler(SocketHandler(host, port))
+
+    # 仅在 logger 仍是默认 ``NOTSET`` 时才设置 level，避免悄悄覆盖
+    # 用户已经显式设置过的级别。
+    if logger.level == logging.NOTSET:
+        logger.setLevel(level)
+
+    # 关闭向 root 的传播，避免与已存在的 root handler（比如调用过
+    # ``basicConfig``）造成重复输出。root 自身没有父级，跳过此项。
+    if logger is not logging.getLogger():
+        logger.propagate = False
+
+
+def getLogger(name: str | None = None) -> logging.Logger:
+    """返回一个会把日志通过 :class:`SocketHandler` 发送到日志服务的 logger。
+
+    必须在父进程已经调用过 :func:`kitty_logger.setup_logging` 之后才能
+    使用。本库只支持 ``spawn`` 启动方式；spawn 出来的子进程模块级状态
+    天然为空，因此不需要处理"继承自父进程的 SocketHandler"问题。
+
+    :param name: logger 名；``None`` 表示 root logger。
+    :raises RuntimeError: 当前进程树尚未调用 ``setup_logging``。
+    """
+    host, port = _read_endpoint()
+    level = _read_level()
+    logger = logging.getLogger(name)
+
+    with _lock:
+        key = name or ""
+        if key not in _configured_loggers:
+            _attach_socket_handler(logger, host, port, level)
+            _configured_loggers.add(key)
+    return logger

kitty_logger-0.2.0.dev0/src/kitty_logger/_env.py

@@ -0,0 +1,13 @@
+"""共享的环境变量名常量。
+
+将这几个常量单独放在一个不依赖任何业务模块的位置，避免 ``_setup`` 与
+``_client`` 之间出现循环导入。
+
+这些环境变量由主进程的 :func:`kitty_logger.setup_logging` 写入；通过
+``spawn`` 启动的子进程会自然继承，从而能在不显式传参的情况下找到日志
+服务地址。
+"""
+
+ENV_HOST = "KITTY_LOGGER_HOST"
+ENV_PORT = "KITTY_LOGGER_PORT"
+ENV_LEVEL = "KITTY_LOGGER_LEVEL"

kitty_logger-0.2.0.dev0/src/kitty_logger/_formatters.py

@@ -0,0 +1,82 @@
+"""日志格式化器：控制台版（按字段着色 ANSI）与文件版（无颜色）。
+
+控制台格式化器把不同字段染成不同颜色，便于在终端里快速分辨；
+文件格式化器保持纯文本，避免日志文件被颜色码污染。两者都通过
+:class:`_MillisecondTimeFormatter` 共享毫秒精度的时间戳实现。
+"""
+
+import logging
+import time
+from typing import override
+
+# 256 色调色板，在深色终端下不刺眼。
+_LEVEL_COLORS: dict[str, str] = {
+    "DEBUG": "\033[38;5;32m",
+    "INFO": "\033[38;5;70m",
+    "WARNING": "\033[38;5;186m",
+    "ERROR": "\033[38;5;206m",
+    "CRITICAL": "\033[1;38;5;196m",
+}
+_PROC_COLOR = "\033[38;5;141m"
+_NAME_COLOR = "\033[38;5;36m"
+_FILE_COLOR = "\033[38;5;45m"
+_FUNC_COLOR = "\033[38;5;208m"
+_RESET = "\033[0m"
+
+# 控制台格式：每个字段独立着色，进程信息排在最前以契合 kitty_logger 的跨进程定位。
+DEFAULT_CONSOLE_FMT = (
+    "%(asctime)s | "
+    "%(proc_color)s%(processName)s(%(process)d)%(reset)s | "
+    "%(name_color)s%(name)s%(reset)s | "
+    "%(file_color)s%(filename)s:%(lineno)d%(reset)s | "
+    "%(func_color)s%(funcName)s%(reset)s | "
+    "%(color)s%(levelname)s%(reset)s | "
+    "%(message)s"
+)
+
+# 文件格式：字段一致，但不带任何 ANSI 颜色码。
+DEFAULT_FILE_FMT = (
+    "%(asctime)s | %(processName)s(%(process)d) | %(name)s | "
+    "%(filename)s:%(lineno)d | %(funcName)s | %(levelname)s | %(message)s"
+)
+
+
+class _MillisecondTimeFormatter(logging.Formatter):
+    """带毫秒精度的时间格式化基类。
+
+    标准库 :meth:`logging.Formatter.formatTime` 在传入 ``datefmt`` 时
+    不会自动拼接毫秒，这里覆写以始终带上 ``.毫秒`` 后缀。
+    """
+
+    @override
+    def formatTime(
+        self,
+        record: logging.LogRecord,
+        datefmt: str | None = None,
+    ) -> str:
+        ct = self.converter(record.created)
+        s = time.strftime(datefmt or "%Y-%m-%d %H:%M:%S", ct)
+        return f"{s}.{int(record.msecs):03d}"
+
+
+class ColorFormatter(_MillisecondTimeFormatter):
+    """控制台格式化器：按字段分别添加 ANSI 颜色。
+
+    实现思路是把颜色码作为属性挂到 ``record`` 上，再在格式串里通过
+    ``%(xxx_color)s ... %(reset)s`` 占位符把颜色串入对应字段，从而让
+    进程名、logger 名、文件位置、函数名、级别各自拥有独立的配色。
+    """
+
+    @override
+    def format(self, record: logging.LogRecord) -> str:
+        record.color = _LEVEL_COLORS.get(record.levelname, "")  # type: ignore[attr-defined]
+        record.proc_color = _PROC_COLOR  # type: ignore[attr-defined]
+        record.name_color = _NAME_COLOR  # type: ignore[attr-defined]
+        record.file_color = _FILE_COLOR  # type: ignore[attr-defined]
+        record.func_color = _FUNC_COLOR  # type: ignore[attr-defined]
+        record.reset = _RESET  # type: ignore[attr-defined]
+        return super().format(record)
+
+
+class FileFormatter(_MillisecondTimeFormatter):
+    """文件格式化器：与控制台版字段一致但不带任何 ANSI 颜色码。"""

{kitty_logger-0.1.0 → kitty_logger-0.2.0.dev0}/src/kitty_logger/_server.py

@@ -1,11 +1,13 @@
-"""日志记录接收进程。
+"""日志服务子进程实现。
 
-运行在一个独立的子进程中。接收父进程预先 bind 好的监听 socket，
-反序列化客户端进程通过 ``logging.handlers.SocketHandler`` 发来的
-``logging.LogRecord``，然后交给本进程内配置的日志 handler（文件、
-stderr 等）输出。
+工作模型：
 
-实现参考自 Python ``logging`` cookbook。
+1. 父进程在 :func:`kitty_logger.setup_logging` 中先 ``bind`` 一个 TCP
+   监听 socket，再连同其他参数一起传给一个 ``spawn`` 启动的子进程。
+2. 子进程在 :func:`run_server` 里基于这个 socket 跑 ``ThreadingTCPServer``，
+   反序列化客户端通过 :class:`logging.handlers.SocketHandler` 发来的
+   ``LogRecord`` 字节流，再用本进程里配置的 handler（FileHandler /
+   StreamHandler）落地。
 """
 
 import logging
@@ -15,24 +17,24 @@ import socketserver
 import struct
 import sys
 import threading
-from typing import cast, final, override
-
+from logging.handlers import TimedRotatingFileHandler
 from multiprocessing.synchronize import Event as MpEvent
+from typing import cast, final, override
 
 from ._formatters import ColorFormatter, FileFormatter
 
-# 单条 LogRecord 序列化后的最大字节数。超过即视为协议错乱或恶意流量，
-# 直接断开连接，避免 ``recv`` 一口气分配几个 GB 的 buffer 把进程打爆。
-# 16 MiB 已经远大于任何正常的 ``LogRecord``（含 traceback / extra）。
+# 单条 LogRecord 序列化后字节数上限。任何正常 LogRecord 都远小于此值；
+# 超过即视为协议错位或异常流量，直接断开连接，避免一次性分配巨大缓冲区
+# 触发 OOM。
 _MAX_RECORD_BYTES = 16 * 1024 * 1024
 
 
 def _recv_exact(conn: socket.socket, n: int) -> bytes | None:
-    """从 ``conn`` 上**读满** ``n`` 字节，对端关闭则返回 ``None``。
+    """从 ``conn`` 上读满 ``n`` 字节；对端已关闭则返回 ``None``。
 
-    单次 ``recv`` 不保证读满指定长度（TCP 半包），而当对端关闭后 ``recv``
-    会立刻返回 ``b""`` —— 任何"按长度循环 recv"的实现都必须显式处理 EOF，
-    否则会在客户端中途断连时陷入死循环。
+    单次 ``recv`` 不保证读够请求长度（TCP 半包），且对端关闭时
+    ``recv`` 会立刻返回 ``b""``。任何"按长度循环 recv"的实现都必须显式
+    处理 EOF，否则在客户端中途断连时会陷入死循环。
     """
     buf = bytearray()
     while len(buf) < n:
@@ -48,7 +50,11 @@ def _recv_exact(conn: socket.socket, n: int) -> bytes | None:
 
 @final
 class _LogRecordStreamHandler(socketserver.StreamRequestHandler):
-    """处理一个客户端连接上的流式日志请求。"""
+    """处理一个客户端连接上的连续 LogRecord 流。
+
+    协议沿用标准库 :class:`logging.handlers.SocketHandler`：
+    ``[uint32 大端长度][pickle 字节]``，可在同一连接上重复出现。
+    """
 
     @override
     def handle(self) -> None:
@@ -59,8 +65,6 @@ class _LogRecordStreamHandler(socketserver.StreamRequestHandler):
                 break
             slen = cast(int, struct.unpack(">L", header)[0])
             if slen == 0 or slen > _MAX_RECORD_BYTES:
-                # 长度异常的请求多半是协议不匹配或恶意流量，直接断连而不是
-                # 试图继续读，避免被诱导分配巨大 buffer。
                 break
             body = _recv_exact(conn, slen)
             if body is None:
@@ -68,29 +72,36 @@ class _LogRecordStreamHandler(socketserver.StreamRequestHandler):
             try:
                 obj = cast(object, pickle.loads(body))
             except Exception:
+                # 单条记录损坏不应连累整条连接；继续读下一条。
                 continue
             if not isinstance(obj, dict):
                 continue
             record = logging.makeLogRecord(cast(dict[str, object], obj))
-            logger = logging.getLogger(record.name)
-            logger.handle(record)
+            logging.getLogger(record.name).handle(record)
 
 
 @final
 class _LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
+    """基于 :class:`socketserver.ThreadingTCPServer` 的接收器。
+
+    复用父进程已 ``bind`` 好的监听 socket，本类不再自己 ``bind``/``listen``。
+    """
+
     allow_reuse_address: bool = True
     daemon_threads: bool = True
 
     @override
     def __init__(self, listening_sock: socket.socket) -> None:
-        # 父类正常初始化（含 _BaseServer 的 shutdown 标志位等内部状态），
-        # 但跳过 bind/listen——监听 socket 是父进程已经绑好的。
         addr = cast(tuple[str, int], listening_sock.getsockname()[:2])
+        # 走父类正常流程以建立 BaseServer 内部状态（shutdown 标志等），
+        # 但通过 ``bind_and_activate=False`` 跳过它自己的 bind/listen——
+        # 这个 socket 已经由父进程绑好。
         super().__init__(addr, _LogRecordStreamHandler, bind_and_activate=False)
-        # 关闭 ``TCPServer.__init__`` 默认创建的那个空 socket，再换成外部传入的。
+        # 父类构造时仍会 ``self.socket = socket.socket(...)`` 占坑，
+        # 这里替换成真正复用的 socket，并把临时占位关闭掉。
         try:
             self.socket.close()
-        except Exception:
+        except OSError:
             pass
         self.socket = listening_sock
         self.server_address = addr
@@ -103,9 +114,17 @@ def _build_handlers(
     file_fmt: str,
     datefmt: str | None,
 ) -> list[logging.Handler]:
+    """根据用户传入的参数组合出落地用的 handler 列表。"""
     handlers: list[logging.Handler] = []
     if log_file:
-        fh = logging.FileHandler(log_file, encoding="utf-8")
+        # 按天轮转，每天 0 点切一份，最多保留 365 天历史。
+        fh = TimedRotatingFileHandler(
+            log_file,
+            when="midnight",
+            interval=1,
+            backupCount=365,
+            encoding="utf-8",
+        )
         fh.setFormatter(FileFormatter(fmt=file_fmt, datefmt=datefmt))
         handlers.append(fh)
     if stream:
@@ -126,7 +145,23 @@ def run_server(
     file_fmt: str,
     datefmt: str | None,
 ) -> None:
-    """日志服务子进程的入口函数。"""
+    """日志服务子进程入口函数。
+
+    通过 :mod:`multiprocessing` 在 ``spawn`` 出来的全新解释器里运行；
+    所有依赖参数显式从 ``kwargs`` 进入，不依赖父进程的全局状态。
+
+    :param listening_sock: 已经由父进程 ``bind`` + ``listen`` 好的 socket。
+    :param shutdown_event: 父进程通知子进程正常退出用的事件。
+    :param parent_alive_recv: ``socketpair`` 的接收端，用来侦测父进程死亡。
+    :param level: 服务端 root logger 级别。
+    :param log_file: 日志文件路径；``None`` 表示不落盘。
+    :param stream: 是否同时输出到 ``stderr``。
+    :param console_fmt: 控制台 handler 的 format 字符串。
+    :param file_fmt: 文件 handler 的 format 字符串。
+    :param datefmt: 时间戳的 ``strftime`` 格式；``None`` 走默认值。
+    """
+    # 子进程是 ``spawn`` 出来的全新解释器，root logger 默认无 handler；
+    # 但仍保险地清掉一遍以便重复初始化场景下的幂等性。
     root = logging.getLogger()
     for h in list(root.handlers):
         root.removeHandler(h)
@@ -141,9 +176,9 @@ def run_server(
         server.shutdown()
 
     def _watch_parent_alive() -> None:
-        # 父进程持有 socketpair 的 send 端；任何原因导致父进程消失（正常退出、
-        # SIGKILL、段错误等），内核都会关闭它的 fd，本端 ``recv`` 会立刻得到
-        # 空字节（EOF）。借此触发服务自我退出，避免变成孤儿进程。
+        # 父进程持有 socketpair 的发送端；任意原因（正常退出 / SIGKILL /
+        # 段错误）使父进程消失，内核都会关闭它的 fd，本端 ``recv`` 会立刻
+        # 返回空字节（EOF）。借此触发自我退出，避免变成孤儿进程。
         try:
             while True:
                 data = parent_alive_recv.recv(64)
@@ -154,7 +189,7 @@ def run_server(
         finally:
             try:
                 parent_alive_recv.close()
-            except Exception:
+            except OSError:
                 pass
         shutdown_event.set()
 
@@ -166,6 +201,6 @@ def run_server(
     finally:
         try:
             server.server_close()
-        except Exception:
+        except OSError:
             pass
         logging.shutdown()