LX Music Sync Server v2.1.1

v2.1.1 (2026-09-22)

🌟 新增功能与优化 (#381)

• 同步协议路由防拦截与播放器鉴权隔离 (#390):
  • 修复启用 Web 播放器密码导致 LX 客户端无法连接与同步歌单的缺陷: 当播放器访问路径设置为根路径 / 且开启「启用 Web 播放器密码 (player.enableAuth)」时，服务端将 LX Music 同步握手与鉴权路由（/hello、/id、/ah 以及 /<username>/... 等）误判定为播放器页面请求，返回 302 重定向到 /login 导致 App 报错 Connect service failed。
  • 白名单精准分流: 在底层路由分发逻辑中增加同步协议正则过滤，将同步协议路由及全局配置脚本与播放器页面鉴权严格隔离，彻底解决根路径模式下播放器密码与客户端同步互斥的问题。
• 服务端控制台日志全面中文化与规范化:
  • 全面排查并重构了服务端核心模块（包括系统管理、文件缓存、用户管理、音乐库同步、任务调度、WebDAV 等）的控制台输出日志。
• 自定义源版本更新智能检测与提醒卡片:
  • 更新通知多渠道捕获与请求自动嗅探: 全面支持标准阻断式 lx.send('updateAlert') 事件与第三方脚本后台异步请求结果（HTTP 响应体内包含 updateMsg / updateUrl）的智能嗅探，自动将最新版本提示持久化关联至对应音源。
  • 
• 开发调试 DEBUG 模式开关与沙箱日志静默:
  • 基础配置新增 DEBUG 模式 (debug.enabled / 环境变量 ENABLE_DEBUG): 支持在后台基本配置中一键启停 DEBUG 调试日志输出（默认关闭，供开发人员使用）。
  • 第三方音源沙箱日志静默机制: 在非 DEBUG 模式下自动代理并静默第三方音源脚本沙箱中的普通 console.log / info / debug / warn 输出，仅保留关键错误日志，避免服务启动与运行过程中控制台被第三方脚本日志刷屏。
  • 
• 歌单同步下载任务稳定性与并发优化 (#386):
  • 并发下载超时控制与信号量释放: 修复在个别音源链接请求挂起、网络拥塞或解析异常时同步队列卡死阻塞后续所有歌单的问题，增加单曲解析/下载严格超时降级与错误重试保护。
  • 失败歌曲高品质展开列表与报错跑马灯:
    • 支持在未全同步（红色 Tag）的歌单卡片上展开查看失败歌曲明细（采用与「我的收藏」一致的高品质列表风格，包含封面、序号、歌曲名、歌手、专辑、时长与错误原因）。
    • 失败原因（如 No downloadable source found / VIP limitation 等）自适应接入动态跑马灯检测函数（createMarqueeHtml / applyMarqueeChecks），长文本超出容器宽度时平滑循环滚动展示，支持卡片展开时实时触发检测。
• 歌单同步下载重复下载与重试机制优化 (#387):
  • 已下载文件跳过逻辑增强: 修复当本地已存在同名或已下载歌曲时重复发起解析与下载请求的问题，准确识别本地磁盘缓存与数据库索引，避免多余网络开销。
  • 进度条计算与总曲数统计校准: 修复整体进度条分母统计异常、跨歌单时进度提前跑满（如分子超过分母）以及单个歌单计数显示不准的问题。
  • 单歌单独立手动重试支持: 后端支持按指定 playlistId 触发局部同步；当同步完成且存在失败歌曲时，在对应歌单卡片开关旁提供「重试同步」按钮。
  • 同步运行态动态互斥保护: 修复在点击全局「立即同步」或开始同步后歌单重试按钮依然显示的问题，同步运行期间（isRunning === true）全局自动隐藏各卡片上的重试按钮，并将状态 Tag 动态更新为「同步中」或「等待同步」，同步结束后自动恢复。
• 歌单同步下载目标音质、存储位置设置与性能增强 (#388):
  • 同步目标音质独立配置:
    • 在同步下载控制面板中新增 「同步目标音质」 选项（支持 128k / 320k / flac / flac24bit 等）。
    • 歌单同步将严格按照设定的目标音质下载；当切换更高音质时，下一次同步将智能检测并自动将已下载歌曲重新下载更新至目标音质。
  • 同步存储位置灵活选择与智能热迁移:
    • 新增 「存储位置」 下拉配置，支持将同步下载的音乐保存在 根目录 /music/、数据目录 /data/music/ 或 自定义音乐目录。
    • 切换存储位置时提供自动文件迁移机制（支持 root ↔ data ↔ custom 雙向互转），智能仅迁移已启用同步的歌单歌曲，并实时同步更新对应索引。
  • 自定义目录模式入口显示优化:
    • 优化前端“同步下载”入口按钮的显示逻辑，在开启自定义目录模式后，只要用户具有自动同步下载权限即常驻显示该入口，方便随时管理同步配置。
  • 自定义目录直达下载与索引维护:
    • 在自定义目录模式下，下载流直接写入目标自定义物理目录及对应歌单子文件夹（customDir/{歌单名}/），完全消除先下载至缓存再跨目录移动的中转开销与卡顿。
    • 同步结果直接维护生成自定义目录的 custom_index.json，无缝对接自定义音乐管理。
  • 即点即停（秒级打断）响应:
    • 彻底重构同步中止控制器机制，点击「暂停同步」时立刻联动底层下载流与网络请求强制断开，并自动清理 .tmp 临时文件，杜绝后台继续偷跑流量。
  • 
• 系统配置备份与管理中心 (configBackup.*):
  • 新增 config.js 定时自动轮换备份功能（默认开启），每天生成一份配置备份副本，防止误操作或系统异常导致配置丢失。
  • 支持自定义备份存储目录（configBackup.dir / 环境变量 CONFIG_BACKUP_DIR，默认 backups）与保留天数（configBackup.retentionDays / 环境变量 CONFIG_BACKUP_RETENTION_DAYS，默认 7 天），过期备份自动清理。
  • 修改备份目录后点击保存自动执行热迁移，平滑转移旧备份数据并即时生效。
• 全新「备份与恢复管理」面板:
  • 原「快照管理」升级为全新的 「备份管理」 面板，采用现代化分段 Tab 切换设计：
    • 📑 系统配置备份 Tab：提供状态概览徽标（自动模式与保留期）、支持「立即备份配置」、配置备份列表按生成时间精确倒序排列（包含「每日自动」与「手动备份」分类标签）、支持单个备份一键下载、一键回滚恢复配置（恢复前自动安全备份）以及手动删除。
    • 📑 歌单快照 Tab：保留并优化各用户歌单快照的查看、上传、回滚、下载与删除。
  • 
• 歌单快照自定义存储目录 (snapshot.backupPath):
  • 支持自定义歌单快照的存放路径（snapshot.backupPath / 环境变量 SNAPSHOT_BACKUP_PATH），可将快照保存在自定义数据盘或外部挂载目录。
  • 多用户快照数据独立隔离存放，各用户的快照读写与管理无缝对接。
  • 修改快照存储路径后点击保存支持即时热迁移，自动重定位所有活跃用户的快照管理器与物理目录，无需重启服务。
• 管理后台「备份与恢复设置」卡片:
  • 系统配置中新增直观的「备份与恢复设置」面板，提供详细的路径说明与填写引导。
  • 增加严格的路径合法性校验与写入权限预检，非法路径友好拦截报错。
  • Web 页面与服务端配置完整双向同步，刷新后持久化保留展示。
  • 
• Subsonic 独立监听端口与静默路由守卫 (#382 @pyss56):
  • 独立端口监听 (subsonic.port / 环境变量 SUBSONIC_PORT):
    • 支持为 Subsonic 协议配置独立的监听端口（0 为不启用，走主端口），将 Subsonic 客户端流量与主服务及管理后台端口物理隔离。
    • 严格鉴权与专属暴露：独立端口仅暴露 Subsonic 协议接口，复用 Subsonic 内部 verifyAuth 机制，只有携带合法 Subsonic 凭据（用户名/密码/Token）的用户方可访问。
    • 端口冲突智能感知：服务启动若遇端口占用（EADDRINUSE）或绑定异常，服务端记录冲突状态，前端管理控制台在对应端口输入框下方实时弹出配置未成功与更换端口引导提示。
  • 静默路由守卫与防探测:
    • 独立端口严格限制仅允许 /rest/{method} 请求，浏览器裸访问（如 /、/rest、/rest/）及网络扫描/爬虫探测一律直接返回无响应体的空 404 状态码，不暴露任何服务指纹与特征。
  • 管理后台交互优化:
    • 「系统配置 → Subsonic 协议配置」中提供「启用 Subsonic 独立监听端口」快捷开关，支持动态展开配置独立端口，保存时提供智能平滑联动。
    • 
• 出站代理按类别细分配置 (#383 @pyss56):
  • 分类独立代理管控 (proxy.music.* / proxy.customSource.* / proxy.app.*):
    • 将全局统一出站代理拆分为 音乐平台（内置源 SDK 请求）、自定义音源（用户导入的第三方脚本请求）与 应用功能（封面代理、AcoustID 歌曲识别、远程音源导入等）三大独立维度。
    • 各分类支持独立选择「沿用统一代理」、「直连（不走代理）」或「使用单独代理地址」，彻底解决部分内网/国内音乐平台在全局代理出口下被拦截导致无法播放的问题。
    • 完全向下兼容：未单独配置的分类自动继承全局 proxy.all.* 统一代理开关与地址。
  • 管理后台交互设计:
    • 代理配置卡片中新增分类代理下拉选择与按需展开的独立代理地址输入框及连通性测试。
    • 
• Subsonic 网络电台（Internet Radio）多源接入与精简隔离 (#384 @pyss56):
  • 网络电台完整协议接入 (getInternetRadioStations / createInternetRadioStation / updateInternetRadioStation / deleteInternetRadioStation):
    • 全面支持 Subsonic / OpenSubsonic 标准网络电台规范，客户端可浏览、自建、更新与删除电台。
    • 热门歌单电台 (radio_pl_*)：自动聚合各大音乐平台（网易云、企鹅、酷狗、酷我、咪咕等）的公开热门歌单包装为轮播电台，播放时由服务端自动进行真随机抽取单曲并流式播放。
    • QQ 官方电台 (radio_tx_*)：接入官方电台列表，内置智能可用性探测，接口不可用时优雅隐藏避免客户端报错。
    • 用户自建电台 (radio_usr_*)：支持用户在第三方客户端添加自定义外部流媒体直播源（如 Shoutcast / Icecast / HLS 直播流），请求时 302 秒播直达。
  • 用户级别数据完全物理隔离:
    • 用户自建电台持久化隔离存储至 data/users/<username>/radioStations.json，多用户环境互不干扰、独立增删改查。
  • 无状态紧凑短安全 Token (tk=<user>_<sig>):
    • 针对客户端播放网络电台直连 streamUrl 时不带 Subsonic 认证凭据的问题，创新采用确定性 HMAC 短 Token 机制，不暴露用户密码，防篡改且服务重启后永久有效，彻底消除了冗长的 URL 参数，显著提升音流（Stream Music）等客户端界面的清爽度与观感。
  • 各音源歌单 ID 自动清洗与透明还原:
    • 智能过滤清洗酷我（kw）等平台复合内部前缀（如 digest-8__），呈现干净整洁的数字 ID，播放解析时透明无缝还原，兼顾 URL 美观与底层 SDK 路由精准度。
  • OpenSubsonic 电台封面规范 (coverArt) 与 ICY 流媒体元数据中继:
    • 按 OpenSubsonic 标准扩展规范下发各大热门歌单电台的高清封面 coverArt。
    • 服务端支持 ICY Metadata 代理注入，为支持 ICY 协议的客户端动态注入当前播放的真实歌手与歌名。
• Subsonic 协议全量补全、智能歌手匹配与简繁双向搜索 (#385 @pyss56):
  • Subsonic / OpenSubsonic 协议全量补全:
    • 专辑详情与封面 (getAlbumInfo / getAlbumInfo2)：支持专辑描述（notes）与封面解析，构造不出平台直链时自动回退歌曲自带封面。
    • 播放状态与听歌历史 (reportPlayback / getNowPlaying / scrobble)：精确上报播放进度毫秒（positionMs）；按规范仅在 stopped 且未带 ignoreScrobble 时写入听歌历史；提供最近播放与最常播放列表，支持播放队列（getPlayQueue / savePlayQueue）与索引式队列接口。
    • 相似歌曲推荐 (getSonicSimilarTracks)：复用同歌手相似歌优选逻辑，按匹配度综合排序推荐。
    • 音频书签三件套 (getBookmarks / createBookmark / deleteBookmark)：支持跨客户端书签创建、读取与删除，分用户独立持久化存储。
    • 服务端转码决策与流支持 (getTranscodeDecision / getTranscodeStream)：自动下发安全签名 transcodeParams；支持服务端 ffmpeg 转码可用性探测（不可用时平滑降级 302 直链）、并发信号量限流控制、timeOffset 快速时间定位，并在 handleStream 中根据客户端 maxBitrate 智能决定转码。
    • 规范化扩展声明与参数修复：getOpenSubsonicExtensions 准确声明实际实现的官方扩展名（songLyrics, playbackReport, sonicSimilarity, indexBasedQueue, transcodeOffset, transcoding），确保第三方客户端准确调用；共享歌单支持「排行榜 / 歌单 / 都要」三态配置。
  • 智能歌手匹配与跨源合并:
    • 歌手寻址由「精确同名」升级为「相似度模糊匹配」，引入失败短缓存与详细诊断日志，解决大量歌手无法检索到的问题。
    • 跨音源歌手智能合并，名字型歌手 ID 优先复用本地规范 ID，搜索结果中跨音源同名智能去重。
    • 艺术家按拼音首字母索引精准分组，并对歌手头像做自适应尺寸优化。
  • 简繁体双向模糊搜索:
    • 新增轻量级简繁转换模块（zhConvert.ts），支持简繁双向互转变体匹配，彻底解决繁体搜索词匹配不到简体歌曲/歌手（或反之）的痛点。
  • 音源与搜索鲁棒性增强:
    • search3 补齐在线歌手与在线专辑检索（此前未收藏时结果为空）。
    • 腾讯与网易封面 URL 增加自适应尺寸与回退降级逻辑，避免客户端请求小图返回空白。
    • 百度音乐源精简（不再参与运行时搜索与初始化注册，保留历史数据兼容解析模块）。
• Web 音乐界面布局与元数据解析优化:
  • 歌曲列表表头与行网格精确对齐:
    • 统一「搜索结果」、「我的收藏/自定义歌单」、「排行榜」与「精选歌单」的 12 列网格（Grid）响应式布局与内边距定义，解决表头与内容行错位的问题。
    • 修正歌曲列表项垂直对齐方式（items-center），确保歌曲名、歌手、专辑与时长在同一水平线上对齐居中。
    • 调整右侧操作栏按钮间距与显示层级，避免在多列响应式下挤压或遮挡「时长」列。
  • 多源专辑名称解析与兼容显示:
    • 新增 getSongAlbumName 通用解析器，全量兼容并按优先级提取 albumName、album（字符串或对象）与 meta.albumName / meta.album 等不同音源/同步歌单的元数据格式。
    • 彻底修复导入/同步歌单（如 QQ/网易外部歌单）中专辑名称不显示或回退为横线（-）的问题。
• 本地音乐与洗版面板 UI 修复与体验增强:
  • 歌曲洗版弹窗 UI 结构与布局错乱修复: 修复洗版模态框头部 DOM 结构缺失导致的内容挤压、文字竖排排版错乱问题，补齐关闭按钮、副标题与滚动容器。
  • 洗版待选列表歌曲封面与平台 Tag 显示: 洗版待选歌曲列表中新增歌曲封面缩略图与音源平台徽标（如 TX / WY / KG / KW / MG），并完美适配下载目录及用户自定义目录的封面鉴权与多级回退机制。

---

• 本次版本由 @XCQ0607 维护构建 🚀