Linux inotify 监听目录时怎么处理队列溢出

我们写文件夹监听程序的时候，最需要留意的坑不是收到未知类型的事件，而是事件队列被塞满之后，悄无声息丢掉一部分变动记录。Linux inotify 发现队列溢出时会返回 IN_Q_OVERFLOW，这个事件的 wd 为 -1，表示后续缓存不能再靠增量事件修正。

正确处理方式是：把 IN_Q_OVERFLOW 当成“当前状态已失去连续性”，暂停应用增量事件，重新扫描被监听目录并重建缓存；必要时关闭旧文件描述符、重新创建 inotify 实例和 watches，再以全量扫描结果作为新的基线。单纯调大 max_queued_events 只能降低复发概率，不能找回已经丢失的事件。

先判断 IN_Q_OVERFLOW 到底意味着什么

inotify 把事件放在每个实例对应的内核队列里。读取到 IN_Q_OVERFLOW 时，超出队列容量的事件已经被丢弃，内核不会补发一份“丢了哪些文件”的列表。因此，程序不能把这一条记录当作某个文件的修改通知，也不能只重新读取最后一个路径。

static int overflow_seen = 0;

// 只展示事件分流；真实程序还需要处理缓冲区边界和 errno。
static void handle_event(const struct inotify_event *event)
{
    if ((event->mask & IN_Q_OVERFLOW) != 0) {
        // wd 为 -1，不能从 name 推断具体丢失对象。
        overflow_seen = 1;
        mark_cache_stale();
        return;
    }

    if (!overflow_seen) {
        // 没有断档时，才把普通创建、删除、修改事件应用到缓存。
        apply_incremental_change(event);
    }
}

生产代码通常把 overflow_seen 放进监听器状态机：一旦置为真，后续普通事件先进入丢弃或暂存策略，直到重扫成功。这样做看起来保守，却能避免“旧缓存加上一小段新事件”形成一个没有人察觉的错误索引。

先分清队列容量和 watch 数量

下面三个参数经常被一起修改，但它们限制的对象并不一样。max_queued_events 在创建 inotify 实例时决定该实例的事件队列上限；max_user_watches 限制一个真实用户能创建的 watch 数；max_user_instances 限制该用户能创建的 inotify 实例数。

# 查看当前内核为新 inotify 实例准备的事件队列上限
cat /proc/sys/fs/inotify/max_queued_events

# 区分 watch 配额和实例配额，不要只盯着队列参数
cat /proc/sys/fs/inotify/max_user_watches
cat /proc/sys/fs/inotify/max_user_instances

调大队列是容量缓冲，不是可靠性方案。监听目录里如果持续产生临时文件、编辑器交换文件或构建产物，应该先减少不必要的事件类型、缩小监听范围，并确保读取线程不会被慢日志、网络请求或昂贵的业务处理阻塞。

溢出后的恢复流程：重扫、重建、再接收

恢复的核心是建立一个新的可信快照。先让业务层看到“正在重建”，暂停依赖目录缓存的动作；然后对根目录做全量扫描，把文件路径、类型和需要的元数据写入临时缓存，成功后再一次性替换旧缓存。扫描失败时保留旧缓存但标记为过期，不能假装已经恢复。

如果监听树很大，推荐把重建拆成明确的两个边界：监听器负责生产事件，重同步器负责扫描和替换快照。对新建或移入的子目录，先添加 watch，再扫描该目录内容；因为在创建 watch 之前，目录里可能已经出现文件。

// 伪代码：重同步成功后才恢复增量消费。
int recover_watch_tree(int old_fd, const char *root)
{
    // 先阻止业务读取不完整的缓存，避免把半成品当作事实。
    set_cache_state(CACHE_REBUILDING);

    cache_t *fresh = scan_tree(root); // 全量扫描，失败返回 NULL。
    if (fresh == NULL) {
        set_cache_state(CACHE_STALE);
        return -1;
    }

    int new_fd = inotify_init1(IN_NONBLOCK);
    if (new_fd == -1 || add_watches_recursively(new_fd, root) != 0) {
        // 新监听未准备好时，保留旧状态并让上层继续报警。
        destroy_cache(fresh);
        set_cache_state(CACHE_STALE);
        return -1;
    }

    replace_cache(fresh); // 快照和 watches 都成功后才切换基线。
    close(old_fd);
    set_cache_state(CACHE_LIVE);
    return new_fd;
}

是否每次都关闭旧 fd 要看实现：简单监听器可以直接重建，复杂系统也可以保留 fd 并重新加入 watches。关键不在某个固定 API 顺序，而在于不能让“重扫期间产生的变化”被误认为已经完整处理；必要时要在切换后再做一次短校验扫描。

如何验证恢复真的完成

至少记录四个指标：溢出次数、从发现到恢复的耗时、全量扫描失败次数，以及恢复后的一致性检查结果。用一个可重复的测试目录制造高频创建和删除，观察监听器是否进入重建状态、缓存是否回到 CACHE_LIVE，而不是只看进程有没有退出。

如果溢出频繁出现，先从消费路径排查：读取线程只做解码和入队，把慢操作交给工作线程；减少 IN_OPEN、IN_ACCESS 等非必要事件；对临时目录设置更窄的监听范围。对于网络文件系统，inotify 本身不能覆盖远端变化，应准备轮询或其他同步机制。

相关问题

把 max_queued_events 调大就不会丢事件了吗？

不会。它只能提高单个新实例的队列上限，无法消除消费线程停顿、事件风暴或已经发生的丢失。恢复逻辑仍必须存在。

收到 IN_Q_OVERFLOW 后能不能只扫描最近改动的文件？

不能可靠判断“最近改动”集合，因为溢出事件本身不携带丢失清单。除非业务另有独立的版本号或日志，否则应按可接受成本做目录或子树全量重扫。

为什么 watch 数量够用，仍然会队列溢出？

watch 配额限制的是被监听对象数量，队列溢出关注的是事件积压。一个 watch 目录也可能在短时间产生大量创建、删除和修改事件。

把 IN_Q_OVERFLOW 设计成一次“重新建立事实”的信号，监听程序才不会把偶发高峰变成长期错误缓存：先停增量、再做全量基线，最后恢复消费并持续观测。