Linux inotify 监听数量不足时如何确认限制

开发工具、文件同步服务或构建系统递归监听目录时，常见现象是“监听数量不足”。这个提示不一定代表 max_user_watches 真到顶：Linux inotify 还分别限制同一真实用户能创建的实例数量，以及每个实例能积压的事件数量。

先读出三个 fs.inotify 参数，再用目标进程的 /proc/PID/fdinfo 对照实际 watch。只有确认是 watch 配额不足才调大 max_user_watches；如果出现 IN_Q_OVERFLOW，要修复事件消费和全量重建策略。

先把三个限制拆开再查

一个 inotify 实例由 inotify_init() 或 inotify_init1() 创建，并拥有自己的事件队列；应用调用 inotify_add_watch() 后，才会在实例里增加具体 watch。递归监听目录树时，子目录通常也要分别建立 watch，所以目录数量增长会很快触及用户级 watch 上限。

这三个值都位于 /proc/sys/fs/inotify/。它们是按真实用户计算的，因此同一账号下的编辑器、同步服务和测试进程会共同消耗前两类配额。

先读取生效值，再判断是哪一条边界

排查时先把三个参数放在同一份记录里，避免只看到一个熟悉的 watch 配置：

# 一次读取 inotify 的三类内核限制，保存修改前基线
sysctl fs.inotify.max_user_watches \
       fs.inotify.max_user_instances \
       fs.inotify.max_queued_events

# 也可以直接读取 procfs，确认当前命名空间中可见的值
cat /proc/sys/fs/inotify/max_user_watches
cat /proc/sys/fs/inotify/max_user_instances
cat /proc/sys/fs/inotify/max_queued_events

如果报错发生在创建 watch 的位置，优先看第一项；如果应用连新的 inotify 文件描述符都创建不了，查看第二项。第三项不是“能监听多少目录”，而是事件来得太快时，单个实例能暂存多少事件。

用 fdinfo 找到进程正在占用的 watch

只比较上限还不够。inotify(7) 说明，进程的 /proc/PID/fdinfo 中，inotify 文件描述符会列出 inotify wd: 条目；可以用它估算一个进程当前持有的 watch 数：

pid=1234
# 统计目标进程每个 fd 中的 inotify watch 条目
for info in /proc/"$pid"/fdinfo/*; do
  # 没有 inotify wd 的 fd 不是监听实例，跳过它
  count=$(awk '/^inotify wd:/{n++} END{print n+0}' "$info")
  if [ "$count" -gt 0 ]; then
    printf '%s: %s watches\n' "$info" "$count"
  fi
done

这个统计只回答“某一个进程持有多少”，不能直接代表真实用户的总量。若多个服务用同一个 UID 运行，还要逐个查看它们的监听实例；反过来，清理已经退出进程的实例后，相关资源会随文件描述符关闭而释放。

按问题类型调整，别把队列溢出当成配额不足

确认确实需要增加 watch 后，可以先临时修改，观察应用能否正常建立监听，再决定是否持久化。下面的数值只是配置示例，应结合主机内存、目录规模和同 UID 服务数量评估：

# 先只调整 watch 上限；实例和队列问题不要用这一项代替
sudo sysctl -w fs.inotify.max_user_watches=524288

# 确认应用恢复后，再写入独立配置文件便于审计和回退
printf 'fs.inotify.max_user_watches = 524288\n' \
  | sudo tee /etc/sysctl.d/99-inotify.conf

# 重新加载 sysctl.d 中的配置，并复读最终生效值
sudo sysctl --system
sysctl fs.inotify.max_user_watches

如果是实例数不够，应单独评估 max_user_instances；如果应用报告 IN_Q_OVERFLOW，说明事件超过了对应实例的队列能力，简单增大 watch 没有帮助。max_queued_events 的值会在调用 inotify_init() 创建实例时用于设置队列上限，因此修改后通常要让应用重新创建实例。更重要的是，应用必须能识别溢出并重新扫描或重建缓存，因为已经丢失的事件无法从队列中找回来。

常见问题

把 max_user_watches 调得很大，为什么仍然报错？

可能触及的是 max_user_instances，也可能是事件队列溢出。先看报错发生在创建实例、添加 watch 还是读取事件的阶段。

fdinfo 里的 wd 数量能代表整台机器的使用量吗？

不能。它是单个进程、单个 inotify 文件描述符的观察值；同一真实用户下的其他进程也会消耗用户级 watch 和实例额度。

提高队列上限后，丢失的文件事件会回来吗？

不会。队列溢出意味着事件已经丢失，程序仍需重新扫描受监控目录或重建缓存，才能恢复一致状态。

最后复查三项 sysctl、目标进程的 fdinfo 和应用日志，把变更前后的数值写入运维记录。若 watch 数持续增长，优先排查递归目录范围过大、重复注册和退出路径未清理，而不是无限提高上限。