XiaoMusic 教程：小爱音箱播本地音乐，Docker 部署全流程

家里那台小爱音箱，买回来第一周放儿歌，第二周开始只在早上播天气。想让它放自己的歌就卡住了：曲库要会员，本地存的无损音乐它不认——音箱上没有插卡口，也没有浏览文件的入口。

XiaoMusic 补的就是这个缺口。它是跑在 NAS 或者任意一台常开机器上的服务，用 Docker 起一个容器，把你的本地音乐目录开放给小爱音箱，然后用语音点歌。项目在 GitHub 上叫 hanxi/xiaomusic，MIT 协议，作者是涵曦。技术栈没什么花哨的，Python 加 FastAPI，前端还是 jQuery。

先说结论，免得看到最后才发现不合适：这东西能用，也确实解决了问题，但作者已经宣布停止维护，不再接受新功能和 bug 修复。所以下面除了怎么装，也会写清楚它现在的状态和几条替代路线。

它到底怎么让小爱播本地歌

小爱音箱本质上是个联网设备，它播放的音频要么来自云端曲库，要么来自一个它能访问到的 URL。XiaoMusic 做的就是后者：在局域网里起一个 HTTP 服务，把 /app/music 目录下的音频文件暴露成可播放的地址，再通过小米的接口把播放指令下发给音箱。

所以它不需要刷机，不改音箱固件，也不用拆机。代价是这套服务必须一直开着——NAS 关机、容器停了，语音点歌就失效。

Docker 部署，一行 compose 就够

项目推荐 compose 部署。国内拉 hanxi/xiaomusic 有时候慢，作者另外维护了一个镜像源，两个选一个：

services:
  xiaomusic:
    image: hanxi/xiaomusic          # 国内换成 docker.hanxi.cc/hanxi/xiaomusic
    container_name: xiaomusic
    restart: always
    ports:
      - 58090:8090
    volumes:
      - /xiaomusic_music:/app/music
      - /xiaomusic_conf:/app/conf

几个容易搞错的地方，我一开始就在这上面浪费了时间：

左边的 /xiaomusic_music 和 /xiaomusic_conf 是你主机上的实际路径，可以换成 NAS 里任意位置，比如 /volume1/docker/xiaomusic/music。右边容器里的路径不要动。端口这边的 58090 是你在浏览器里访问用的，8090 是容器内部的，也只改前面那个。

目录不存在的话容器起不来，先手工建一下：

mkdir -p /xiaomusic_music /xiaomusic_conf

起来之后浏览器打开 http://你的NAS地址:58090，就是控制台。

第一次配置：要填小米账号

控制台第一次打开是空的，设备列表也是空的。这里必须填小米账号和密码，服务要靠它去调小米的设备接口，才能拿到你账号下的音箱列表。页面上带星号的字段是必填的，其他先空着也能跑。

这一步有两个提醒。一是账号密码是存在 /app/conf 里那个配置文件中的，别把 conf 目录随手共享出去。二是作者在 README 里专门写了一句：强烈不建议用小爱音箱绑定的那个小米账号去接摄像头。代码难免有 bug，一旦凭据泄露，监控录像也会跟着暴露。这条建议我觉得很实在，不是免责声明式的套话。

保存之后设备列表会刷出来，把你的音箱勾上就行。

音乐怎么放进去，格式有什么讲究

直接把文件丢进 music 目录对应的主机路径，容器里就能看到。支持 mp3、flac、wav、ape、ogg、m4a 六种。目录结构就是你自己的歌单结构——建一个子目录叫「老歌」，语音说「播放歌单老歌」就会播这个目录里的。

这里有个实际会踩的坑：不是所有型号都吃 flac。按项目文档，L05B、L05C、LX06、L16A 这几款不支持 flac。如果你正好是这几个型号，控制台里把「转换为 MP3」和「型号兼容模式」打开，服务会转码后再推给音箱。转码要花点 CPU，但总比点了没反应强。

型号对照可以去小米 IoT 平台查，比对着音箱底部标签看快。L06A 是小爱音箱，LX06 是音箱 Pro，L16A 是 Xiaomi Sound——这几个是最常见的。

语音口令：能用的就那么几句

装完最想知道的是「我到底能对它说什么」。实测能识别的：

• 「播放歌曲」——随机播本地全部
• 「播放歌曲 周杰伦 晴天」——按歌名点播
• 「上一首」「下一首」「停止播放」
• 「单曲循环」「全部循环」「随机播放」
• 「播放歌单 老歌」——按目录名播
• 「加入收藏」「取消收藏」

口令是固定句式，不是自然语言。你说「来点音乐」它不会理你，说「播放歌曲」才行。这一点习惯之后还好，但家里人要适应一阵。

另外有个隐藏玩法写在文档里，我觉得挺有意思：对小爱说「播放歌曲 小猪佩奇的故事」，它会先把内容下载下来再播。相当于绕过了曲库限制，用语音给小孩放故事。不过这也引出下一个问题。

两个必须说清楚的限制

第一，下载功能涉及版权，自己判断。 项目用 yt-dlp 拉取音频，从哪个源拉、拉什么内容，取决于你自己。我只用本地已有的文件，没碰下载功能。要是你打算拿它当在线音乐库用，先想清楚这件事。

第二，别直接暴露到公网。 如果想让在外面也能用，必须开密码登录并设一个不短的密码。这个服务的控制台里存着你的小米账号密码，放在公网又没有认证，等于把家门钥匙挂在门上。作者也提醒了别在公共 WiFi 下用。

项目现状：已经停止维护

这是必须写在前面的部分。作者在仓库顶部挂了公告，大意是个人精力有限，要把重心转到其他项目，本项目不再接受新功能开发和 bug 修复，已有 issue 和 PR 也不再处理。

所以现在装它，要想清楚你接受的是什么：一个功能完整、能跑、但不会再有安全更新的工具。它不复杂，风险不算高，但「不会有人修」这件事本身是个长期成本。

三条替代路线，看你更在意什么：

• songloft-org/songloft：作者自己在公告里推荐的社区接力项目，思路一脉相承，适合想继续跟进的人。
• hanxi/mimusic：同作者后来写的个人音乐服务器，更简洁，插件扩展能力更强。但定位是音乐服务器，不是专门伺候小爱音箱的。
• 不折腾：如果你的核心需求只是「在客厅放自己存的歌」，买个支持 DLNA 的音箱、或者给现有音响接个蓝牙接收器，成本更低，也不用担心停维。

我的判断

如果你已经有 NAS 常年开着、本地存了一批音乐、家里又正好有台小爱音箱，那 XiaoMusic 值得装。部署十分钟，配置五分钟，日常用起来就是「说句话就放歌」，没有额外的心智负担。

如果你是专门为它去买音箱、或者指望它长期稳定维护，我觉得算了。停维的项目适合「刚好手上有这些东西」的人，不适合「围绕它搭一套方案」的人。

顺带一提，作者另外几个小工具也都是同一路数——tiny-nav 做 NAS 导航页、cups-web 把打印机接进 NAS、epub2mp3 把电子书转音频。都是那种「一个小痛点、一个能跑的工具」的风格，用得上就装，用不上也不用惦记。