摘要:本文记录 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。写在这里是给读者一个诚实的预期。

二、整体架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[生产服务器,不能联网]                 [汇聚服务器,有公网]                [本地电脑]
┌─────────────────────────┐        ┌─────────────────────────┐        ┌─────────────────────────┐
│  collector(进程常驻)    │   HTTPS│  gateway(FastAPI)       │  WS    │  agent(CLI)            │
│  ┌─────────────────────┐ │ ────▶ │  ┌─────────────────────┐ │ ◀──── │  ┌─────────────────────┐ │
│  │ watchdog 回调线程    │ │       │  │ 事件入库              │ │       │  │ 实时告警订阅          │ │
│  │  ↓ 只入队(微秒级)  │ │       │  │ 变更集聚合             │ │       │  │ 历史查询 / diff       │ │
│  │ raw_queue(无界)    │ │       │  │ Blob 去重存储          │ │       │  │ 版本还原(blob)       │ │
│  │  ↓ N worker 消费    │ │       │  │ 规则层风险分层         │ │       │  │ LLM 每日总结          │ │
│  │ SQLite 上传队列      │ │       │  └─────────────────────┘ │       │  └─────────────────────┘ │
│  │  ↓ 批量上传+指数退避 │ │       │  DB: SQLite / PostgreSQL │       │  LLM: 本地离线调用      │
│  └─────────────────────┘ │       └─────────────────────────┘       └─────────────────────────┘
└─────────────────────────┘

三段式分工: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 线程池异步处理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
watchdog 回调线程        内存队列 (raw_queue)         N 个 worker 线程(CPU 核数)
      │                       │                           │
      │  queue.put(event)     │                           │
      │  (微秒级,永不阻塞) ├──────────▶  各自独立取事件  │
      │                       │       ├── 计算哈希/diff   │
      ▼                       │       ├── 维护 per-path 快照
    立即返回                   │       └── 写入 SQLite 上传队列
                              │
                              ▼
                         SQLite 上传队列 ──▶ uploader 线程批量上传 ──▶ 网关

具体实现(collector.py 第 484-503 行):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 无界内存队列 —— 防止任何情况下阻塞 watchdog 回调
raw_queue = queue.Queue()           # Python queue.Queue 本身无界,永远不会 put 阻塞

# watchdog handler 只做入队
class ChangeHandler(FileSystemEventHandler):
    def on_created(self, e):
        raw_queue.put({...})        # 微秒级返回,绝不在这读文件算哈希

# worker 池 —— 默认 CPU 核数,最少 2
n_workers = os.cpu_count() or 4
for i in range(n_workers):
    threading.Thread(target=worker_loop, args=(cfg, queue, raw_queue),
                     daemon=True, name=f"fg-worker-{i}").start()

这条流水线的每一个环节都有明确的职责:

环节 做什么 为什么这样设计
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 启动时还做了一个操作:

1
2
from watchdog.observers.api import NativeDispatcher
NativeDispatcher.buffer_size = 65536   # 默认 8192,提到 64KB

双重保险——哪怕流水线设计没问题,内核缓冲区本身也提了 8 倍上限。

四、我做的几个关键决策

决策 1:watchdog 回调里绝不做重操作

这是最核心的设计,其他都是它的衍生。原则就一条:任何可能超过 1ms 的操作都不能放在 watchdog handler 里。读文件、算哈希、写磁盘——全扔给 worker 异步处理。

决策 2:用 SQLite 做持久化缓冲,不用文件

一开始想过用本地文件存队列,后来选了 SQLite。原因有三:

  1. SQLite 单文件、零配置,生产服务器不需要额外装数据库服务。
  2. 有事务语义——worker 写入成功才 commit,失败回滚,避免半写状态。
  3. 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 就反了。做法:

1
2
3
4
5
6
7
8
_path_locks = defaultdict(threading.Lock)

def worker_loop(cfg, queue, raw_queue):
    while True:
        event = raw_queue.get()
        path = event["path"]
        with _path_locks[path]:    # 同路径串行,不同路径并行
            build_event(cfg, queue, path, event["event_type"], event["occurred_at"])

决策 5:AI 能力全部落在 Agent 侧,网关只做规则

生产服务器不能联网 → 网关跑不了 LLM → AI 能力只能在本地 Agent 上实现。这带来一个架构分工:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
网关侧(纯规则,确定性):
├── 事件入库、去重、Blob 存储
├── 变更集聚合(actor + root_dir + 时间窗)
├── 目录删除兜底推断(从子文件反推父目录)
├── 风险等级基线(删除=critical、修改=high、创建=low)

Agent 侧(AI + 查询):
├── 实时告警订阅(WebSocket)
├── 历史查询、diff、版本还原
├── summarize-pending:LLM 每日批量总结未总结变更集
└── (待做)AI 日报、跨变更集叙事合并、自然语言查询

规则做确定性判断,AI 只做规则做不了的语义理解。这个分工不会把规则算出的正确结论推翻——LLM 总结的风险等级只是覆盖,不修改基线逻辑;下次 rules 重新聚合还是按基线来。

决策 6:「空目录 / 只含 log 目录」对称过滤

一堆 “创建 LogDir” 的事件淹没了真正重要的变更,所以 collector 在 dir_created 事件里加了过滤逻辑:等 500ms 让子文件事件落盘,os.walk 扫描目录,如果所有文件都被 ignore patterns 过滤(*.log、*.tmp、.git/*)就跳过不上报,同时把这个目录记进 _ignored_dirs 集合。删除时查这个集合——命中就跳过。创建和删除完全对称。

五、其他值得记录的踩坑(简化条列)

这些不是我上面重点讲的架构设计,但落地过程中踩到了,记下来省得下次再踩:

  1. watchdog 的 on_deleted 不给 is_directory——删除目录树时只发子文件 deleted,完全不给父目录 deleted 事件。解法:不在 collector 侧挣扎,网关聚合器兜底——从所有 deleted 路径取 dirname,找被覆盖次数最多的公共父目录,推断为 dir_deleted。
  2. Blob 重复上报冲突——collector 重启时同一个文件内容(哈希相同)被重新上报,UNIQUE constraint failed: blobs.sha256。解法:先 add + flush,失败则 delete 再 add。
  3. Agent api() 参数乱传——**kwargs 把业务参数和 requests 库内部参数混了。解法:GET 显式 params={},POST 显式 json=json_body,不再用 **kwargs。
  4. 目录事件命名统一——watchdog 原生只有 created/modified/deleted/moved,目录级事件走自定义 dir_created / dir_deleted,下游直接按 event_type 分流。
  5. 事件去重用 (server_id, path, event_type, 秒级时间桶)——collector 重启时 watchdog 会重复上报同一秒内的事件。

六、运维侧:让 collector 像真正的服务一样活着

生产服务器不能有人常驻操作,collector 必须开机自启、崩溃自恢复。NSSM 注册成 Windows 服务:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
nssm install FileGuardCollector "C:\Python310\python.exe"
nssm set FileGuardCollector AppDirectory "C:\apps\FileGuard\collector"
nssm set FileGuardCollector AppParameters "collector.py"
nssm set FileGuardCollector Start SERVICE_AUTO_START

# 日志滚动(服务没控制台,不配就看不到任何日志)
nssm set FileGuardCollector AppStdout  "C:\apps\FileGuard\collector\stdout.log"
nssm set FileGuardCollector AppStderr  "C:\apps\FileGuard\collector\stderr.log"
nssm set FileGuardCollector AppRotateFiles 1
nssm set FileGuardCollector AppRotateBytes 10485760

# 崩溃 5 秒后自动重启
nssm set FileGuardCollector AppExit Default Restart
nssm set FileGuardCollector AppRestartDelay 5000

nssm start FileGuardCollector

两个必须记的运维细节:

  • 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 总结也只能看表象。但它做到了三件事:

  1. 不丢事件——多 worker + 无界队列 + SQLite 持久化 + 全量对账兜底。
  2. 不改研发流程——旁路监听,零侵入。
  3. 生产机离线也能工作——断网时事件积压,恢复后自动批量补发。

这三点,就是 FileGuard 的全部价值。


✅ 已在 3 台生产服务器稳定运行 2 个月,未再出现事件丢失。