Python logging RotatingFileHandler 轮转后如何保留最近几份

如果 Python 服务的 app.log 越写越大，最直接的做法是使用 logging.handlers.RotatingFileHandler。它按文件大小触发轮转：maxBytes 决定什么时候换文件，backupCount 决定最多留下多少个带编号的旧文件。比如 backupCount=3 时，磁盘上通常会看到当前的 app.log，以及 app.log.1、app.log.2、app.log.3。

先把保留数量换算成文件名

RotatingFileHandler 的命名规则很固定：当前写入目标始终是 app.log，发生轮转后它被改成 app.log.1；已有的 .1 依次后移为 .2，直到达到备份上限，最旧的一份被丢弃。因此，backupCount 不是“总文件数”，而是“旧文件数量”。

还要注意两个容易忽略的条件：maxBytes=0 时不会按大小轮转，backupCount=0 也不会保留备份。生产配置可以先从单文件 20 MB、保留 5 份开始，再依据磁盘预算调整。只要磁盘预算是硬约束，就把“当前文件大小 ×（backupCount + 1）”作为粗略上限，而不是只看备份数字。

用 RotatingFileHandler 固定轮转边界

下面的配置把轮转范围写得很明确。delay=True 可以让文件在第一次真正写日志时再打开；encoding="utf-8" 避免中文日志在不同环境中出现编码差异。示例中的中文注释只解释关键参数，不把每一行都变成注释。

import logging
from logging.handlers import RotatingFileHandler

logger = logging.getLogger("order-service")
logger.setLevel(logging.INFO)

# 只有 maxBytes 和 backupCount 都非零时，才会按大小轮转
handler = RotatingFileHandler(
    "app.log",
    maxBytes=20 * 1024 * 1024,
    backupCount=3,          # 保留 app.log.1 到 app.log.3
    encoding="utf-8",
    delay=True,
)

# 统一格式，避免轮转后不同文件难以检索
handler.setFormatter(logging.Formatter(
    "%(asctime)s %(levelname)s %(name)s %(message)s"
))
logger.addHandler(handler)

logger.info("订单服务已启动")

这个例子最终最多约有四个文件：正在写入的 app.log 加三份备份。若重启后发现日志文件数量没有按预期变化，先检查是否真的使用了这个 handler，以及代码是否在初始化函数被重复调用，导致同一个 logger 被添加了多个 handler。

并发写入时把轮转动作集中起来

同一进程内的多个线程通常可以共享同一个 logging handler；但多个进程各自打开同一个 app.log 时，大家都可能判断“快到上限了”，并同时执行改名。backupCount 只负责备份链的数量，不负责跨进程锁和消息协调。

如果应用已经采用线程池或进程池，更稳妥的结构是让工作线程只产生日志记录，由 QueueHandler 放入 queue.Queue，再由单独的 QueueListener 持有 RotatingFileHandler。这样真正改名和写文件的对象只有一个。

如果是多个独立进程，不能只把 QueueHandler 换成普通进程内队列就结束：队列的生命周期、监听器退出时的刷新，以及进程异常退出后的剩余记录，都要一并设计。对高并发服务，也可以把文件轮转交给外部日志代理或系统级日志服务，Python 进程只负责输出记录。

用检查清单确认没有少留或无限增长

最后按“参数—文件名—进程模型”三层检查：先看配置是否触发轮转，再看 app.log.1 到 app.log.N 是否形成连续链，最后确认是否存在多个进程同时持有同一个文件 handler。这样能把“保留几份”的问题与“谁负责写文件”的问题分开处理。

相关问题

backupCount=1 时总共会有几个文件？

通常是当前的 app.log 加一份 app.log.1，也就是最多约两个文件，实际数量还取决于是否已经触发过轮转。

为什么设置了 backupCount 还是不轮转？

先确认 maxBytes 不是 0，并确认写入量确实接近上限；如果使用的是 TimedRotatingFileHandler，它按时间而不是按文件大小工作。

多个进程能共用 RotatingFileHandler 吗？

不建议把同一个文件直接交给多个进程各自轮转。应集中写入、使用进程安全的日志组件，或交给外部日志系统管理轮转。