一个旁路式文件变更审计系统的设计与落地
文章目录
摘要:本文记录 FileGuard 从想法到落地的全过程。我们需要追踪生产服务器上的文件变更,但又面临三个硬约束:不想改研发流程(引入 Git/SVN 管控需要研发配合 commit)、不想侵入非自维护服务器(装个 agent 可以,但搞复杂同步机制不行)、生产服务器不能联网。FileGuard 就是在这些约束下催生的旁路式变更审计方案。文章重点展开 collector 侧的多 worker 线程池 + 无界内存队列架构——它是解决"文件操作过多时 watchdog 缓冲区溢出、事件丢失"的核心设计——并条列了网关、Agent 侧的设计决策和踩坑。
一、为什么要造这个轮子
先讲清楚为什么不用已有的方案:
| 方案 | 为什么不行 |
|---|---|
| Git / SVN 管控 | 最好的方案,但需要研发配合 commit、需要在服务器端做代码同步。生产服务器不是我们自己维护的,没法要求研发去改工作流 |
| inotifywait / auditd | Linux 生态的成熟方案,但我们线上是 Windows Server,套不上 |
| 商业审计产品 | 贵,且客户端装在不能联网的生产机上也没法上报 |
| 写个 watchdog 脚本 | 调 watchdog.observer,每个事件打日志——听起来简单,实际上就是这个"简单"的想法后来踩了一堆坑 |
所以 FileGuard 的定位从第一天就很明确:旁路式、低侵入、零改造研发流程。它的能力边界也是天生限定的:
- ✅ 能记录:哪个服务器上、哪个路径、发生了什么变更
- ❌ 不能记录:谁在操作(没有 Windows 审计 API hook)
- ❌ 没有 commit 信息(不是 Git)
- ❌ AI 只能看表象总结,推不出操作背后的真实意图(“删了 RackAgent"到底是正常清理还是被入侵了?AI 只能猜)
这些局限是架构约束,不是技术 bug。写在这里是给读者一个诚实的预期。
二、整体架构
|
|
三段式分工:collector 只管采集和上传、gateway 只管入库聚合和推送、agent 只管查询和 AI 总结。关键约束生产服务器不能联网决定了 AI 能力全部落在本地 Agent 侧——网关是纯规则引擎,不调 LLM。
三、Collector 核心设计:让 watchdog 不再丢事件
这是整个系统最有价值的部分。先讲问题,再讲解法。
问题:watchdog 在 Windows 上的缓冲区溢出
watchdog 底层用的是 Windows ReadDirectoryChangesW。这个 API 有一个固定大小的内核缓冲区(默认 8KB),短时间内大量文件操作(git checkout、解压、批量 cp)会把缓冲区灌满,新事件直接被内核丢弃——watchdog 的 handler 根本收不到。
更糟糕的是,watchdog 的 handler 是在 watchdog 自己的内部线程里执行的。如果 handler 里做了任何重操作(读文件、算哈希、写磁盘),就会阻塞 watchdog 线程,让内核缓冲区更快溢出。
解法:生产者-消费者 + 多 worker 线程池
核心思想一句话:watchdog 回调里只做一件事——往内存队列里 put。所有重操作扔给后面的 worker 线程池异步处理。
|
|
具体实现(collector.py 第 484-503 行):
|
|
这条流水线的每一个环节都有明确的职责:
| 环节 | 做什么 | 为什么这样设计 |
|---|---|---|
| watchdog 回调线程 | 只往 raw_queue put 事件 |
任何重操作都会阻塞它,导致内核缓冲区溢出 |
raw_queue(内存无界队列) |
解耦 watchdog 和 worker | watchdog 只负责生产,worker 负责消费,生产速率 > 消费速率时积压在内存里——反正内存足够 |
| N 个 worker 线程 | 取事件、算哈希、算 diff、写 SQLite | 并行处理不同路径的事件;同一路径用 per-path 锁串行保证顺序正确 |
| SQLite 上传队列(持久化) | worker 写入、uploader 读取 | 断网时事件积压在本地,恢复后批量补发,不丢数据 |
| uploader 线程 | 定时批量上传 + 指数退避重试 | 减少 HTTP 往返;失败时 10s→20s→40s→最多 10min 退避 |
| full_scan 线程 | 每 5 分钟全量对账 | 兜底——哪怕前三层都漏了事件,定时扫描监控目录和上一次快照 diff,把遗漏的事件重新推入 raw_queue |
为什么不把所有逻辑塞进一个线程?
一开始我也想过让 watchdog handler 直接做所有事——简单,省内存,省线程。结果真实跑了一次:解压一个 5000 文件的 zip,丢了 3000+ 事件。原因就是 handler 里算哈希、写 SQLite 的时候阻塞了 watchdog,内核缓冲区爆了。
改成现在的流水线后,同样的测试零丢失。watchdog 回调的 put 是微秒级,内核缓冲区在它之前根本没机会被填满。
额外加成:调大 Windows 通知缓冲区
collector 启动时还做了一个操作:
|
|
双重保险——哪怕流水线设计没问题,内核缓冲区本身也提了 8 倍上限。
四、我做的几个关键决策
决策 1:watchdog 回调里绝不做重操作
这是最核心的设计,其他都是它的衍生。原则就一条:任何可能超过 1ms 的操作都不能放在 watchdog handler 里。读文件、算哈希、写磁盘——全扔给 worker 异步处理。
决策 2:用 SQLite 做持久化缓冲,不用文件
一开始想过用本地文件存队列,后来选了 SQLite。原因有三:
- SQLite 单文件、零配置,生产服务器不需要额外装数据库服务。
- 有事务语义——worker 写入成功才 commit,失败回滚,避免半写状态。
queue.push() / queue.pop_batch() / queue.ack()这三个方法天然对应 SQLite 的 insert / select+delete,实现简单。
决策 3:全量对账做兜底
任何依赖内核事件的机制都可能漏——这是我从那次 5000 文件解压测试里学到的。所以加了一个 full_scan 线程,每 5 分钟扫描一次监控目录的文件清单,和上一次快照 diff,把遗漏的事件重新推入 raw_queue。慢,但可靠。
决策 4:per-path 锁保证同一路径事件顺序
worker 是多线程并行的,但同一路径的事件必须串行处理——不然 “先 A 后 B” 变成 “先 B 后 A”,diff 就反了。做法:
|
|
决策 5:AI 能力全部落在 Agent 侧,网关只做规则
生产服务器不能联网 → 网关跑不了 LLM → AI 能力只能在本地 Agent 上实现。这带来一个架构分工:
|
|
规则做确定性判断,AI 只做规则做不了的语义理解。这个分工不会把规则算出的正确结论推翻——LLM 总结的风险等级只是覆盖,不修改基线逻辑;下次 rules 重新聚合还是按基线来。
决策 6:「空目录 / 只含 log 目录」对称过滤
一堆 “创建 LogDir” 的事件淹没了真正重要的变更,所以 collector 在 dir_created 事件里加了过滤逻辑:等 500ms 让子文件事件落盘,os.walk 扫描目录,如果所有文件都被 ignore patterns 过滤(*.log、*.tmp、.git/*)就跳过不上报,同时把这个目录记进 _ignored_dirs 集合。删除时查这个集合——命中就跳过。创建和删除完全对称。
五、其他值得记录的踩坑(简化条列)
这些不是我上面重点讲的架构设计,但落地过程中踩到了,记下来省得下次再踩:
- watchdog 的
on_deleted不给is_directory——删除目录树时只发子文件 deleted,完全不给父目录 deleted 事件。解法:不在 collector 侧挣扎,网关聚合器兜底——从所有 deleted 路径取 dirname,找被覆盖次数最多的公共父目录,推断为dir_deleted。 - Blob 重复上报冲突——collector 重启时同一个文件内容(哈希相同)被重新上报,
UNIQUE constraint failed: blobs.sha256。解法:先 add + flush,失败则 delete 再 add。 - Agent
api()参数乱传——**kwargs把业务参数和 requests 库内部参数混了。解法:GET 显式params={},POST 显式json=json_body,不再用**kwargs。 - 目录事件命名统一——watchdog 原生只有 created/modified/deleted/moved,目录级事件走自定义
dir_created/dir_deleted,下游直接按 event_type 分流。 - 事件去重用
(server_id, path, event_type, 秒级时间桶)——collector 重启时 watchdog 会重复上报同一秒内的事件。
六、运维侧:让 collector 像真正的服务一样活着
生产服务器不能有人常驻操作,collector 必须开机自启、崩溃自恢复。NSSM 注册成 Windows 服务:
|
|
两个必须记的运维细节:
AppDirectory必须设成 collector 目录本身(不是 FileGuard 根目录),否则config.yaml和 SQLite 队列文件找不到。- NSSM 服务以 SYSTEM 身份运行时读不到用户环境变量——不要指望 API_TOKEN 从环境变量来,所有配置都写在
config.yaml里。
七、现状与局限
| 能做到 | 做不到 |
|---|---|
| 哪个服务器、哪个路径、什么变更 | 谁在操作(无 Windows 审计 hook) |
| 文件 diff、版本还原 | commit 历史和版本语义 |
| 规则层风险分层 + 批量 LLM 总结 | 操作背后的真实意图 |
| 实时推送告警 | 主动阻断高风险变更 |
| 断网事件积压、恢复后补发 | 网关端离线(SQLite 够用但不是集群级 HA) |
全部 AI 能力目前只有 summarize-pending(每日批量总结未总结变更集)。值得继续做的:AI 日报、跨变更集叙事合并、自然语言查询、异常变更识别——但都只能跑在 Agent 侧,网关还是纯规则。
八、结语
回到文章开头的那个选择:为什么不引入 Git/SVN?答案其实很简单——在不是自己维护的服务器上,介入越少越好。
FileGuard 就是在"少介入"这个前提下能做到的最好结果。它不完美——不知道谁在操作,不知道为什么操作,AI 总结也只能看表象。但它做到了三件事:
- 不丢事件——多 worker + 无界队列 + SQLite 持久化 + 全量对账兜底。
- 不改研发流程——旁路监听,零侵入。
- 生产机离线也能工作——断网时事件积压,恢复后自动批量补发。
这三点,就是 FileGuard 的全部价值。
✅ 已在 3 台生产服务器稳定运行 2 个月,未再出现事件丢失。
文章作者
上次更新 2026-11-19