企业官网建设流程全解析

xiaomusic 完整指南：3 条命令部署免费的小爱音箱音乐服务器

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

xiaomusic 是一个 Python 开源音乐服务器：部署后，小爱音箱可以直接播你 NAS 里的本地音乐，也能在线搜歌（用 yt-dlp 下载）再播，语音口令还能自己改词。装完之后，音箱的曲库从"平台给什么听什么"变成"你的曲库你说了算"。

为什么值得装 xiaomusic

场景一：NAS 上的无损音乐吃灰。你攒了几年的 FLAC/WAV 文件躺在 NAS 里，而音箱内置音源只认自家平台的曲库，想听自己的文件要么再买一个会员，要么就听个响。xiaomusic 直接指向你的音乐目录，格式覆盖 MP3/FLAC/WAV/APE/OGG/M4A 六种，无损文件也能出声。

场景二：想听的歌，平台搜不到。对音箱说歌名，内置曲库回复"未找到"。xiaomusic 接了 yt-dlp：说"播放歌曲+歌名"，它先在线找到、下载、再播放，歌还会存进本地下载目录，下次直接秒播。

xiaomusic 部署准备步骤

先建好两个挂载目录（用绝对路径）：

mkdir -p /xiaomusic_music /xiaomusic_conf

说明：/xiaomusic_music放音乐，/xiaomusic_conf放配置，分开管理、方便备份。

踩坑提示：这两个目录不存在时容器会启动报错，务必先建。NAS 上有@eaDir之类系统目录的话，后面可以在设置里用exclude_dirs排除，避免被扫进曲库。

如果打算跑源码做开发调试（普通用户不用）：

git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic

说明：拉取源码，依赖可用仓库里的 install_dependencies.sh 安装（负责下载 ffmpeg 等），再装 Python 依赖启动。新手直接走 Docker 更省事。

xiaomusic Docker 部署命令

一条命令完成拉镜像和启动：

docker run -p 58090:8090 -v /xiaomusic_music:/app/music -v /xiaomusic_conf:/app/conf hanxi/xiaomusic

说明：58090是宿主机端口（你在浏览器访问的号码），8090是容器内部端口；两个-v分别挂音乐和配置目录。

国内网络拉镜像慢的话，换成国内加速地址：

docker run -p 58090:8090 -v /xiaomusic_music:/app/music -v /xiaomusic_conf:/app/conf docker.hanxi.cc/hanxi/xiaomusic

踩坑提示：端口冲突只改冒号左边的58090，右边的8090和容器内路径/app/music、/app/conf都不要动——官方 FAQ 里就有人只改映射端口导致播放失效。

xiaomusic 首次验证：从登录到播第一首歌

1. 浏览器打开http://<服务器IP>:58090（IP 换成跑 Docker 那台机器的地址）。
2. 在账号设置里填入小米账号密码并保存，保存成功后设备列表就会出现。
3. 在"小爱设备控制"里勾选你要控制的音箱。
4. 对着音箱说一句"播放歌曲"，本地库里的歌就该响起来了。

语音验证清单（全部通过才算装好）：

• "播放歌曲晴天" → 开始播放（本地没有会在线搜并下载）
• "下一首" / "上一首" → 切歌正常
• "随机播放" → 切换到随机模式
• "加入收藏" → 页面上"收藏"分类里能看到这首歌

踩坑提示：设备列表空白（Login Failed）多半是账号状态问题。按顺序试：关掉代理 → 米家 App 退出重登 → 在小米官网登录一次完成滑块验证，基本能解决。

上手后 xiaomusic 能做什么

使用前/使用后对比：

高频语音口令一览（触发词都能在配置里改，见 配置示例 中的key_word_dict）：

两个容易忽略的好用点：

1. 自定义口令：任意短语都能映射到内置命令或自定义插件，比如把"播放健身歌单"绑到指定歌单，插件代码在 plugins/ 目录。
2. 网络歌单/电台：把 m3u8 链接或电台做成 JSON 歌单配置进去，睡前电台这种场景直接语音点播。

页面上方可以按"全部/所有歌曲/收藏/下载"分类浏览，右上角随时切换设备。

xiaomusic 常见问题与避坑

1. Login Failed，看不到设备列表：账号状态问题。关代理 → 米家 App 重登 → 小米官网登录做滑块验证，按这个顺序来。
2. 提示找不到 /xiaomusic_music 目录：先mkdir -p建好两个挂载目录，再启动容器。
3. FLAC 播放不了或有杂音：L05B、L05C、LX06、L16A 这几个型号不支持 FLAC，在设置里打开"转换为MP3"和"型号兼容模式"即可。
4. 在线歌下载失败：下载依赖 yt-dlp + ffmpeg（Docker 镜像已内置），先查网络；个别站点需要 cookie，可在设置里开启对应开关。
5. 用着用着设备"消失"：语音口令开关长期开启会高频轮询对话记录，不用口令时关掉它，避免设备频繁掉线。

另外提醒一句：作者在 README 顶部已公告项目后续维护安排，部署前看一眼首页通知，了解社区接力的最新情况即可，现有功能稳定可用。遇到问题优先查 FAQ 问题集合。

下一步行动清单

1. 今晚就装：在 NAS 上执行那条docker run，5 分钟内打开面板、存好小米账号。
2. 灌入曲库：把 MP3/FLAC 目录丢进/xiaomusic_music，扫描完成后语音即可点播。
3. 定一个专属口令：往词条表里加一句"播放健身歌单"，明天回家开口就能听。

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