扫描卡住不动怎么办：进度条一直停在 0% 或某个百分比

症状

扫描进度长时间停在同一个百分比（比如一直 0%、或一直 42%）
日志里不再有新的作品处理记录
Socket.io 推送停了，Web 界面没更新
扫描"永远不结束"

排查步骤一：看容器/控制台日志

# Docker
docker logs kikoeru --tail 200

# Windows：直接看 exe 所在窗口的输出

日志是最关键的线索。重点找：

线索 A：DLSite 反爬

日志里连续出现 metadata fetch failed、HTTP 403、timeout 之类的错误。

原因：DLSite 对你的 IP 或短时间内过多请求做了限制。解决：

等一段时间再试（通常几分钟到几小时）
配置爬虫请求间隔（config.json 里加 delay）
换个网络环境（比如手机热点）

线索 B：某个文件解析异常

日志里停在某个特定的文件或目录名附近。

原因：该文件格式不被 Kikoeru 识别、或文件名里有特殊字符导致解析器挂了。解决：

手动把那个文件夹暂时移走
重新扫描——如果能过，说明就是那个文件夹的问题
重命名文件夹、或手动把问题文件转成标准格式（mp3/flac）

线索 C：数据库锁竞争

日志里有 SQLITE_BUSY、database is locked。

原因：你同时触发了两次扫描（手动扫描 + 自动扫描），两个进程在抢 SQLite 写锁。解决：

停掉自动扫描（关掉配置里的 autoScan）
关掉手动扫描按钮
等几分钟让 SQLite 释放锁
只跑一个扫描任务

线索 D：Socket.io 连接断了

日志正常在跑，但 Web 界面没更新——WebSocket 断了。

解决：刷新浏览器页面，重新建立连接。扫描其实没停，只是推送断了。

排查步骤二：停掉重来

最简单的万能解法：

停掉 Kikoeru（docker compose down、关掉 exe、Ctrl+C npm 进程）
等 5 秒
重新启动
等启动完成后，手动点一次扫描（不要开自动扫描，先跑一次干净的）

如果第二次还是卡住，说明问题不是瞬时的，回到排查步骤一看日志。

排查步骤三：精简扫描范围

如果你的音声库特别大（几万条），可以：

暂时只挂载一个根文件夹（最小的那个）
扫描这个小库——如果能过，说明大库某个目录有问题
二分法定位：逐步加回根文件夹，找到是哪一个出问题

常见误区

❌ 以为"卡住" = "系统挂了" → 重启容器或服务器 → 其实只是 DLSite 限频，等会就好
❌ 同时点多次扫描按钮 → 制造数据库锁竞争 → 日志里全是 SQLITE_BUSY
❌ 扫描失败后不停重试 → 越重试越容易被 DLSite 限频 → 整个库都扫不了

扫描卡住大概率是个小问题，耐心等 + 看日志，总能找到原因。