发布日志
本文档记录 MusicFree 各版本的变更摘要、升级注意事项与破坏性变更。功能细节请参阅 功能特性 与各功能模块文档。
阅读说明
版本号规则
- 稳定版：
V1.x.y（如V1.1.5） - 预发布版：
v1.x.y-alpha.nn（如v1.2.0-alpha.09），功能可能仍在快速迭代，不建议直接用于生产环境
升级建议
- 升级前备份
data/music.db与配置文件 - 关注各版本 升级说明 中的扫描、插件、配置变更
- Alpha 版本之间可能包含数据库自动迁移；首次启动后观察日志是否正常
- 插件（尤其
mf-plugin-gomusicdl）版本与宿主需匹配，升级后建议在管理端确认插件已更新
Docker 升级示例：
bash
docker pull ansgoo/music-free:latest
docker compose up -d未发布（main 分支，计划 v1.2.0-alpha.10）
相对上一标签
v1.2.0-alpha.09的累积变更（截至 2026-05-24）。
V1.1.9
更新特性
音乐去重：三步向导
管理后台 音乐管理 → 音乐去重 改为清晰的三步流程，降低误操作风险：
- 生成指纹 —— 为缺失指纹的曲目批量补算 Chromaprint（已有指纹自动跳过）
- 重复检测 —— 按可配置阈值比对全库，输出重复组与相似度分数
- 去重 —— 组内手动勾选假删除，或 按规则批量清理（同专辑内保留无损 > 码率 > 时长；跨专辑重复默认全部保留）
媒体源扫描与指纹：更快、更稳
- 扫描提速：并发 worker、目录 hash 增量跳过未变更路径；WebDAV 支持部分读取与单次 OpenStream 解析，减少远程 I/O
- 指纹与扫描解耦：入库扫描不再强绑指纹计算；支持定时补指纹任务与管理端异步全库回填
- 指纹引擎：内嵌
chromaprint.wasm+ ffmpeg/ffprobe，不再依赖系统fpcalc；WASM 堆内存可配置上限，大文件 / WebDAV 特殊格式拉取与运行时错误恢复更稳健，大幅降低了docker镜像体积 - 指纹调度：支持任务中断与互斥锁，避免多任务争抢资源
ARM Docker 多架构镜像
CI 构建并推送 amd64 + arm64 双架构镜像，标签与 V1.1.8 一致，ARM NAS / 单板机可直接使用官方镜像。
飞牛 fnOS 原生应用（FPK）
新增 飞牛应用中心 可安装的原生 .fpk 包（非 Docker 模板），支持桌面快捷方式启停与向导配置音乐库路径；Release 流水线同时产出 amd64 / arm64 安装包
其他改进
- WebDAV 媒体源：在开启「允许回写音乐源文件标签」时，清洗 / 刮削 / 元数据编辑可写回远程标签（需 WebDAV PUT 权限）
- 标签清洗：内置
RULE-03扩展支持标题前导下划线序号（如_01.）清理 - 远程搜索 / 下载：插件选项展示插件图标，远程曲目列表增加加载骨架屏
- 默认策略：新装默认关闭「回写音频源文件标签」，降低误改 NAS 原文件风险（可在 系统设置 中开启）
升级说明
| 场景 | 建议操作 |
|---|---|
自旧版升级且已开启 fingerprint.enabled | 进入 音乐去重 执行「生成指纹」，或对媒体源全量扫描一次 |
| 飞牛用户 | 可选用 Docker 镜像或从 Release 附件安装对应架构 FPK |
升级前请备份 data/music.db
其他修复
- 优化指纹生成任务状态提示与进度展示（支持更细粒度进度）
- 修正部分管理端路由重定向与守卫逻辑
- 依赖与构建脚本小幅更新，提升稳定性
V1.1.7
新功能
歌曲许愿
- 用户可为尚未入库的曲目提交愿望（手动新建，或从外部歌单未匹配条目一键 / 批量许愿）
- 愿望状态：
pending（待处理）、fulfilled（已实现）、rejected（已拒绝） - 按归一化键
norm_key（作品名|艺术家|专辑）去重；管理员实现时同键下所有用户的待处理愿望批量闭环 - 管理员 愿望管理（
/admin/wish）：远程搜索、下载入库、拒绝；复用远程音乐搜索能力 - 外部歌单详情展示当前用户的
wishStatus（none/wished/fulfilled） - 说明文档：许愿
歌单增强
- 公开歌单不可删除，返回明确错误提示
- 新增未匹配曲目重链（
RelinkUnmatchedPlaylistSongs）：库内已有对应歌曲时自动绑定外部歌单行 - 前端歌单卡片与列表 UI 重构（
PlaylistCard组件）
歌曲清洗功能
歌曲文件的元数据存在各种各样的脏数据，元数据清洗功能在扫描入库的时候会按照特定规则对歌曲文本进行清洗
修复
- 修复了
--gap-smCSS 变量丢失导致部分样式异常 - 修复了暗黑模式下，message消息看不清的样式异常
- 修复特定情况下播放器播放会有重音的问题
- 重构了歌单列表视图