故障排查
排查时先记录：镜像 tag 或桌面版本、用户名、歌曲名、来源平台、目标音质、发生时间和服务端日志。不要在 Issue 中公开密码、Cookie、Token 或完整音源脚本密钥。
页面与登录
登录后仍提示“请先登录同步账户”
确认登录的是同步账户而不是管理后台密码。注销后重新登录，检查 /api/user/auth/verify 是否成功，并查看浏览器控制台是否存在 Token 或请求路径错误。
本地音乐列表为空
- 清空搜索与筛选条件。
- 确认登录的用户名与
music/<用户名>目录一致。 - 检查容器挂载和目录读取权限。
- 等待大曲库扫描完成并查看日志。
- 确认文件扩展名和容器格式受支持。
桌面客户端空白
检查端口占用、应用日志和硬件加速。完整步骤见桌面客户端。
播放
本地已有歌曲却再次换源
系统没有把本地文件与播放记录匹配为同一首歌。常见原因是平台 ID 缺失、来源平台被旧版本错误标记、歌手或专辑元数据差异，以及索引未刷新。
在本地音乐中执行批量更新元数据并重新扫描。不要仅修改文件名，匹配主要依赖音频标签和服务器索引。
tx 自动切换到 kw
先确认设置目标音质，再查看音质弹窗标记的实际平台。若腾讯目标地址解析失败，系统会换源保证播放。更新腾讯音源、检查其 Cookie/会员要求，并在音源日志中确认失败原因。
浏览器能播，Subsonic 客户端不能播
检查反向代理 Range 请求、客户端支持格式和服务端流接口日志。首次在线解析可能较慢，但命中本地文件后不应每次等待相同时间。
下载与音质
音质大小显示未知
重新打开下载弹窗触发探测。若持续未知，检查音源是否返回 Content-Length、是否支持 Range，以及该档音质是否真实存在。未知大小与下载成功是两个独立状态。
选择母带却得到其他音质
查看任务结果中的实际音质和来源平台。目标不可用时可能按设置降级。若不允许降级，应关闭相应选项并接受任务失败。
关闭浏览器后下载停止
只有“下载到服务器”使用持久服务端队列。浏览器下载依赖页面，关闭后无法继续。
歌词或封面没有写入
确认下载设置已启用歌词和封面；检查源是否返回有效内容，以及音频容器是否支持标签写入。系统可能保存外置 .lrc，即使无法内嵌。
本地文件
文件显示错误平台
旧文件可能含错误来源标签或历史文件名中的平台标识被误解析。执行批量更新元数据和重新扫描。新文件的平台 ID 存在标签与索引中，不应追加到文件名。
显示有封面但实际没有
可能存在空图片标签、损坏图片或索引缓存。更新元数据并重新扫描；如果仍出现，记录文件名并提供标签读取日志。
数万首歌曲扫描不完整
先确认扫描是否仍在运行，而不是立即判断不支持。检查内存、NAS I/O、文件权限和不支持格式；按目录分批导入更容易定位坏文件。
日志位置
- Docker：宿主机映射的
logs目录，或运行docker logs yinyun。 - 桌面端：托盘菜单打开存储位置后查看日志目录。
- 管理后台：系统日志页面可在线查看和检索。
提交问题：GitHub Issues。