tuowei2这个代号第一次听的人都会问一句啥意思其实它是我本地维护的一套服务器磁盘巡检与日志清理工具tuowei是“拓位”的拼音第二版。工具本身不复杂但迭代到这个版本的过程中踩了不少值得记录的坑也让我把“能跑的脚本”和“扛得住的生产级工具”之间的差距彻底想明白了。这套东西解决的是所有后端都会遇到的痛日志文件只增不减磁盘总有写满的一天。tuowei2会自动扫描各个目录的占用按策略清理过期日志生成报表并在磁盘水位超过阈值时发出告警。如果你是那种被磁盘告警在凌晨叫醒的人或者你的服务经常因为日志把磁盘写满而卡死这篇文章应该能帮上忙。我会把tuowei2从设计思路、核心代码、上线前后踩坑的完整过程摊开来说既有可以直接抄走的片段也有只有跑过生产环境才懂的细节。1. 两个版本的分水岭v1从能用到难用的全过程1.1 一切的起点凌晨两点的磁盘告警做v1的动机非常朴素。有一年春天我维护的一个运营后台开始频繁打磁盘告警查下来是业务日志和Nginx access log疯涨单台机器每天新增几个GB根分区只剩不到10%。当时图省事我写了大概50行shell脚本find指定目录按mtime删除超过7天的日志再用du统计剩余空间如果超过80%就给运维群发一条curl通知。脚本丢进crontab里每天凌晨1点跑一次。当时觉得这事已经“解决”了。但一个工具能跑和能用是两码事v1坚持了不到半年就暴露出一堆只在生产环境才显现的问题。最典型的场景是你明明每天在删日志磁盘占用却还在涨因为业务临时文件、导出文件、备份文件都不在清理规则里它们会悄悄把磁盘吃满。1.2 v1的三条致命短板第一个短板是清理策略写死在代码里。目录列表、保留天数、触发阈值全是一堆变量塞在脚本顶部每次要调整都得ssh登录服务器改脚本改完还要手工重跑一遍验证。岗位交接的时候新同事看那脚本一头雾水注释只有一行“删除7天前的日志”。第二个短板是没有任何前置检查。有一次日志目录下出现了大量临时导出文件占了好几十GB但它们不是日志mtime只有3天find命令根本不碰它们。结果磁盘还是飙到95%服务开始报no space left on device用户那边直接看到白屏。事后排查才发现清理逻辑只认文件年龄根本不看磁盘真实水位也不看目录里到底堆了什么。第三个短板是误删风险不可控。find rm的组合在路径写错的时候非常致命尤其当变量拼接路径时如果某个目录为空字符串rm -rf可能会落在意想不到的位置。虽然v1没有真正删错东西但那种“不知道自己会不会删错”的感觉比磁盘告警还让人焦虑。每天凌晨cron跑完之后我都要爬起来瞄一眼日志确认没有把不该删的东西删掉。1.3 为什么选择重写而不是接着打补丁其实在v1后期我已经往里面塞了各种补丁加了磁盘水位预判、加了排除目录、加了日志输出。但每次改完都觉得脚本越来越像一堆临时方案叠在一起。当时给了我自己两个选择继续在shell脚本上打补丁或者用Python重写一版把配置、执行、报表、告警拆开。我选了重写理由有三条。第一shell做简单的find和rm够用但要处理遍历性能、并发锁、幂等重放、结构化报表成本会越来越高Python在这些方面有现成的标准库。第二配置外置是刚需我不希望下一次调整策略还要进服务器改脚本。第三v1最欠缺的不是功能而是可观测性——跑完之后发生了什么、删了什么、还剩多少这些信息必须能追溯而这正是shell脚本最薄弱的地方。工具一旦不可观测出了问题就只能靠猜。2. tuowei2的核心设计从脚本思维到任务编排思维2.1 先把职责拆清楚四个模块各管一段tuowei2的整体结构非常简单简单到再复杂的场景也是围绕同一套骨架扩展collector扫描指定目录统计占用产出结构化数据。cleaner基于策略执行清理但所有删除操作前先进入“演练模式”。reporter把扫描和清理结果渲染成报表。notifier通过Webhook把报表和告警发出去。四个模块通过一个主流程串起来各自只依赖配置不互相调用内部函数。这样做的直接好处是想单独跑一遍扫描不清理或者只重发一次报表都不需要动逻辑命令行指定模块即可。我曾经把collector单独接进一个数据看板让它每10分钟跑一次清理还是按天跑两个流程互不干扰。这种“模块边界清晰”带来的自由度是v1那种一个脚本从头跑到尾的结构没法给的。2.2 配置外置改策略不用碰代码我选择用YAML做配置因为它的可读性对不写代码的人比如接班的同事最友好。配置片段大致是这样scan: - path: /var/log/app name: app_logs clean: enabled: true max_age_days: 7 max_dir_size_mb: 4096 - path: /data/export name: exports clean: enabled: false global: disk_threshold_percent: 80 dry_run: true pid_lock: /var/run/tuowei2.pid timezone: Asia/Shanghai关键点是每条扫描路径都可以独立设置保留天数、大小上限、是否参与删除。比如导出目录只统计不删除应用日志既按天数又按大小双条件清理。所有策略改动都只发生在YAML里脚本本身不碰业务逻辑。之前v1要改一个阈值需要进服务器操作现在只需要在一个公共的配置文件里改值然后reload一下就生效这对我这种同时维护多台机器的人来说体验是质的飞跃。2.3 任务状态机与失败重试主流程我设计成一个小状态机pending、scanning、cleaning、reporting、done以及两个失败态cleaning_failed和reporting_failed。整个流程是顺序的但clean失败不会让report和notify中断——宁可先把问题暴露出来也不能让一次清理故障吞掉告警信息。这句话说起来容易实际设计时我反复纠结过cleaning失败之后到底要不要继续report后来想明白了必须继续因为report里会带上cleaning失败的明细这本身就是最有价值的告警内容。重试只针对notifier。Webhook偶发超时很常见所以发送带三次重试每次间隔指数退避。扫描和清理不自动重试因为重复扫描代价高、重复清理可能出问题这类任务应该让人去看日志而不是让机器反复尝试。如果你在做类似的运维工具我建议你也遵循这个原则凡是有副作用的操作失败了一定要停下来等人处理不要自作主张重试。2.4 幂等设计重复执行也要安全这是我这次重写最看重的一点。v1最大的心理负担就是手误重跑一遍会不会出问题。tuowei2对每个清理动作都做记录删除前先把目标文件的path、size、mtime写入历史库一个本地SQLite文件再执行删除。万一action日志和实际删除不同步也能通过SQLite完整回溯。加上dry_run参数默认首次部署时强制开启。dry_run模式下collector完整执行cleaner只打印“将要删除”清单不真正删文件。确认清单没问题之后把dry_run改成false跑一遍再检查一次实际结果整个过程都是可回滚的。这套逻辑说白了就是把“手抖重跑”从“事故”变成“无害操作”因为每次删除都有记录重复执行时能通过历史库判断这个文件是不是已经处理过了已经处理过的就直接跳过。3. 三个直接可抄的代码模块扫描、清理、告警3.1 模块一目录占用扫描器真正扫描的时候用os.scandir比os.walk和pathlib.rglob要更稳因为rglob会先构建整个目录树遇到海量小文件时内存飙升os.scandir是边遍历边统计而且可以follow_symlinksFalse安全跳过软链接。我第一版用的是rglob在单目录十万个文件的情况下内存占用涨了快一个GB后来改成os.scandir才降下来。# collector.py 目录占用扫描核心简化版 import os def scan_dir_size(root: str, max_depth: int 5) - dict: 递归统计目录占用超过max_depth不再下探。 result {path: root, size: 0, child: []} try: with os.scandir(root) as it: for entry in it: if entry.is_symlink(): continue if entry.is_file(follow_symlinksFalse): try: result[size] entry.stat(follow_symlinksFalse).st_size except OSError: continue elif entry.is_dir(follow_symlinksFalse): if max_depth 0: sub scan_dir_size(entry.path, max_depth - 1) result[size] sub[size] result[child].append(sub) except PermissionError: pass return result两点说明一是max_depth必须有限制否则即使跳过软链接遇到嵌套很深的目录也会白白消耗大量时间二是PermissionError要吞掉并继续很多系统目录对普通用户就是只读的工具没必要因为扫不到某个目录就整体失败。扫描结果里的size单位是字节后面报表里统一转成GB或MB展示。3.2 模块二带安全护栏的清理器清理器的核心不是“能删文件”而是“知道哪些能删哪些不能删”。我把它拆成三层检查# cleaner.py 清理动作的安全检查链路核心简化版 from pathlib import Path def safe_delete(path: Path, allowed_roots: set) - bool: # 第一道护栏软链接直接拒绝 if path.is_symlink(): return False # 第二道护栏目录必须落在允许清理的根路径之下 try: abs_path path.resolve() except OSError: return False if not any(abs_path.is_relative_to(Path(root)) for root in allowed_roots): return False return True这里allowed_roots来自配置里clean.enabled的目录本质上是一张白名单。任何不在白名单内的路径即使因为配置写错了被传给清理器也会被挡下来。另外还有一个容易被忽略的细节resolve()之后的路径是绝对路径配置里的路径最好也统一转成绝对路径再比较不然“相对路径能不能删”这种问题会让你debug到怀疑人生。清理策略部分我同时支持“保留天数”和“目录大小上限”。当天数条件命中但目录总大小仍然很大时按文件mtime从旧到新继续删直到目录大小降到目标值以下。这条逻辑用一句话概括先保证数据不过期再保证磁盘不爆满。实际执行时我会先按mtime排序取最旧的一批文件模拟删除看会释放多少空间如果不够再扩大范围避免一次性删太多影响业务侧的数据追溯需求。3.3 模块三报表生成与告警触发报表我直接生成Markdown格式的表格因为运维群普遍支持Markdown渲染贴进去就能看# report.py 报表生成核心逻辑示意 def render_inventory(data: dict) - str: rows [] rows.append(| 目录 | 占用大小 | 删除文件数 | 释放空间 |) rows.append(| --- | --- | --- | --- |) for item in data: rows.append(f| {item[path]} | {item[size]} | {item[deleted]} | {item[released]} |) return \n.join(rows)告警触发条件是全局磁盘使用率超过阈值或者某一个被标记为critical的目录剩余空间不足。通知走Webhook发送函数带超时和重试我在使用中给Webhook加了5秒超时避免notifier线程卡死影响主流程。这里有个经验之谈告警文案一定要带上这台机器的主机名和具体目录路径否则收到告警的人还要去查“是哪台机器在报警”这一步非常影响响应速度。4. 上线前的应激测试与三个坑的完整排查链路4.1 坑一软链接目录差点清空根分区第一次在预发布环境做演练时我把/var/log挂进扫描列表然后发现扫描结果里出现了一个异常大的目录/var/log/oldlogs。我第一反应是“业务还留了这么一大坨日志”正准备把清理策略加上去结果同事提醒我看看那是不是软链接。一查果然是/var/log/oldlogs - /。也就是说扫描器如果没跳过软链接会把整个根文件系统的内容都算进/var/log/oldlogs的占用里如果当时我把清理策略误加到这条路径上后果就是cleaner认为根目录下所有文件都“过期”了整个删下去运维事故直接上演。这就是为什么我说一定要用独立的环境先跑演练这种级别的错误在预发布环境暴露出来是幸运暴露在生产环境就是事故。排查链路其实不算复杂但暴露了一个设计缺口我在collector里跳过了软链接但在cleaner的第一版里没有对软链接做防御。也就是说即使collector不统计软链接目录如果有人在配置里手动加了一条指向软链接的路径cleaner照样会傻乎乎地执行删除。修复就是在safe_delete里加第一道护栏path.is_symlink()直接拒绝任何情况下都不允许删除软链接本身也不允许跟随软链接去删目标。4.2 坑二清理任务互相打架引发的文件竞争上线一段时间后我注意到一个奇怪现象偶尔会有几条告警说“清理任务异常退出”但看日志却找不到明显的报错。后来我把cron的执行时间拉长来看发现是任务运行时超过了预期下一个周期的任务又启动了两个进程同时扫同一个目录同时去删同一批文件结果一个进程删除成功后另一个进程在stat文件时拿到了None直接抛了异常。这个坑的本质是任务没有防重入。修复方式非常传统但非常有效文件锁。我在启动时用fcntl.flock拿一个排他锁如果锁拿不到说明已经有一个tuowei2在跑直接退出并输出“previous instance still running”。# lock.py 单实例锁Linux环境 import fcntl class SingleInstanceLock: def __init__(self, lock_path): self.lock_file open(lock_path, w) try: fcntl.flock(self.lock_file, fcntl.LOCK_EX | fcntl.LOCK_NB) self.acquired True except OSError: self.acquired False def release(self): if self.acquired: fcntl.flock(self.lock_file, fcntl.LOCK_UN) self.lock_file.close()从此之后cron纵使配置成每5分钟跑一次也不会出现两个实例互相踩踏的情况。这个坑也让我意识到任何定时任务只要执行时间不稳定就必须假设它会和下一个实例重叠防重入不是可选项是必选项。4.3 坑三报表时间凭空少了8小时有段时间群里收到的报表完成时间总是显示的凌晨可cron明明配的上午9点跑。第一反应是cron时区变了查了一圈发现系统时区根本没问题。后来才想起Python的datetime.now()返回的是系统本地时间而系统本地时间是UTC报表渲染又没做时区转换所以显示的是UTC时间反映过来就是比预期少了8小时。修复方式不复杂但能体现工具的成熟度配置里加了一个timezone字段所有时间字符串渲染和日志记录统一走zoneinfo不用默认的本地时区。并且在报表末尾附带一行“时区Asia/Shanghai”杜绝以后再出现类似误判。如果你也在这类工具里格式化时间我建议直接把时间统一成带时区的ISO格式比如2025-05-21T09:30:0008:00这样无论谁看到都不会产生歧义。4.4 止血与自检清单踩完这三个坑我把“上线前自检清单”固化到了项目README里dry_run模式必须开启至少完整跑三天演练看清理清单是否符合预期。把所有配置路径过一遍safe_delete白名单确认没有软链接目录进入可删除集合。人工触发两次并发实例确认单实例锁生效。检查报表中的时间字样是否带时区说明。在测试环境故意放一个超大文件验证大小阈值清理确实能把目录压到目标水位。这条清单后来成了我部署到其他机器的标准操作流程。有了它新环境的上线时间从半天压缩到半小时。为了更直观我把三个核心问题的排查结果整理成了下表坑根因修复软链接目录误入清理范围cleaner缺少软链接防御safe_delete首道护栏is_symlink拒绝并发实例互相踩踏缺少单实例锁fcntl.flock排他锁报表时间偏差8小时使用默认UTC本地时间配置timezone字段统一渲染5. 运行半年后的效果复盘与下一步改造方向5.1 半年来的实际运行数据我给tuowei2做了简单的统计部署覆盖了6台服务器平均每天清理掉大约20GB的过期日志磁盘使用率从长期90%以上回落到60%-70%波动。最直观的变化是磁盘告警从以前每周至少一次变成了半年几乎没有误报级别的告警再也不用半夜爬起来处理“磁盘满了”这种问题。人工介入次数这个指标更能说明问题v1时代差不多每个月都要登服务器看一次日志确认脚本有没有异常tuowei2上线后我只需要每周看一眼群里的报表确认数值在合理区间内。有一次业务方做活动日志量翻了3倍tuowei2自动把清理量也翻了3倍磁盘水位稳定在75%以下全程没有人工干预。对我来说这就是一个自动化工具该有的状态——平时感觉不到它的存在但它在默默兜底。5.2 哪些设计经受住了考验回看这半年有三件事被证明是对的。第一是白名单护栏。即便有一次我在新服务器上配置路径时手滑写错了根目录safe_delete依然把所有删除请求挡下了只报了“路径不在白名单”的警告没有造成任何损失。那一刻我非常庆幸自己把护栏放在cleaner的最前面而不是依赖外部调用方的自觉。第二是dry_run机制。它不只是第一次上线的保险后来每次调整保留天数或新增扫描路径我都会先开着dry_run跑一天看清单和预期一致再切正式模式。这个习惯帮我避开了至少三次配置错误其中一次是把保留天数从30改成3dry_run跑出来的清单显示会一次性删掉半个月的日志我赶紧把配置改了回去。第三是SQLite历史记录。有一次同事问“上周清理了多少文件”我直接查库给出一份精确清单他当时还挺意外。操作的可追溯性在多人协作环境里比其他所有特性都值钱。工具可以出错但不能让人查不到是哪里出的错。5.3 下一步从清理工具走向容量预测tuowei2目前的定位还是一个“事后处理”工具——等到磁盘快满了再去清。但日志增长是有规律可循的我接下来想给collector加一个简单的时间序列分析记录每个目录每天的增量用滑动平均预测未来N天的占用当预测值超过阈值时提前告警把“等它满了再清”变成“提前规划容量”。另外一个是清理策略的细化现在的双条件天数大小对大多数场景够用但有些业务文件要求按版本保留最新几个有些要求按月份保留这需要引入更灵活的文件保留模式。我计划在配置里给cleaner增加一个rule字段按glob模式做更细粒度的匹配。比如data/backup/*.tar.gz这条规则可以配置成“保留最近3个版本”而不是单纯按天数切。刚才提到的SQLite历史记录也可以顺势扩展成趋势分析的底表这样每个目录的占用变化就变成可查询的历史序列了。这些改造不一定都落地但tuowei2这个项目让我深刻意识到一件事很多运维问题不是靠一个绝妙的脚本解决的而是靠一次次踩坑、一版版迭代把防御性的逻辑一层层加进去才变稳的。我现在写完这类工具的代码第一件事永远不是测业务逻辑通不通而是先想“它出错的时候会怎样”——出错时是否安全、是否可控、是否能被快速定位。工具真正成熟的标准不是功能多而是出错时它的反应依然可控。