备份与数据目录

V1 以文件目录为核心。正确的持久化和备份比容器本身更重要。

目录职责

容器目录	内容	建议
/server/data	用户、歌单、设置、快照、下载队列和服务配置数据	必须持久化并备份
/server/music	用户下载曲库和手动放入的音乐	必须持久化，按需要备份
/server/cache	播放缓存、缓存歌词等可再生成内容	持久化可提升体验，可按需清理
/server/logs	服务运行和错误日志	建议持久化，定期清理

不要把 /cache 与 /music 映射到同一个宿主目录，否则清理缓存可能影响下载文件，也会导致曲库识别混乱。

用户目录

音乐和缓存通常按规范化后的用户名分目录：

music/admin/
music/user01/
cache/admin/
cache/user01/

用户名不区分大小写，并统一使用小写目录。不要手动创建大小写不同但实际代表同一用户的目录。

快照

服务会保存歌单等同步数据的历史快照。管理后台可：

• 查看和下载快照。
• 恢复到指定时间点。
• 删除不再需要的快照。
• 上传已有备份。

快照主要保护同步数据，不等同于完整备份 /music 音频文件。

WebDAV

WebDAV 用于服务器配置和数据备份，不用于同步音频元数据数据库，也不会代替 LX Music 的实时同步连接。

管理后台支持：

• 测试 WebDAV 连接。
• 增量同步数据文件。
• 创建并上传全量备份。
• 从远端恢复。
• 配置同步和备份周期。

远端恢复会覆盖本地相关数据，执行前确认服务器版本、账户和目录结构匹配。

推荐备份策略

1. 每日备份 /server/data。
2. 根据下载成本和 NAS 冗余情况备份 /server/music。
3. /server/cache 通常无需异地备份。
4. 保留最近的服务日志用于排查升级后问题。
5. 更新镜像前记录当前 tag，并确认备份可读取。

容量管理

可启用缓存空间限制，超出容量后按 LRU 清理旧缓存。限制只应作用于缓存目录，不应把下载曲库当作可自动回收内容。

磁盘接近满载时暂停下载和洗版。洗版替换期间需要同时容纳原文件和新文件，实际临时空间会高于最终曲库大小。