终极Xiaomusic安装部署指南：3种方式快速搭建小爱音乐播放系统

Xiaomusic是一款基于Python开发的智能音乐播放系统，通过yt-dlp工具实现音乐资源下载，让你的小爱同学变身专业音乐播放器。本指南将通过Docker容器化部署、Python源码安装两种主流方式，带你零基础快速搭建属于自己的音乐播放平台，支持多设备管理、播放列表创建和智能音乐下载等核心功能。

项目核心功能概述 🎵

Xiaomusic作为开源音乐播放解决方案，主要特点包括：

• 智能音乐下载：集成yt-dlp工具，支持多平台音乐资源获取
• 多设备管理：可同时连接多个小爱音箱设备并切换控制
• 播放控制中心：提供播放/暂停、上/下一首、音量调节等基础功能
• 播放模式切换：支持随机播放、单曲循环、全部循环等模式
• 音乐库管理：分类展示本地音乐和网络音乐，支持收藏功能

环境准备与系统要求

基础环境要求

• 操作系统：Windows 10/11、Linux (Ubuntu 18.04+)、macOS 10.15+
• Python环境：Python 3.7及以上版本
• 网络要求：稳定的互联网连接（用于音乐下载）
• 硬件要求：至少1GB RAM，10GB可用存储空间

必备依赖工具

• Docker（可选，用于容器化部署）
• Git（用于源码克隆）
• pip（Python包管理工具）

Docker容器化部署：3步快速启动

适用场景

适合追求简单快捷部署的用户，无需配置复杂的Python环境，尤其适合Linux服务器和新手用户。

步骤1：拉取官方镜像

docker pull xiaomusic:latest

步骤2：启动容器服务

docker run -d -p 5000:5000 --name xiaomusic xiaomusic:latest

⚠️ 注意：如果5000端口已被占用，可修改端口映射如-p 8080:5000

步骤3：访问Web界面

打开浏览器访问 http://localhost:5000 即可进入控制界面

Python源码安装：灵活定制部署

适用场景

适合需要自定义配置、开发扩展功能或贡献代码的高级用户，支持Windows/macOS/Linux全平台。

步骤1：克隆项目源码

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

步骤2：安装依赖包

pip install -r requirements.txt

步骤3：启动应用服务

python xiaomusic.py

基础配置指南：5分钟完成初始化

配置文件设置

1. 复制配置模板创建配置文件：

cp config-example.json config.json

2. 关键参数配置对比：

参数名称	描述	默认值	推荐配置
music_path	音乐存储路径	./music	/home/user/Music
port	Web服务端口	5000	根据需要修改
device_name	默认设备名称	小爱音箱	实际设备名称
download_quality	音乐下载质量	medium	high (高质量)

设备连接设置

1. 在Web界面点击"设备控制"
2. 选择可用的小爱设备并连接
3. 测试播放功能确保连接正常

快速使用示例：3个实用操作

1. 搜索并播放音乐

1. 在Web界面顶部搜索框输入歌曲名
2. 点击搜索结果中的播放按钮
3. 系统将自动下载并播放音乐

2. 创建个人播放列表

1. 勾选多首歌曲
2. 点击"添加到播放列表"
3. 输入列表名称并保存

3. 切换播放设备

1. 点击界面右上角设备选择下拉框
2. 选择已连接的其他小爱设备
3. 音乐将自动切换到所选设备播放

常见问题解决与注意事项

端口冲突问题

当提示"Address already in use"时，修改配置文件中的port参数或使用Docker端口映射功能。

设备连接失败

• 确保小爱设备与服务器在同一局域网
• 检查网络防火墙设置，开放5000端口
• 重启小爱设备后重新尝试连接

音乐下载失败

• 检查网络连接是否正常
• 确认yt-dlp已正确安装
• 尝试更换音乐源或降低下载质量

高级功能：插件系统扩展

Xiaomusic支持通过插件扩展功能，现有插件包括：

• HTTP请求插件：plugins/httpget.py
• 网络请求插件：plugins/httppost.py

安装插件只需将插件文件放入plugins目录，然后在Web界面的"插件管理"中启用即可。

总结

通过本文介绍的Docker或Python源码两种部署方式，你已掌握Xiaomusic的完整安装流程。无论是追求简单快捷的容器化部署，还是需要灵活定制的源码安装，都能让你快速构建智能音乐播放系统。利用其强大的音乐下载能力和多设备管理功能，让你的小爱音箱发挥更大价值。

后续可探索定时任务配置、自定义音乐源等高级功能，进一步提升音乐播放体验。如有问题，可查阅项目文档或提交issue获取帮助。