主题
音乐自动化
音乐自动化可以搜索下载、刮削整理曲库，并搭建私人音乐流媒体服务。三个组件可以按需组合：只下载、下载 + 整理、下载 + 播放，或完整三件套。
组件构成
| 组件 | 关系 | 分组 | 作用 |
|---|---|---|---|
| music-dl | 必选 | 下载 | 音乐搜索与下载 |
| Music Tag Web | 可选 | 整理 | 音乐刮削、标签编辑与自动整理 |
| Navidrome | 可选 | 播放器 | 私人音乐流媒体与在线播放 |
目录约定（重点）
音乐组合共享一个存储根目录，默认把本地 music 目录挂载到 /mnt/music，并提供几条嵌套挂载：
| 本地路径 | 容器路径 | 用途 |
|---|---|---|
music | /mnt/music | 共享根目录，Navidrome 读取曲库与歌单 |
music/downloads | /app/media/downloads | Music Tag Web 的下载目录 |
music/library | /app/media/music | Music Tag Web 的整理/曲库目录 |
music/downloads | /home/appuser/data/downloads | music-dl 的下载目录 |
建议把本地路径改成绝对路径，例如 /mnt/disk1/music，并保持所有行位于同一个根目录下。公共配置已经预置这些嵌套挂载，不要删除，否则对应组件会扫不到文件。
默认共享环境变量：
| 变量 | 默认值 | 说明 |
|---|---|---|
TZ | Asia/Shanghai | 时区 |
ND_MUSICFOLDER | /mnt/music/library | Navidrome 曲库目录 |
ND_PLAYLISTSPATH | /mnt/music/playlists | Navidrome 歌单目录 |
ND_SCANNER_SCHEDULE | 1h | Navidrome 定时扫描间隔 |
ND_* 仅 Navidrome 使用，其他组件会忽略。
自动配置
部署完成后平台会自动：
- 初始化 music-dl、Music Tag Web、Navidrome 的账号；Music Tag Web 会先尝试内置默认账号，再回退到统一密码
- 把下载目录写入 music-dl，优先使用共享卷中的
/app/media/downloads - 把 Navidrome 曲库指向共享目录
自动整理（Music Tag Web）
如果部署了 Music Tag Web，应用面板会多出「自动整理」标签页：
- 后端按设定间隔扫描下载目录，调用 Music Tag Web 完成刮削，再按目录模板整理进曲库
- 检查间隔（默认 5 分钟）、每轮最多处理文件数（默认 20）、文件稳定等待时间（默认 60 秒）
- 自动刮削、自动整理、整理后触发 Navidrome 扫描
- 音乐源：网易云、QQ 音乐、酷狗、酷我、咪咕、B 站、千千
- 写入字段：标题、艺术家、专辑、封面、年份、歌词
- 整理目录层级默认「艺术家/专辑」，最多添加 4 层
配置保存在自动化页的应用配置中，不修改应用镜像。失败文件最多重试 5 次，间隔逐步延长。
后台定时执行需要授权；手动「立即整理」不受影响，建议先手动跑一次验证目录和刮削结果。
部署步骤
- 在「自动化配置 → 音乐」中点击「部署」
- 保留 music-dl；需要刮削整理勾选 Music Tag Web，需要在线播放勾选 Navidrome
- 公共配置中把各行的本地路径改为同一个实际根目录下的对应子目录
- 提交部署并等待账号配置完成
- 在 music-dl 中搜索下载音乐，文件进入下载目录
- 用 Music Tag Web 刮削整理，结果进入曲库目录
- Navidrome 按
ND_SCANNER_SCHEDULE自动扫描，也可在后台手动触发
部署后检查清单
- [ ] music-dl 下载一首测试歌曲，文件出现在共享的下载目录
- [ ] Music Tag Web 能看到该文件并完成刮削整理，结果进入
library - [ ] Navidrome 扫描后能在线播放，并显示封面与标签信息
- [ ] 自动整理面板的目录检测没有红色报错
常见问题
Navidrome 里没有音乐 确认文件已经被整理进 library 而不是只停留在 downloads，并检查 ND_MUSICFOLDER 是否被改坏；然后在 Navidrome 后台手动触发一次扫描。
Music Tag Web 扫不到文件 它的整理目录是 /app/media/music，只对应共享的 library；请先把下载文件整理/移动到该目录，或检查公共配置中的嵌套挂载是否被删除。
music-dl 下载到了别的位置 平台会优先把共享卷中的 /app/media/downloads 写成下载目录；如果公共配置被改坏，可在应用面板的「检测优化」或 music-dl 自身设置中修正。
歌词与歌手信息不全 刮削依赖 Music Tag Web 的在线数据源，网络不佳时结果会受影响；可在其设置中调整数据源，或参考影视组合的思路优化域名解析与代理。