Linux inotify 监听目录移动后为什么原 watch 描述符会失效

线上目录从 /srv/inbox 改名为 /srv/inbox-old 后，程序还在打印事件，却不再处理新目录里的文件。这类问题通常不是 inotify “丢了路径”，而是应用把 wd 当成了永久路径身份。wd 只标识当前 inotify 实例里的 watch；目录移动后，路径名、目录树关系和待处理事件可能已经变化，原来的 wd 到路径缓存需要更新甚至重建。

目录移动后先判断事件对应的对象

排查时先把每条事件的 wd、mask、cookie 和 name 原样记录下来。最容易混淆的是“被监听目录自身移动”和“目录里的某个条目移动”：前者关注目录对象本身，后者关注父目录里的名字变化。

如果只是把子目录从 待处理 移到 归档，父目录上的两个移动事件可能带相同 cookie；如果整个被监听目录被改名，则要关注 IN_MOVE_SELF。事件到达应用时，文件名可能已经再次改变，所以事件里的名字更适合触发重扫，不适合被当成永远正确的当前路径。

根因：watch 描述符不是路径，也不是业务对象 ID

inotify_add_watch 返回的 watch descriptor 只在对应的 inotify 实例中有意义。应用可以维护 wd -> path 表，但这张表是缓存，不是内核为你持续维护的真实路径索引。目录改名后，如果代码仍把 wd=17 解释成旧路径，就会出现两种假象：事件看似“来自旧目录”，或者新目录已经收到事件，但业务层查不到对应对象。

目录监听还不是递归监听。新目录被移入目录树后，即便收到了 IN_MOVED_TO，也要对它当前内容做一次扫描，并为内部子目录补充 watch。这个扫描不是多余的：创建 watch 前，子目录里可能已经出现新文件。

/* 事件处理只更新状态，不把 wd 当成永久路径身份。 */
static void handle_event(const struct inotify_event *ev) {
    /* watch 被移除后，先删除旧映射，避免 wd 被误用。 */
    if (ev->mask & IN_IGNORED) {
        remove_watch_mapping(ev->wd);
        return;
    }

    /* 目录自身移动后，按保存的根路径重新解析并安排重扫。 */
    if (ev->mask & (IN_MOVE_SELF | IN_DELETE_SELF)) {
        mark_path_reconcile(ev->wd);
        return;
    }

    /* 目录项移动用 cookie 关联旧名和新名，不能假设两条事件永远相邻。 */
    if (ev->mask & (IN_MOVED_FROM | IN_MOVED_TO)) {
        remember_or_match_cookie(ev->cookie, ev->wd, ev->name);
    }
}

修复：把 wd 映射改成可重建状态

可靠的修复不是“收到移动事件后给字符串拼一个新路径”，而是把监听器设计成可重建。建议为每个 watch 保存当前路径、父目录、对象类型和最后一次确认时间；收到目录移动信号后，先标记该节点待协调，再以业务根目录为准重扫，最后重新调用 inotify_add_watch 并原子替换映射。

1. 读取事件时保留 wd 和 cookie，不要立即覆盖旧映射。
2. 收到目录自身移动或移动入目录树时，解析当前路径并扫描目录内容。
3. 对新发现的子目录补挂 watch，扫描完成后再把节点标记为已同步。
4. 收到 IN_IGNORED 时移除旧 wd；重挂后把新 wd 写入同一业务节点。

防复发：用重扫和队列状态兜底

生产环境不要把“当前收到一条事件”当成状态已经完全同步。Linux 手册明确提醒，事件队列可能溢出，溢出时会收到 IN_Q_OVERFLOW，此前未处理的事件不能再逐条补回。此时应暂停增量处理，清理或标记缓存，重新扫描业务根目录并重建 watch。

排障可以先确认进程实际持有的 watch 集合：

# 通过 fdinfo 查看进程的 inotify watch，确认 wd 是否还在实例中。
grep -E '^inotify wd:' /proc//fdinfo/

# 发现溢出后触发全量协调，而不是继续猜测丢失事件的顺序。
logger "inotify queue overflow; schedule a full directory rescan"

还要给移动事件设置一个短暂的协调窗口：IN_MOVED_FROM 和 IN_MOVED_TO 可能不在同一次读取中出现，也不保证原子地同时进入队列。窗口结束仍匹配不到目标时，应按未完成移动处理并启动重扫，而不是永久保留一条悬挂 cookie。

延伸问答

为什么收到 IN_MOVE_SELF 后不能只改字符串路径？

因为路径名变化不等于目录树内容已同步，子目录 watch、待处理事件和并发改名都可能落后。改字符串只能修正表面显示，重扫才能恢复状态。

IN_IGNORED 是错误吗？

它更像生命周期信号，表示 watch 被显式或自动移除。收到后应删除旧映射；是否需要重新监听取决于对象是否仍应存在。

目录监听为什么会漏掉新子目录里的文件？

因为 inotify 目录监听不递归。新目录移入后要先扫描已有内容，再为子目录补挂 watch，并接受扫描期间仍需再次协调的竞态。

把 wd 看作短生命周期句柄，把路径和业务对象作为可重建状态，目录移动后的失效问题就会从“偶发丢事件”变成一套可观测、可恢复的协调流程。