聊一个每个 Python 后端项目迟早都会踩的雷Python 日志轮转。我见过不少项目上线后跑得挺正常结果某天磁盘满了才发现app.log已经十几个 G而标准库logging.handlers里早就提供了轮转能力只是没被用上。这篇文章就从RotatingFileHandler和TimedRotatingFileHandler开始带你把日志轮转快速落地顺带把我这些年踩过的坑一并交代了。1. 为什么日志必须轮转磁盘撑爆只是最轻的代价1.1 日志自增长的“惊喜”一个后端服务只要在运行日志就会不停增长。你以为每天只有几百 MB但一旦某个接口进入异常重试循环或者有一个忘记关闭的调试开关日志量可以一夜之间涨到几个 G。等到磁盘告警服务开始写不进任何文件数据库连接也跟着出问题这时候再排查往往需要花比写轮转代码多得多的时间。更隐蔽的是单个日志文件过大tail -f还能忍但grep一次就卡半天编辑器直接打不开按行数截取也要读完整的文件。日志的核心价值是“事后定位”如果日志文件变成了一个巨大的黑盒定位问题的效率会急剧下降。很多团队一开始不上轮转理由是“上线前日志量测过不大”但线上数据和预演数据完全是两回事流量抖动、活动流量、下游超时重试都会让日志量发生量级变化。1.2 logging.handlers 自带轮转能力的边界Python 的logging模块作为标准库其实已经把“轮转”这个常见需求做了封装。logging.handlers里提供了RotatingFileHandler按字节数切割、TimedRotatingFileHandler按时间周期切割、WatchedFileHandler检测文件被外部替换后重新打开这三个已经能覆盖绝大部分单体应用和中小架构。不过自带工具不等于拿来即用。RotatingFileHandler的轮转是基于单进程内的写入流程触发的TimedRotatingFileHandler的“定时”也不是操作系统任务计划而是“下一次写日志时检查时间是否到了”。理解这些边界比会调用 API 更重要。很多人把日志轮转配好后发现“不生效”大多是没搞懂这套触发机制。我个人的建议是先把自带 handler 的源码读一遍至少读BaseRotatingHandler和TimedRotatingFileHandler的shouldRollover与doRollover这两个方法决定了所有轮转行为。读完以后很多报错一眼就能定位。2. 两种自带轮转 Handler什么时候选哪个2.1 RotatingFileHandler按文件大小切分RotatingFileHandler是最常用的。它判断当前日志文件是否超过maxBytes设定的字节数超过就执行一次轮转。轮转时现有文件会依次改名app.log变成app.log.1原来的app.log.1变成app.log.2依此类推保留backupCount个备份。最老的那个备份会被删除避免磁盘被备份慢慢吃光。一个最小例子可以直接跑import logging from logging.handlers import RotatingFileHandler handler RotatingFileHandler( app.log, maxBytes10 * 1024 * 1024, backupCount5, encodingutf-8, ) handler.setFormatter(logging.Formatter(%(asctime)s [%(levelname)s] %(name)s: %(message)s)) logger logging.getLogger(app) logger.addHandler(handler) logger.setLevel(logging.INFO) logger.info(hello, rolling!)这段代码会把日志写到同目录下的app.log单文件超过 10MB 后开始轮转最多保留 5 个备份文件。注意maxBytes只是触发阈值不是硬性上限因为每条日志是先写入后判断单条日志特别长时实际文件可能略超阈值。选择大小轮转变量的核心是“单文件可容忍度”。我个人会把maxBytes设在 10MB 到 100MB 之间backupCount按磁盘空间倒推。假设每天 500MB 日志保留 7 天约 3.5GB是一个比较合理的容量。如果日志量小也可以把maxBytes调小到 1MB方便本地调试时能快速看到轮转效果。2.2 TimedRotatingFileHandler按时间切分当你更关心“某个时间点以前的日志去哪里了”时按大小切分就不够直观。举个例子排查一个问题你希望“昨天的日志在昨天的文件里”这时候用TimedRotatingFileHandler更合适。from logging.handlers import TimedRotatingFileHandler handler TimedRotatingFileHandler( app.log, whenmidnight, backupCount7, encodingutf-8, )when参数控制轮转周期取值包括S秒、M分钟、H小时、D天、midnight每天零点、W0~W6周一到周日。backupCount在这里不是“保留几个文件”而是“保留几个轮转周期”。比如whenD, backupCount7就是保留最近 7 天的备份。这里有一个容易踩的坑TimedRotatingFileHandler判断“是否该轮转”是在写入日志时触发的不是后台定时器。如果某个周期内完全没有日志到时间不会立刻生成新文件而是在下一次写入时发现已经超过周期然后一次性补执行轮转。对于低流量的服务这可能让日志文件的时间归属和你预期不完全一致。另一个坑是备份文件名。默认的命名是app.log.2025-06-01这种带日期的形式但suffix和通过namer自定义后规则会变化。如果你后续要写脚本统计“昨天的日志”建议先手动创建一条日志触发一次轮转看看实际文件名再写匹配规则。2.3 参数选择速查用一个表格把几个关键参数放一起方便抄作业Handler核心参数触发时机默认备份名适用场景RotatingFileHandlermaxBytes、backupCount文件字节数超过阈值app.log.1、app.log.2日志大小稳定关心磁盘占用TimedRotatingFileHandlerwhen、backupCount当前时间超过计算的下一次轮转点app.log.2025-06-01按天/小时归档排查按时间分段WatchedFileHandler无文件可被外部替换每次写入前比对 inode/设备/大小无不做轮转配合系统 logrotate外部切分注意RotatingFileHandler的maxBytes和backupCount必须同时设置文档里明确写了如果maxBytes为 0轮转不会发生。很多新手只配了maxBytes忘了backupCount结果发现文件从来不切第一个排查方向就是这个。3. 快速落地的标准配置模板3.1 dictConfig 按大小轮转模板真正项目里不建议在业务模块里手动addHandler那样 logger 容易越加越乱。更规范的做法是用logging.config.dictConfig集中管理。下面是一份可以直接放进项目里的基础配置import logging.config LOGGING_CONFIG { version: 1, disable_existing_loggers: False, formatters: { standard: { format: %(asctime)s [%(levelname)s] %(process)d %(name)s: %(message)s, datefmt: %Y-%m-%d %H:%M:%S, } }, handlers: { console: { class: logging.StreamHandler, formatter: standard, }, file: { class: logging.handlers.RotatingFileHandler, filename: logs/app.log, maxBytes: 10485760, backupCount: 5, encoding: utf-8, formatter: standard, }, }, root: { handlers: [console, file], level: INFO, }, } logging.config.dictConfig(LOGGING_CONFIG)这里的version固定为 1disable_existing_loggers如果设成默认的True可能会把第三方库已经创建的 logger 禁用导致某些库日志消失在配置后。所以在项目里我会显式写成False。日志文件路径用了logs/app.log但logging不会自动创建logs目录记得在应用启动时补一个os.makedirs(logs, exist_okTrue)。配置完以后业务里直接用logging.getLogger(__name__)拿到子 logger 即可。因为 root logger 有 handler子 logger 默认会向上传播所以不用每个模块再配置 handler日志会统一走到 root 的 file handler完成轮转。如果某个模块有自己的 logger 配置注意它可能不再向上传播需要单独确认。3.2 按天轮转模板与目录初始化如果业务上更需要按天归档把filehandler 的class替换成logging.handlers.TimedRotatingFileHandler然后加when和backupCountfile: { class: logging.handlers.TimedRotatingFileHandler, filename: logs/app.log, when: midnight, backupCount: 14, encoding: utf-8, formatter: standard, }单独把目录初始化写成一个小函数放到应用入口执行import os from pathlib import Path def ensure_log_dir(log_path: str) - None: log_dir Path(log_path).parent log_dir.mkdir(parentsTrue, exist_okTrue)这样配置和启动代码分离换路径、换轮转策略都不用改动业务逻辑。日志轮转配置的维护成本主要在于“改文件名规则”和“清理策略”用 dictConfig 集中表达以后团队里任何人打开都能看清楚整个日志链路不需要一个模块一个模块去翻代码。3.3 为什么不用每个模块自己 new handler我在一些项目里见过这种写法每个 Python 文件顶部都来一个logging.basicConfig或者RotatingFileHandler(...)结果日志文件出现多份、重复打印、进程句柄泄漏。原因很简单模块级的 handler 在 import 时创建同一个 logger 会被反复添加 handler。标准做法是只在应用入口配置一次 handler业务模块只负责创建 logger 和打印日志。如果确实需要在不同子目录写不同日志比如“请求日志”和“错误日志”分开可以给不同 logger 配置不同 handler但每个 logger 的 handler 来源应该是配置文件而不是模块内拼装。这个思路能让日志行为全局可控线上排查时不用推理某个模块当时是怎么创建的。4. 多进程与外部轮转自带 Handler 的隐藏坑4.1 多进程写同一个文件的经典问题logging模块保证的是单进程内的线程安全不是进程安全。使用RotatingFileHandler时如果多个进程同时打开同一个app.log每个进程的文件偏移量独立维护日志行可能互相穿插甚至覆盖。更糟的是轮转动作两个进程可能同时判断“该轮转了”同时执行 rename结果备份文件被覆盖日志丢失。一个常见场景是 Web 服务用多进程模型比如某些 WSGI 服务器启动多个 worker每个 worker 都是独立进程。此时如果直接共用一个RotatingFileHandler线上一定会出现日志错乱。解决办法有好几档最省事每个进程写自己的日志文件比如文件名带上process id或 worker 编号最后在日志采集端合并。标准做法用QueueHandler把所有进程的日志发送到一个队列由单独一个进程或线程用QueueListener统一写文件。这样轮转发生在单写者进程中天然避免竞争。或者直接用支持多进程的第三方 handler但依赖引入需要评估。如果只是少量并发进程、日志量也不大WatchedFileHandler可以缓解“外部替换文件”的问题但它本身也不解决多进程轮转的竞争问题别指望它做多进程安全。4.2 WatchedFileHandler 配合系统级 logrotate如果你不想在 Python 进程内做轮转而是想交给系统自带的logrotate那么WatchedFileHandler值得留意。它的行为是每次写入日志前检查当前打开文件的 inode、设备号和文件大小是否和第一次打开时一致如果不一致说明文件被外部移动或重建了于是重新打开新路径的文件继续写入。from logging.handlers import WatchedFileHandler handler WatchedFileHandler(app.log, encodingutf-8)WatchedFileHandler本身不做任何轮转它只是“跟住”文件名。系统logrotate按天或大小把app.log重命名为app.log.1并新建空文件app.logPython 进程会在下一次写日志时发现原文件被替换立刻切换到新文件。这个方案的好处是轮转策略集中在系统层不依赖 Python 进程的生命周期就算进程重启、崩溃也能被系统兜底。我一般只推荐这种用法进程对日志文件没有强绑定接受最多“下一次写入”后切换的延迟。日志量极低、半天没日志的服务切换延迟可能很长但通常可以接受。注意WatchedFileHandler在多进程下依然不是进程安全多个进程写入新文件还是会有交错问题。4.3 进程安全方案简析QueueHandler QueueListener如果是真正需要多进程安全轮转的服务建议用logging.handlers.QueueHandler配合logging.handlers.QueueListener的官方方案。原理不复杂业务进程只负责把日志事件放进一个queue.Queue写入端由独立线程从队列取事件并调用真正的文件 handler。因为写文件、轮转都在同一个线程里发生不存在多个进程争抢文件偏移的问题。简单示意import logging import logging.handlers import queue log_queue queue.Queue(-1) queue_handler logging.handlers.QueueHandler(log_queue) memory_handler logging.handlers.RotatingFileHandler( app.log, maxBytes10 * 1024 * 1024, backupCount5, encodingutf-8 ) listener logging.handlers.QueueListener(log_queue, memory_handler) listener.start() root logging.getLogger() root.addHandler(queue_handler) root.setLevel(logging.INFO) # 业务进程都使用这个 root日志先到 queuelistener 负责写入和轮转注意QueueListener需要在进程退出时listener.stop()否则队列里没写完的日志可能丢失。这个方案的缺点是日志是异步写入的崩溃时最后几条可能来不及落盘优点则是把复杂的并发写文件问题压缩成了一个单写线程。对于大多数 Web 服务来说这是比“每个进程各写各”更干净的归宿。5. 扩展技巧改成 gz 压缩、自定义备份名5.1 用 namer rotator 给轮转文件压缩日志轮转之后备份文件如果一直不压缩磁盘占用依然会随着时间缓慢增长。对按天轮转的场景旧日志压缩率通常很高文本日志能压到十分之一上下。Python 3.3 之后BaseRotatingHandler提供了namer和rotator两个钩子可以自定义轮转后的文件名和实际搬运动作。给TimedRotatingFileHandler加压缩的一个典型写法import gzip import os import shutil def namer(name): return name .gz def rotator(source, dest): with open(source, rb) as f_in, gzip.open(dest, wb) as f_out: shutil.copyfileobj(f_in, f_out) os.remove(source) handler TimedRotatingFileHandler(app.log, whenmidnight, backupCount30) handler.namer namer handler.rotator rotator这里namer做的事情是把默认的app.log.2025-06-01改成app.log.2025-06-01.gzrotator则是从原始文件生成一个 gzip 文件并删掉原始文件。配置完以后旧日志会自动变成.gz日志量一下子小很多。需要注意如果你自定义了namer备份保留数量backupCount在清理旧文件时也是基于namer返回的文件名进行匹配所以保持文件名中的时间特征很重要否则清理逻辑可能认不出哪些是旧备份。上线前建议手动触发一次轮转看看生成的备份名和清理结果是否符合预期。5.2 自定义轮转逻辑的思路自带的RotatingFileHandler和TimedRotatingFileHandler已经覆盖大多数需求但如果需要“文件达到 100MB 或跨天先到先切”的组合规则就要动手写自定义 handler。思路不是重写整个logging而是继承BaseRotatingHandler覆写shouldRollover方法和doRollover方法。shouldRollover返回True表示需要轮转你可以在里面同时判断文件大小和当前时间。doRollover则负责重命名、清理旧备份、重新打开新文件。组合规则的难点是清晰定义“一个轮转周期”是按大小触发还是按时间触发触发后旧文件归属于哪个周期。最常见的做法是偏重按时间分文件再用文件大小作为强制切割条件避免单文件过大。自定义 handler 的好处是业务可控坏处是容易引入隐蔽 bug。如果不是团队里确实有公共基础件需求我建议优先组合两个自带 handler —— 比如用RotatingFileHandler做大文件保护用TimedRotatingFileHandler做按天归档两个 handler 同时挂到同一个 logger虽然会写两份日志但大多数时候可以接受或者根据场景选择一个。6. 常见问题排查实录6.1 日志一直不轮转先查这四个地方很多同学配了RotatingFileHandler日志也正常写但文件就是不切。我一般按这个顺序排查确认 handler 真的挂到了当前 logger 上而不是配到了另一个 logger。用logging.getLogger(app).handlers直接打印一下。确认maxBytes和backupCount都设置了缺一个都不会按大小轮转。确认文件权限。如果日志文件是 root 创建的当前 Python 进程没有写权限重命名会直接抛异常而异常可能被 logging 模块吞掉只会在 stderr 里看到一条记录。确认日志最终是写到你配置文件里那个文件。有时候项目里多个地方调用了basicConfig后续调用覆盖了之前的配置你以为挂了轮转实际 handler 已经被换掉了。另外记得在测试环境写一个“日志刷量”的小脚本打 50 万条日志观察轮转是否发生。这种验证成本很低能避免上线后才发现配置无效。6.2 轮转后内容还在写旧文件这种现象多发生在外部工具配合场景。比如你自己没用 Python 的自带轮转而是用系统logrotate在外部把app.log重命名成了app.log.1。此时 Python 进程的文件描述符还指向原来的 inode系统创建的app.log反而没人写日志就“消失”了而app.log.1还在继续变大。解决办法是换用WatchedFileHandler它会在每次写入前比较 inode发现文件被替换后自动打开新文件。不要在自定义代码里用os.rename后还期望原 handler 能自动跟随FileHandler没有这个机制。6.3 Windows 下文件占用导致轮转失败Windows 对已打开文件的重命名限制比 Linux 严格。RotatingFileHandler在轮转时要把app.log改成app.log.1如果这个文件正被 Excel、文本编辑器或杀毒软件占用os.rename会失败并抛出权限错误。在 Windows 上部署 Python 服务时一定要确认没有外部程序常驻打开日志文件。如果确实要长期在 Windows 环境跑并且日志量不小建议用QueueListener把写文件和轮转限定在一个线程内同时避免任何 GUI 工具打开日志目录下的文件。或者直接用第三方支持 Windows 的 handler但在选型时先做一轮压力测试不要只看文档。6.4 backupCount 到底保留几个文件RotatingFileHandler的backupCount5表示除了当前正在写入的app.log还保留app.log.1到app.log.5五个备份。有人会误以为备份总数是 5 个实际是 6 个日志文件当前5个备份。TimedRotatingFileHandler类似按天轮转时除了当前文件还保留最近 5 个时间点的备份文件。计算磁盘占用时记得把正在写的文件也算进去否则备份总大小会比预期多一个文件。6.5 编码和日志格式的“玄学”日志内容里如果有中文handler 没设置encodingutf-8默认会按照系统字符集写文件在 Linux 上通常是 UTF-8在 Windows 上可能是 GBK后续处理日志的脚本如果统一按 UTF-8 打开就会乱码。建议所有文件 handler 都显式传encodingutf-8。另外如果发现日志里的%字符没了或者变成%%多半是格式化字符串套了两层logging.Formatter多检查一层setFormatter的调用。日志时间格式也别忽视。%(asctime)s默认包含毫秒datefmt一旦设置成%Y-%m-%d %H:%M:%S毫秒会消失。日志轮转按时间归档时是否保留毫秒通常不影响但如果你用日志时间做排序最好保持一致。6.6 如果日志轮转配置本身没生效怎么快速验证我会在一个临时脚本里直接调用 handler 的doRollover()强制触发一次轮转查看生成的备份文件名和后续写入行为。比如handler.doRollover()这样能跳过等待文件变大的过程快速确认命名规则、压缩钩子和清理逻辑是否正常。强制轮转后再写一条日志确认新文件能继续写入、句柄没有丢。如果连这个调用都异常基本就是 handler 构造参数有问题或者目录权限不对。用强制轮转做单元测试比等线上出问题再查要高效得多。7. 最后说几句实操体会7.1 我的默认配置组合我在实际项目里一般默认采用这样的组合本地开发用控制台输出测试和预发环境用按天轮转 保留 30 天单文件超过 200MB 再叠加一个RotatingFileHandler做兜底。压缩钩子只在日志量明显大的模块里启用避免所有日志文件都加一层 gzip 导致排查时要多解压一步。轮转不是越复杂越好。对很多中小规模项目来说TimedRotatingFileHandler按天切分加上合理的backupCount已经够用与其花时间研究各种高级 handler不如先把磁盘监控和日志采集接上让“日志有没有在正常轮转”“备份清理是否达标”变成可以被观察的指标。7.2 日志轮转回归测试最后分享一个小技巧把日志轮转的验证脚本写进自动化测试里每次发布前跑一次确认轮转文件名、保留数量、压缩功能没有回归。日志这层基础设施平时不显山露水出了问题却是焦头烂额花十分钟做一次回归比线上翻车后花一小时排查值多了。