扫描不到书？常见排查步骤

如果您在添加存储库后，点击「扫描」却没有任何书籍显示，请根据您的 存储库类型 选择对应的排查方案。

模式 A：本地存储库 (Local Storage)

适用于飞牛 NAS 原生应用或 Docker 挂载本地目录的场景。

1. 路径有效性

飞牛原生应用：请确保填写的路径是绝对路径（例如 /vol5/Media/AudioBooks）。
Docker 部署：请确保填写的路径是 容器内部 的挂载路径（例如 /books），而不是宿主机的路径。

2. 权限检查

Leelaa Reader 进程必须有权读取该目录。

飞牛原生应用：请检查该文件夹的权限设置，确保 leelaa 用户或应用具有读取权限。
日志排查：查看 info.log，如果看到 Permission denied，说明权限不足。

模式 B：WebDAV 存储库

适用于连接 NAS 自带 WebDAV、原生 WebDAV 服务，或第三方工具转出的 WebDAV 服务。

1. 连接测试

在存储库设置中点击 「测试连接」。
连接失败：检查地址（是否带 http/https）、端口、用户名和密码。
内容为空：检查「根目录」是否填写正确。根目录应以 / 开头，指向存放书籍的文件夹。

2. 兼容性设置

兼容模式：如果连接第三方 WebDAV 桥接工具时扫描不稳定，请尝试在存储库设置中开启「兼容模式」。
网络限制：部分 WebDAV 服务对并发请求有限制，可能导致大批量扫描时断连。

3. 共同规则（必读）

无论哪种模式，书籍的存放都必须符合以下规范：

目录结构规范

文件夹即书籍：每一本书必须放在一个独立的文件夹内。根目录下的散乱音频文件不会被识别。
层级要求：建议结构为 根目录/书名/章节.mp3。
分段目录兼容：也支持 根目录/书名/1-500/第1集.mp3、根目录/书名/501-999/第501集.mp3 这种分段存放方式。

4. 音频格式不被支持（不支持 .aac / .ogg 等）

问题表现： 书名建好了，但点进去“没有章节”，或者整本书直接被系统跳过。

排查原因： 系统默认支持 .mp3、.m4a、.m4b、.flac、.wav、.wma 格式，其中 .wma 依赖服务端 FFmpeg 转码播放。系统明确不支持以下格式，扫描时会自动忽略它们：

.aac (裸流)
.ogg
.opus
任何带有 DRM 加密的专属格式（如喜马拉雅的 .xm，QQ音乐的 .qmc）

解决方法： 使用音频转换工具（如“格式工厂”或 FFmpeg）将不支持的有声书批量转换为通用的 .mp3 或 .m4a 格式，然后重新扫描。.wma 若无法播放，请检查服务端是否已开启并检测到 FFmpeg。

查看任务状态

进入管理后台的 「任务中心」。
检查是否有扫描任务报错。如果有错误，点击查看详情，或查看服务器日志（info.log 或 docker logs）获取具体原因。