Linux inotify 监控目录时怎么处理事件合并和重复通知

Linux inotify 适合发现“目录里发生了变化”，但它不是业务变更计数器。同一个文件连续写入时，内核可能合并尚未读取的相同事件；应用层又可能同时收到 IN_MODIFY、IN_CLOSE_WRITE 等不同事件。所以正确做法是把通知当作“需要重新判断”的信号：用路径和事件类型做短时间去重，处理完成后再以文件当前状态为准；一旦收到 IN_Q_OVERFLOW，立即做全量补扫，而不是继续相信手上的增量列表。

要处理事件合并和重复通知，核心思路是把收到的原始事件先放入带过期窗口的暂存队列，过滤掉短时间内重复的路径操作，等待连续操作停止一小段时间后再统一批量分发处理即可。

为什么一个文件会带来多条看似重复的通知

inotify 事件包含 wd、mask、cookie 和可选的 name。编辑器保存一个文件时，可能先写临时文件，再重命名；普通写入也可能经历修改和关闭写入。它们在文件系统层面是不同事实，不能只按文件名粗暴丢弃。

另外，man7 的 inotify 说明指出：如果连续事件的 watch 描述符、掩码、cookie 和名称都相同，且旧事件尚未读出，内核可以把它们合并成一条。因此“读到一条”不等于只发生了一次，“读到多条”也不等于业务上要执行多次。上传索引、刷新缩略图这类动作应该设计成幂等任务。

先给一个按语义去重的最小配方

不要把所有 mask 拼成一个字符串后比较，而是先决定业务真正关心的事件。例如内容处理通常优先使用 IN_CLOSE_WRITE，原子替换场景再补上 IN_MOVED_TO；IN_MODIFY 可以只作为“延后检查”的提示。

import time

# 记录短时间内已经安排过的文件任务
recent = {}

def should_enqueue(directory, name, mask):
    # 只保留会让内容可读取的业务事件
    semantic = mask & (IN_CLOSE_WRITE | IN_MOVED_TO)
    if not semantic:
        return False

    key = (directory, name, semantic)
    now = time.monotonic()
    # 300 毫秒只是示例，应按写入端节奏调整
    if now - recent.get(key, 0) 

这个配方有两个重点：去重键必须包含事件语义，避免把“移动到目录”和“写入关闭”误合并；队列消费者不能依赖事件里当时的文件内容，因为事件被处理时，文件可能已经再次改名或删除。实际项目还应给 recent 设置过期清理，避免目录长期运行造成内存增长。

收到 IN_Q_OVERFLOW 时为什么必须补扫

/proc/sys/fs/inotify/max_queued_events 限制每个 inotify 实例的队列长度。超过限制后，内核会丢弃超出的事件，并生成一个 IN_Q_OVERFLOW 事件（其 wd 为 -1）。这时你无法从剩余通知推导出完整变更集合。

# 查看当前实例允许排队的事件上限
cat /proc/sys/fs/inotify/max_queued_events

# 只做临时调优，持久化应交给系统配置管理
sudo sysctl -w fs.inotify.max_queued_events=32768

稳妥的恢复策略是：停止继续消费这批增量结果，标记缓存为“待重建”，重新遍历被监控目录，把当前磁盘状态写回缓存，再继续读取新事件。提高上限只能降低概率，不能把溢出变成绝对不会发生；重建逻辑才是正确性保障。

目录监听不是递归：新目录要补扫再加入 watch

inotify 监听目录本身不会自动覆盖所有子目录。常见做法是遍历初始树，为每个目录建立 watch；收到 IN_CREATE | IN_ISDIR 或目录移动进入监控树时，先为新目录建立 watch，再立即扫描它的现有内容。

这里存在一个窗口：新目录创建后，应用真正执行 inotify_add_watch 之前，里面可能已经出现文件。只加 watch 不补扫会漏数据，只补扫不加 watch 又会漏掉后续变化。对新目录采用“加 watch + 立刻扫描”，并把扫描结果按幂等键写入任务队列，才能覆盖这段竞态。

常见问题

能不能只监听 IN_MODIFY？

不建议把它当成文件可读信号。写入尚未结束时就处理，容易读到半成品；内容处理通常应以 IN_CLOSE_WRITE 或原子替换后的 IN_MOVED_TO 为入口。

提高 max_queued_events 后还需要去重吗？

需要。队列上限只影响溢出风险，不改变不同生命周期事件并存、应用重复入队或同一任务重复执行的问题。

收到 IN_Q_OVERFLOW 后只重读一次可以吗？

不够。应把缓存标记为不可信并执行覆盖目标目录的全量扫描；扫描结束前还要考虑继续到达的新事件，必要时在恢复完成后再做一次收敛扫描。