Xiaomusic使用故障诊疗指南：从现象到根治的系统方法

设备列表丢失：三步重建连接

问题特征描述

后台管理界面设备列表为空，无法选择播放设备，日志中可能出现验证相关异常信息。用户尝试语音控制时无响应，米家APP中设备在线但无法与Xiaomusic关联。

排查流程图

1. 基础检查 ➡️ 确认账号状态
   ├─ ✅ 米家APP能正常登录且设备在线
   ├─ ⚠️ 检查网络环境是否有代理配置
   └─ 🔍 查看Xiaomusic日志文件中的认证相关记录

2. 配置验证 ➡️ 关键参数核对
   ├─ ✅ 检查setting.json中账号密码正确性
   ├─ ⚠️ 确认DID配置与设备型号匹配
   └─ 🔍 验证XIAOMUSIC_HOSTNAME是否正确设置

3. 连接重建 ➡️ 系统状态重置
   ├─ ✅ 删除配置文件后重新初始化
   ├─ ⚠️ 重启容器确保配置生效
   └─ 🔍 检查防火墙设置是否阻止设备通信

解决方案分级

快速修复

1. 访问网页后台，在"账号设置"中重新输入小米账号密码并保存
2. 点击"设备管理"页面的"刷新设备列表"按钮
3. 若仍无设备，在终端执行docker restart xiaomusic重启服务

彻底根治

1. 备份原配置文件：cp setting.json setting.json.bak（风险提示：修改配置前建议备份）
2. 删除现有配置：rm setting.json
3. 重启应用后通过引导流程重新配置设备
4. 验证网络环境：确保服务器与小爱设备在同一局域网，DNS设置为223.5.5.5

预防措施

1. 配置优化：在"系统设置"中启用"自动刷新设备列表"功能，设置每小时更新一次
2. 定期维护：创建每周执行的定时任务，运行xiaomusic reinit命令刷新认证状态
3. 环境监控：使用网络监控工具检查与小米服务器的连接稳定性

语音控制失效：对话链路修复

问题特征描述

网页后台可正常播放音乐，但通过小爱同学语音指令无响应，设备指示灯正常亮起但无音乐输出，日志中可能出现"无法获取对话记录"相关提示。

排查流程图

1. 对话记录检查 ➡️ 基础功能验证
   ├─ ✅ 查看Xiaomusic日志中是否有对话记录拉取信息
   ├─ ⚠️ 检查小爱音箱APP中的历史对话是否包含音乐指令
   └─ 🔍 确认"拉取对话记录"功能是否已启用

2. 权限与配置 ➡️ 功能开关检查
   ├─ ✅ 验证DID配置后是否已重启服务
   ├─ ⚠️ 检查"特殊型号获取对话记录"开关状态
   └─ 🔍 确认设备型号是否在支持列表中（如M01/XMYX01JY需特殊配置）

3. 服务状态 ➡️ 核心进程检查
   ├─ ✅ 确认xiaomusic服务是否正常运行
   ├─ ⚠️ 检查网络连接是否能访问小米对话API
   └─ 🔍 查看系统时间是否与标准时间同步

解决方案分级

快速修复

1. 在网页后台"高级设置"中，启用"特殊型号兼容模式"
2. 重启Xiaomusic服务：systemctl restart xiaomusic
3. 在小爱音箱APP中解除设备绑定后重新关联

彻底根治

1. 升级到最新版本：git pull && ./install_dependencies.sh
2. 修改配置文件启用详细日志："debug": true（风险提示：详细日志可能包含敏感信息）
3. 配置定时任务：设置每天凌晨3点自动重启服务
4. 对于M01/XMYX01JY型号，在配置文件中添加："special_device_support": true

预防措施

1. 配置优化：设置对话记录拉取频率为3秒/次，避免触发频率限制
2. 定期维护：每周清理一次对话记录缓存，防止数据累积导致解析错误
3. 风险规避：使用定时任务在夜间12点至早7点关闭对话记录拉取，降低账号风控风险

播放无声：音频通路排查

问题特征描述

日志显示"正在播放"但无声音输出，进度条正常走动，网页播放器可正常发声，设备连接状态显示正常。

排查流程图

1. 播放测试 ➡️ 基础功能验证
   ├─ ✅ 点击网页后台"播放测试"按钮
   ├─ ⚠️ 直接访问音频文件链接测试播放
   └─ 🔍 检查设备音量是否被静音

2. 网络配置 ➡️ 连接参数检查
   ├─ ✅ 确认XIAOMUSIC_HOSTNAME配置为局域网IP
   ├─ ⚠️ 验证端口映射是否正确（默认8080）
   └─ 🔍 检查防火墙是否阻止设备访问媒体文件

3. 设备状态 ➡️ 硬件功能检查
   ├─ ✅ 测试设备播放其他音频是否正常
   ├─ ⚠️ 检查设备网络连接稳定性
   └─ 🔍 重启小爱设备后重新尝试

图：Xiaomusic播放控制面板，显示设备控制和播放状态区域

解决方案分级

快速修复

1. 在设备列表中切换设备后重新播放
2. 点击播放器"音量"按钮确保未静音
3. 在"设置-音频"中切换不同的音频输出模式

彻底根治

1. 检查并修正XIAOMUSIC_HOSTNAME配置，确保使用局域网IP而非127.0.0.1
2. 验证媒体文件权限：chmod -R 755 ./music（风险提示：修改文件权限可能影响系统安全）
3. 更换音频编码格式，在配置中设置："audio_codec": "mp3"
4. 对于多设备同步问题，在设备分组中配置DID并启用组播模式

预防措施

1. 配置优化：启用"播放前音频检测"功能，自动验证文件可播放性
2. 定期维护：每周执行一次媒体库完整性检查，修复损坏文件
3. 环境优化：确保服务器与播放设备在同一网段，减少网络延迟