Xiaomusic故障排除完全指南：从登录到播放的全方位解决方案

设备列表空白？从网络到配置的深度排查

问题场景

用户在Xiaomusic后台界面中无法看到已连接的小爱音箱设备，日志中频繁出现70016错误代码，表现为"登录验证失败"。

排查流程图

开始 → 检查网络连接 → 验证账号安全状态 → 检查配置文件 → 重启服务 → 问题解决/进一步诊断

解决方案

1. 网络环境优化

适用场景：网络不稳定或存在代理干扰时
操作步骤：

1. 关闭系统或浏览器代理设置
2. 切换至5GHz Wi-Fi网络（若支持）
3. 执行网络诊断命令（Docker环境）：

   docker exec -it xiaomusic ping account.xiaomi.com  # 测试小米服务器连接
   

风险提示：修改网络设置可能导致其他网络服务暂时中断

2. 账号安全验证处理

适用场景：开启了两步验证或账号异常时
操作步骤：

1. 访问小米账号中心完成安全验证
2. 在米家APP中退出并重新登录
3. 清除Xiaomusic的token缓存文件（原生系统）：

   rm ~/.xiaomusic/token.json
   

风险提示：重新登录可能需要重新配置设备列表

3. DID配置修复

适用场景：设备ID配置错误或丢失时
DID配置就像设备的身份证设置，每个小爱音箱都有唯一的标识符。
操作步骤：

1. 登录Xiaomusic后台，进入"设置"→"设备管理"
2. 重新输入正确的DID并保存
3. 重启服务（Docker环境）：

   docker restart xiaomusic
   

风险提示：错误的DID会导致设备无法控制，需确保与音箱实际DID一致

预防措施

• 定期备份setting.json配置文件
• 避免在公共网络环境下登录账号
• 开启"自动重新登录"功能保持会话活跃

语音控制失效？从对话到权限的逐层分析

问题场景

网页后台可以正常播放音乐，但通过"小爱同学"语音指令无法控制音乐播放，设备无响应或提示"无法连接服务"。

图：Xiaomusic操作界面，红框标注了播放控制区域和设备切换功能

排查流程图

开始 → 检查对话记录 → 验证权限设置 → 重启服务 → 检查设备兼容性 → 问题解决

解决方案

1. 对话记录权限修复

适用场景：首次配置后或权限变更后
操作步骤：

1. 进入Xiaomusic设置页面
2. 开启"允许获取对话记录"选项
3. 重启容器使设置生效（Docker环境）：

   docker restart xiaomusic
   

风险提示：关闭对话记录权限会导致所有语音控制失效

2. 特殊设备型号适配

适用场景：M01/XMYX01JY等特殊型号设备
操作步骤：

1. 进入"高级设置"页面
2. 启用"特殊型号支持"选项
3. 手动指定设备型号并保存 风险提示：错误的型号设置可能导致功能异常

预防措施

• 设置每日定时重启任务（通过crontab）
• 避免频繁修改设备配置
• 定期清理对话记录缓存

播放无声音？从链接到设备的全链路检测

问题场景

日志显示音乐正在播放，但音箱没有声音输出，进度条正常走动。

排查流程图

开始 → 测试直接播放链接 → 检查音量设置 → 验证网络路径 → 检查设备连接 → 问题解决

解决方案

1. 媒体链接测试

适用场景：怀疑音乐文件损坏或链接错误时
操作步骤：

1. 在后台点击"播放链接"按钮直接测试
2. 检查返回的音频URL是否可访问
3. 验证文件格式是否支持（支持MP3/WAV/FLAC格式） 风险提示：直接访问媒体文件可能暴露本地网络结构

2. 网络路径配置

适用场景：多网络环境或端口映射复杂时
操作步骤：

1. 检查XIAOMUSIC_HOSTNAME配置是否正确
2. 确保防火墙开放播放端口（默认8080）
3. 使用IP地址替代域名测试（原生系统）：

   export XIAOMUSIC_HOSTNAME=192.168.1.100  # 替换为实际IP
   

风险提示：修改网络配置可能影响其他用户访问

预防措施

• 使用固定IP地址配置
• 定期测试媒体链接可用性
• 开启"播放状态监控"功能

常见误区解析

误区一：频繁修改账号密码

许多用户遇到登录问题时第一反应是修改密码，实际上大多数70016错误是由于安全验证而非密码错误导致。正确的做法是先完成小米账号的安全验证。

误区二：忽略容器重启

修改DID或网络配置后，必须重启容器才能生效。很多用户保存配置后直接使用，导致设置未生效。

误区三：DID与设备不匹配

每个小爱音箱设备有唯一的DID，用户常错误地使用了路由器或其他设备的ID，导致无法控制。

问题反馈渠道与社区支持

如果以上解决方案无法解决您的问题，可以通过以下方式获取帮助：

1. 项目issue系统：提交详细的错误日志和复现步骤
2. 社区讨论：参与项目讨论区的故障排除话题
3. 配置检查工具：运行项目根目录下的check_plugins.py脚本进行自动诊断

定期访问项目文档（docs/index.md）获取最新故障排除指南和版本更新信息。

通过本指南提供的系统化排查流程，大多数Xiaomusic使用问题都能得到快速解决。遇到复杂问题时，建议先查看日志文件获取详细错误信息，这将极大提高问题定位效率。