# 3-23 [done][bug] dev:hot 启动 inotify 限制导致 local-folder events 500 v1

> 发现时间：2026-05-23
>
> 状态：`[done]`
>
> 关联主线：`03-rust-web`

## 1. 用户可见症状

执行：

```bash
npm run dev:hot
```

启动日志出现：

```text
WARN System notification limit is too small, falling back to polling mode.
WARN Polling for changes every 500ms
ERROR response failed classification=Status code: 500 Internal Server Error latency=0 ms
```

`mnote-web` 本身能启动，但首屏随后会打一条 500。

## 2. 根因

浏览器网络请求定位到失败 endpoint：

```text
GET /api/local-folder/events?rootUri=...
```

该请求返回的错误体为：

```json
{
  "code": "internal_error",
  "message": "本地文件夹监听失败: OS file watch limit reached. about [\"/mnt/Data1T/Mnote_data/users/mnote-e2e/workspaces/my-space\"]"
}
```

因此根因不是 route 业务逻辑回归，而是 Linux `inotify` watcher 容量不足：

- `cargo watch` 在启动时检测到系统通知额度不足，降级为 polling。
- `mnote-web` 首屏建立本地工作区 SSE watcher 时也申请 watcher。
- 当前用户已有 watcher 占用接近系统上限，导致 `/api/local-folder/events` 创建监听失败并返回 500。

## 3. 修复

已在系统层即时提高并持久化 inotify 容量：

```bash
sudo sysctl fs.inotify.max_user_watches=1048576 fs.inotify.max_user_instances=1024 fs.inotify.max_queued_events=32768
```

持久配置写入：

```text
/etc/sysctl.d/99-mnote-dev.conf
```

内容：

```text
fs.inotify.max_user_watches=1048576
fs.inotify.max_user_instances=1024
fs.inotify.max_queued_events=32768
```

## 4. 验证

验证系统参数：

```bash
sysctl fs.inotify.max_user_watches fs.inotify.max_user_instances fs.inotify.max_queued_events
```

结果：

```text
fs.inotify.max_user_watches = 1048576
fs.inotify.max_user_instances = 1024
fs.inotify.max_queued_events = 32768
```

验证 SSE：

```text
/api/local-folder/events?... 返回 200，并收到 ready 事件。
```

验证启动：

```bash
FRONTEND_PORT=3107 timeout 10s npm run dev:hot
```

结果：无 `System notification limit` warning，无启动期 500。

重新启动真实入口：

```bash
npm run dev:hot
```

结果：`http://localhost:3000` 正常启动；浏览器首屏网络请求中 `/api/local-folder/events?...` 为 200。

## 5. 剩余边界

这是系统资源配置问题，本仓库代码不需要为本次 inotify 限制做业务改动。若后续再次出现同类 500，应先统计当前 inotify watcher 占用和后台进程，再判断是继续提高系统额度还是清理异常 watcher 进程。