解放你的音乐库：让小爱音箱畅播 NAS 上的海量音乐

你是否也曾遇到这样的烦恼：斥巨资购买了心爱的高品质无损音乐，整齐地收藏在 NAS 里，却只能在电脑或手机上欣赏？客厅里聪明的小爱音箱，能点播全网曲库，却唯独对你触手可及的本地音乐“视而不见”。

今天，我们将彻底打破这堵“墙”！本文将为你献上一份终极指南，手把手教你如何通过部署 xiaomusic 这个开源神器，将你的 NAS 变身为小爱音箱的私人云端曲库，实现语音点播本地音乐的自由。

魔法揭秘：xiaomusic 的工作原理

要让小爱播放你的音乐，首先要理解它俩为何“语言不通”。

小爱音箱播放音乐的流程是这样的：

  1. 你发出语音指令，如“播放周杰伦的歌”。
  2. 音箱将语音上传到小米的云端 AI 进行识别。
  3. 云端 AI 理解指令后，会向其合作的音乐服务商（如 QQ 音乐、网易云音乐）请求歌曲资源。
  4. 音乐服务商返回一个可播放的 URL 地址。
  5. 小爱音箱接收到这个 URL，然后从该地址拉取音频流进行播放。

关键在于，小爱音箱不具备直接访问你家局域网内 NAS 的能力。它需要一个公网可以访问的 URL。

xiaomusic 扮演的角色正是一个“翻译官”和“中间人”。它的工作流程如下：

  1. 模拟音乐服务商：xiaomusic 会利用你的小米账号信息，将自己注册为你账号下的一个“私人音乐源”。
  2. 监听指令：当你在小爱音箱上激活了“播放本地音乐”的类似技能后，小米云端会将播放请求转发给 xiaomusic 服务。
  3. 扫描与索引：xiaomusic 会持续扫描你 NAS 上指定的音乐文件夹，建立一个完整的歌曲索引数据库。
  4. 生成公网 URL：当收到播放请求（如“播放稻香”），xiaomusic 会在自己的数据库中找到对应的音乐文件，并生成一个指向你 NAS 的公网 URL。
  5. 返回 URL：xiaomusic 将这个 URL 返回给小米云端，小米云端再将其下发给你的小爱音箱。
  6. 开始播放：小爱音箱拿到这个 URL 后，直接从你的 NAS 上下载并播放音乐。大功告成！

xiaomusic_workflow
(图片来源: xiaomusic 项目仓库)

因此，一个能从公网访问到你 NAS 的方式是部署本服务的最核心前提。

适用场景与优势

  • 珍藏爱好者：让你的高品质 FLAC、WAV、APE 无损音乐重见天日，享受极致音质。
  • 音乐库整理者：精心整理的专辑、艺术家和播放列表，现在可以通过语音轻松调用。
  • 订阅费用节省者：无需为已拥有的音乐向流媒体平台支付额外费用。
  • 隐私保护者：音乐播放列表和听歌习惯完全留存在你自己的服务器上。
  • DIY 极客：享受打通智能家居生态、实现个性化功能的乐趣。

部署前的准备 (Prerequisites)

在开始之前，请确保你已具备以下条件：

  1. 一台持续运行的设备：NAS (群晖/威联通)、VPS、树莓派或任何可以运行 Docker 的 Linux 服务器。
  2. Docker 环境：安装好 Docker 和 Docker Compose。
  3. 公网访问能力 (最重要！)：
    • 拥有公网 IP，并在路由器上设置好端口转发。
    • 或者，使用 DDNS (动态域名解析)。
    • 或者，使用内网穿透服务 (如 FRP, NPS, ZeroTier)。
  4. 音乐文件：在 NAS 上有一个存放音乐文件的目录。
  5. 小米账号和一台小爱音箱。

终极部署指南 (使用 Docker Compose)

我们将使用 Docker Compose 来部署，这是最简单、最可控、最易于维护的方式。

第一步：创建项目目录

通过 SSH 登录到你的 NAS 或服务器，创建一个专门用于 xiaomusic 的文件夹，并进入该目录。

1
2
mkdir xiaomusic
cd xiaomusic

第二步：创建 docker-compose.yml 文件

在该目录下，创建一个 docker-compose.yml 文件。

1
touch docker-compose.yml

然后，使用文本编辑器 (如 vim 或 nano) 打开它，并粘贴以下内容。请务必根据注释修改为你自己的配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
version: '3.8'
services:
  xiaomusic:
    image: yihong0618/xiaomusic:latest
    container_name: xiaomusic
    restart: unless-stopped
    ports:
      # 将容器的 8090 端口映射到主机的 8090 端口。
      # 如果 8090 端口被占用，可以修改前面的数字，例如 '8899:8090'
      - "8090:8090"
    volumes:
      # 关键：将你的音乐文件夹映射到容器的 /music 目录
      # !!! 请将下面的 `/path/to/your/music` 修改为你的真实音乐库路径 !!!
      - /path/to/your/music:/music

      # 将配置文件目录映射到当前目录下的 config 文件夹，用于持久化存储
      - ./config:/config
    environment:
      # 关键：设置你的服务公网访问地址
      # !!! 必须修改为你的公网 IP/域名 和 映射的端口 !!!
      - XIAOMUSIC_URL=http://your-public-ip-or-domain:8090

      # (可选) 设置 Web UI 的登录用户名和密码
      - XIAOMUSIC_USERNAME=admin
      - XIAOMUSIC_PASSWORD=your_strong_password

      # 设置时区
      - TZ=Asia/Shanghai

配置说明：

  • image: 我们使用 yihong0618/xiaomusic 这个广受欢迎且持续更新的镜像。
  • ports: 确保你映射出的主机端口（冒号前的数字）已经在你的路由器防火墙上放行。
  • volumes: 这是整个配置的核心。第一个 volume 必须正确指向你存放音乐的文件夹。第二个 volume 用于保存 xiaomusic 的配置文件，确保重启后配置不丢失。
  • environment.XIAOMUSIC_URL: 至关重要！ 这里必须填写小爱音箱能够从公网访问到你这个服务的地址。如果填错，音箱将无法获取到播放链接。

第三步：启动服务并完成配置

  1. 启动容器
    在 docker-compose.yml 文件所在的目录中，运行以下命令：

    1
    docker-compose up -d

  2. 登录 Web UI
    服务启动后，在浏览器中访问 http://<你的NAS局域网IP>:8090。使用你在 docker-compose.yml 中设置的用户名和密码登录。

  3. 填写小米账号信息
    登录后，点击页面上的“设置”或类似选项。你需要填写以下信息：

    • 小米账号 (MI_USER): 你的小米账号（通常是邮箱或手机号）。
    • 小米密码 (MI_PASS): 你的小米账号密码。

  4. 选择音箱设备
    填写完账号信息并保存后，服务会自动尝试登录并获取你账号下的智能设备列表。在设备列表 (MI_DID) 中，准确选择你想要用来播放音乐的那台小爱音箱。

  5. 保存并同步
    保存所有配置。然后回到主页，点击“同步”或“扫描音乐库”按钮。服务会开始遍历你在 volumes 中映射的 /music 文件夹，这个过程可能需要一些时间，取决于你的音乐文件数量。

第四步：开始享受音乐！

当音乐库扫描完成后，你就可以对你的小爱音箱说出魔法指令了：

“小爱同学，使用‘自定义’播放周杰伦的歌”

“小爱同学，让‘自定义’播放我的收藏”

这里的唤醒词“自定义”可能需要你在米家 App 中进行设置，具体可以参考 xiaomusic 项目的最新文档，通常是在米家 App -> 我的 -> 其他平台设备 -> 添加 xiaomusic 提供的平台，并设置一个唤醒名称。

疑难解答 (Troubleshooting)

  • 说指令后没反应？
    • 检查 docker logs xiaomusic，看是否有报错信息。
    • 确认 XIAOMUSIC_URL 是否配置正确且公网可访问。可以在手机上用移动网络访问该 URL 试试。
    • 确认路由器端口转发是否正确设置。
  • 找不到音乐？
    • 确认音乐库路径是否正确映射到容器的 /music 目录。
    • 尝试在 Web UI 中手动重新扫描音乐库。
    • 确保音乐文件名和标签 (metadata) 干净、规范，便于识别。

总结

通过 xiaomusic，我们成功地将 NAS 这个数据孤岛与小爱音箱这个智能中枢连接了起来，不仅盘活了我们珍藏的数字音乐资产，更带来了无与伦比的便捷体验和 DIY 成就感。现在，就让悠扬的旋律从你的 NAS 流淌而出，响彻家中的每一个角落吧！