Xiaomusic常见问题诊断与解决方案

认证类问题处理

您可能遇到登录后无法看到设备列表的情况，日志中通常会出现以下信息：

Exception: {'code': 70016, 'description': '登录验证失败'}

根源分析

此问题主要与小米账号安全机制相关，可能原因包括：

• 账号启用了二次验证机制
• 网络环境存在代理干扰
• 配置文件中的身份信息错误

分级解决方案

🛠️ 基础方案（★简单）

• 关闭系统或浏览器代理设置
• 检查setting.json文件中账号密码是否正确

🛠️ 进阶方案（★★中等）

• 在米家APP中退出并重新登录账号
• 访问小米官网完成安全验证流程

预防措施

• 定期执行reinit任务刷新登录状态
• 避免在公共网络环境下使用账号

连接类问题排查

当您看到类似以下日志时，表明存在网络连接问题：

aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host account.xiaomi.com:443 ssl:False [Temporary failure in name resolution]

根源分析

网络连接问题通常涉及：

• DNS解析异常
• 容器网络配置不当
• 防火墙规则限制

分级解决方案

🛠️ 基础方案（★简单）

• 将DNS服务器设置为223.5.5.5
• 重启网络设备

🛠️ 进阶方案（★★★进阶）

• 将Docker网络模式切换为host模式
• 检查防火墙是否允许443端口出站连接

预防措施

• 配置网络连接监控告警
• 使用静态DNS配置提高解析稳定性

功能类异常解决

您可能会遇到这样的错误提示：

{"code":601,"message":"illegal argument exception","data":"IllegalArgumentException: ubus call format illegal!"}

根源分析

这类问题通常与设备配置相关：

• DID（设备唯一标识符）设置错误
• 设备类型选择不匹配
• 配置未正确应用

分级解决方案

🛠️ 基础方案（★简单）

• 在设置页面重新选择正确的设备类型
• 确认DID配置无误后保存

🛠️ 进阶方案（★★中等）

• 保存DID后重启应用容器
• 检查配置文件格式是否正确

预防措施

• 修改配置后执行配置验证
• 定期备份配置文件

用户场景诊断流程

场景一：网页后台可播放，语音控制无效

🔍 排查点

1. 检查容器是否在DID更改后重启
2. 查看应用日志中是否有对话记录拉取失败信息
3. 确认设备型号是否需要特殊配置

场景二：日志显示播放中但无声音输出

🔍 排查点

1. 测试播放链接的可访问性
2. 验证XIAOMUSIC_HOSTNAME配置
3. 检查端口映射是否正确

高级功能配置指南

立体声播放设置

对于多设备同步播放需求：

🛠️ 操作项

• 在设备控制界面勾选多个目标音箱
• 在分组配置中输入多个DID创建播放组
• 注意：目前多设备同步存在约1秒延迟

定时任务优化

为避免风控限制：

🛠️ 操作项

• 设置夜间自动关闭对话记录拉取
• 配置每日定时执行reinit任务
• 使用正确的cron expression格式

版本更新注意事项

当更新后出现设备消失问题：

🛠️ 操作项

1. 重新验证账号信息
2. 在设置页面重新保存配置
3. 尝试切换至默认主题测试

数据迁移建议

• 更新前备份setting.json
• 使用git pull保持代码最新
• 执行install_dependencies.sh确保依赖正确