Python WatchedFileHandler 怎样配合外部日志轮转

如果日志文件由 Linux 上的 logrotate、newsyslog 一类工具负责轮转，应用侧通常不应该再自己改文件名。logging.handlers.WatchedFileHandler 会在每次写日志前检查目标文件的设备号和 inode；发现文件已经被外部轮转器重命名并创建新文件后，它会关闭旧流，再按原路径重新打开。

官方文档：https://docs.python.org/3/library/logging.handlers.html

最稳妥的组合是：Unix/Linux 上让外部工具负责轮转，让 WatchedFileHandler 负责发现“当前路径对应的文件已经换了”。但如果外部工具使用的是 copytruncate，inode 通常不变，不能把它当成同一种轮转；Windows 也不适合使用这个处理器。

• 适合：外部轮转通过重命名旧文件、再创建同名新文件完成。
• 不等价：copytruncate 只是复制后截断原文件，设备号和 inode 可能保持不变。
• 职责边界：一个日志文件只选一套轮转策略，不要同时让应用和系统工具改名、删备份。

先判断外部轮转是否改变 inode

WatchedFileHandler 不是按大小或按时间主动轮转的 handler，它的核心工作是观察“自己正在写的文件是否还是同一个文件”。官方实现把设备号和 inode 的变化作为文件已更换的信号；外部轮转器把 app.log 重命名为备份文件，再创建一个新的 app.log 时，这个条件通常成立。

因此，先看外部工具的动作比先改 Python 代码更重要。若采用 rename/create，应用继续使用固定路径即可；若采用 copytruncate，原文件仍被同一个打开流引用，单靠 WatchedFileHandler 不会凭空获得“发现截断”的能力。此时要么调整轮转策略，要么明确接受 copytruncate 的风险和语义。

配置 WatchedFileHandler 写入固定路径

下面的配置把轮转职责留给外部工具。delay=True 让文件在第一次真正写日志时再打开，encoding="utf-8" 固定文本编码；propagate=False 则避免同一条记录继续冒泡到根 Logger 后被第二个 handler 重复输出。

from logging.handlers import WatchedFileHandler
from pathlib import Path
import logging

def build_logger(log_path: Path) -> logging.Logger:
    # 为本模块创建独立 Logger，避免修改全局根 Logger 的 handler
    logger = logging.getLogger("service.worker")
    logger.setLevel(logging.INFO)
    logger.propagate = False

    # 防止重复调用配置函数时不断追加相同的 handler
    if not logger.handlers:
        handler = WatchedFileHandler(
            filename=log_path,
            encoding="utf-8",
            delay=True,
        )
        # 格式化器只负责输出格式，不负责文件轮转
        handler.setFormatter(logging.Formatter(
            "%(asctime)s %(levelname)s %(name)s %(message)s"
        ))
        logger.addHandler(handler)

    return logger

logger = build_logger(Path("/var/log/my-service/app.log"))
logger.info("worker ready")  # 每次 emit 前由 handler 检查文件是否已更换

这段代码的关键不是把 handler 绑到某个备份文件，而是始终写入外部工具会重新创建的那个固定路径。WatchedFileHandler.emit() 会先调用重新打开检查，然后再输出当前记录；没有新日志时，它也不会主动替你产生一个新文件。

让应用和外部轮转各管一件事

部署时可以把规则拆成两部分：Python 进程只打开 /var/log/my-service/app.log，外部轮转器负责何时重命名、保留多少份、是否压缩。轮转器的具体配置取决于发行版和运维规范，本文只讨论 Python handler 与文件身份的对应关系，不把某个系统配置格式当成通用答案。

一个容易混淆的场景是把 WatchedFileHandler 与 RotatingFileHandler 同时挂在同一个 Logger 上。前者期待外部改变文件身份，后者会在应用内部按大小重命名；两套规则可能互相覆盖备份名、遗漏文件或造成多个流同时写入。若决定由应用自己按大小轮转，应直接评估 RotatingFileHandler；若决定由系统轮转，就保留一个 WatchedFileHandler。

处理并发、平台和退出清理

在 Unix/Linux 上，多个进程各自持有自己的 handler 时，每个进程都只能观察自己的文件流和文件身份；不要把“能重新打开”理解成跨进程日志合并或严格顺序保证。多进程写同一个普通文件还要结合部署模型评估记录交错、权限和锁策略。

官方文档明确说明，这个 handler 面向 Unix/Linux；Windows 上打开的日志文件不能像 Unix 文件那样被移动或重命名，而且 ST_INO 不提供同样的判断依据。跨平台程序应按运行平台选择策略，不要仅因为代码能导入类就认为语义一致。

def close_logger(logger: logging.Logger) -> None:
    # 退出或重新加载配置前关闭文件句柄，避免留下旧的打开流
    for handler in logger.handlers[:]:
        handler.flush()  # 先把缓冲内容交给底层流
        handler.close()  # 再释放文件资源
        logger.removeHandler(handler)  # 防止下次配置重复挂载旧 handler

try:
    logger.info("service stopping")
finally:
    # 应用退出时显式清理属于自己的 handler
    close_logger(logger)

如果只是普通长驻进程，Python 的日志关闭流程通常会参与退出清理；显式封装仍然有助于热重载、测试和多次初始化场景。真正需要复查的是：外部工具是否创建了新路径、进程是否继续向固定路径写、以及部署平台是否允许这种文件替换方式。

常见问题

WatchedFileHandler 会按时间自动切割日志吗？

不会。它只在写日志前检查文件身份是否变化；按时间或大小切割应由外部轮转工具或专门的应用内 handler 负责。

为什么 copytruncate 后仍然能继续写，但不能说明 handler 发现了轮转？

因为原打开流可能仍然指向同一个 inode。截断后继续写只说明文件描述符还能工作，不等于 handler 重新打开了一个新文件。

可以给同一个文件同时挂两个 WatchedFileHandler 吗？

通常没有必要。两个 handler 会各自检查并写入，容易造成重复日志；除非每个 handler 的输出目标、格式或生命周期确实不同，否则保留一个更清晰。

Windows 项目应该直接改用 RotatingFileHandler 吗？

不一定。若需求是应用内按大小或时间轮转，可以评估对应的应用内 handler；若日志交给 Windows 服务或集中式采集器，也应按其文件锁和采集约定选择方案。

归根结底，WatchedFileHandler 解决的是“外部轮转改变了当前路径对应的文件身份，应用如何继续写”的衔接问题。先确定轮转动作，再选择 handler，最后确认平台和进程模型，通常比单纯更换一个类名更可靠。