xiaomusic Docker部署完整指南：小爱音箱用语音播放本地音乐

xiaomusic Docker部署完整指南：小爱音箱用语音播放本地音乐

【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic

早上六点四十分，你说了一句"播放专辑"，小爱音箱就开始播放 NAS 里存的音乐——没有会员费。xiaomusic 是一个让小爱音箱用语音播放本地音乐的开源工具，本文完整走一遍 xiaomusic Docker部署 与配置。

xiaomusic 是什么，适合谁

xiaomusic 运行在 NAS 或家用服务器上：它用网页控制台管理本地音乐库，通过小米账号接入小爱音箱，音箱收到一句语音指令就能播放本地歌曲，本地找不到时还可以在线搜索并下载播放。

• 适合已经有小爱音箱、且 NAS 或电脑上存着本地音乐库的人；
• 适合想自定义语音口令的人，比如把"下一首"改成自己习惯的说法；
• 适合有多台小爱音箱、想让一个服务统一接管的人；
• 没有小米账号、无法完成设备绑定的，不必折腾；
• 只打算听在线音乐、没有管理本地库需求的，也不必折腾。

xiaomusic Docker部署：一个配置文件加一条命令

这一节负责把服务跑起来。宿主机装好 Docker 即可，再准备两个本机目录，一个放音乐、一个放配置，不存在就先建好。compose 文件里只有一个服务：

services: xiaomusic: image: hanxi/xiaomusic container_name: xiaomusic restart: always ports: - 58090:8090 volumes: - /xiaomusic_music:/app/music - /xiaomusic_conf:/app/conf

冒号左边的两个目录改成你实际使用的路径，右边是容器内的固定目录，不要动。左侧 58090 是本地访问网页控制台的端口，右侧 8090 是容器固定端口，不可修改。文件保存后执行docker compose up -d即可，restart: always保证宿主机重启后服务自动拉起。账号、设备等参数都不需要设置环境变量，后面在网页里填。

xiaomusic配置：从绑定设备到第一次语音点播

这一节把控制台、设备、音乐库和语音指令串起来。

服务启动后，浏览器打开http://服务器IP:58090。进入左侧的设备控制入口，填入小米账号和密码并保存，页面会自动扫描局域网内可用的音箱，选中你的设备后绑定完成，系统会同时记下它的 DID（设备标识）。下图标出了控制台上各区域的主要操作：

如果自动发现不到设备，打开小爱音箱 App 的设备详情页找到 DID，在设置里手动填入。然后放音乐：把文件拷进映射的音乐目录，支持 mp3、flac、wav、ape、ogg、m4a、wma，子目录会作为歌单处理；在设置里打开文件监控后，新增文件会自动入库，不用手动刷新。

最后试语音。高频的四条开箱即用：播放歌曲周杰伦、下一首、单曲循环、10分钟后关机。如果说了一首本地没有的歌，xiaomusic 会在线搜索、下载到音乐目录再播放。

进阶玩法：多设备、网络歌单、定时播放

多台音箱同管：在配置项mi_did里用逗号分隔多个 DID，一个服务就能控制多台小爱音箱，控制台右上角的下拉框可以切换当前操作的目标设备。

网络歌单：music_list_url指向一个在线 JSON 歌单，或custom_play_list_json指向本地文件，歌单内容变了库就跟着变，不用动音乐目录。

定时播放：crontab_json指向一个定时文件，比如每天早上八点播一段晨间音乐、睡前定点停止播放，音箱到点自己跑。

账号与端口安全：服务只在局域网用就保持默认；需要对外暴露时，打开设置里的网页登录认证并设强密码，同时把 58090 端口限制在白名单内。绑定的小米账号建议用独立小号，不要把摄像头这类敏感设备挂在该账号下。

避坑清单：xiaomusic配置的常见问题

• 网页控制台打不开→ 58090 端口被占用或映射写错 → 换一个本地端口映射，容器端 8090 保持不变。
• 设备列表里没有音箱→ 账号未保存或设备不在同一网络 → 重新保存小米账号，确认音箱与服务器在同一局域网，或直接手动填 DID。
• 播放后无声或卡顿→ 设备型号不支持当前音频格式 → 在设置页打开"转换为 MP3"。
• 新增歌曲后歌单不更新→ 没开文件监控 → 打开监控开关，并给扫描留一点防抖时间。
• 语音指令没反应→ 口令与配置里的词条不匹配 → 在配置文件中核对key_word_dict的准确说法，也可以自行登记新口令。

xiaomusic 的价值在于把音乐库重新交回自己手里：文件是自己的，歌单是自己的，播放入口只是一句语音。完整配置项见仓库 README 与config-example.json。

【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic