xiaomusic 使用 Docker Compose 命令行安装完整指南：从创建 docker-compose.yml 到日常运维

xiaomusic 使用 Docker Compose 命令行安装完整指南：从创建 docker-compose.yml 到日常运维

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

本指南面向已经具备命令行环境、且已安装 Docker Compose 的读者，以 docs/issues/360.md 中的部署教程为主体，完整讲解 xiaomusic（基于小爱音箱 + yt-dlp 的本地音乐播放服务）的 compose 编排、启动、后台设置、镜像更新与关闭等全部实操步骤，并结合仓库内 Dockerfile、config-example.json 与核心源码，补充路径、端口、用户权限、切歌延迟等关键细节。读完本文，你将能够仅靠复制粘贴命令，在 NAS 或 Linux 主机上 10 分钟内跑通 xiaomusic，并掌握常见的排障与调优手段。

前置条件与整体思路

本教程的核心前提非常简单：

• 拥有可以执行命令的终端环境（SSH 到 NAS 或 Linux 主机）；
• 已经安装好 Docker 与 Docker Compose 插件（docker compose子命令可用）；
• 后续所有配置都通过docker-compose.yml文件完成，步骤以“复制粘贴即可运行”为设计目标。

由于 xiaomusic 支持在 Web 设置页面配置绝大多数参数（见 README.md 的说明），compose 文件只需要承担最基础的四件事：拉取镜像、映射端口、挂载目录、注入必要环境变量。如果需要修改路径或端口，把命令复制到编辑器里改好后再粘贴执行即可，但编辑时务必注意不要破坏文件格式与缩进（YAML 对缩进敏感）。

创建 docker-compose.yml 文件

假设docker-compose.yml存放在宿主机的/xiaomusic/docker-compose.yml。执行下面整段命令即可一次性创建目录并写入编排文件：

mkdir -p /xiaomusic cat <<EOF > /xiaomusic/docker-compose.yml services: xiaomusic: image: docker.hanxi.cc/hanxi/xiaomusic container_name: xiaomusic restart: unless-stopped ports: - 58090:8090 environment: XIAOMUSIC_PUBLIC_PORT: 58090 volumes: - /xiaomusic_conf:/app/conf - /xiaomusic_music:/app/music EOF

各配置项的实操说明

• image: docker.hanxi.cc/hanxi/xiaomusic：国内可用的镜像地址。海外/直连环境下也可替换为hanxi/xiaomusic或hanxi/xiaomusic:main（测试版），README 中三种镜像写法见 README.md。
• container_name: xiaomusic：固定容器名，方便后续用docker compose统一管理，无需额外指定。
• restart: unless-stopped：容器异常退出时自动重启，适合常驻运行的 NAS 场景。
• ports: - 58090:8090：把容器内 8090 端口映射到宿主机 58090 端口。
• environment: XIAOMUSIC_PUBLIC_PORT: 58090：注入“歌曲访问端口”环境变量。这一点非常关键：xiaomusic 在生成对外可访问的歌曲 URL 时，会使用该端口拼接地址，见 config.py 中public_port: int = int(os.getenv("XIAOMUSIC_PUBLIC_PORT", 58090))的定义，以及 music_library.py、online_music.py 中基于hostname:public_port构造代理地址的实现。
• volumes：/xiaomusic_conf:/app/conf与/xiaomusic_music:/app/music分别对应容器内的配置目录与音乐目录。Dockerfile 中也显式声明了VOLUME /app/conf与VOLUME /app/music（见 Dockerfile），因此这两个挂载点是固定约定。

关于路径与端口必须记住的规则

1. /xiaomusic_conf是配置文件存放目录，一般不需要修改：xiaomusic 运行时会把账号、口令、播放设置等写入该目录，conf_path的默认值就是conf（见 config-example.json）。
2. /xiaomusic_music是音乐存放目录，可以替换：想改的话填绝对路径——Linux 下以/开头（如/data/music），Windows 下以盘符开头（如D:/music）。
3. 容器内端口 8090 不要修改：它是 Web 服务在容器内的监听端口，port的默认值即8090（config.py），Dockerfile 亦以EXPOSE 8090声明（Dockerfile）。
4. 宿主机端口 58090 可以修改：如果修改，ports与XIAOMUSIC_PUBLIC_PORT两个 58090 必须同时改，否则外部访问端口与 xiaomusic 内部生成的歌曲 URL 端口不一致，会导致音乐无法播放。该端口是访问 Web 后台的端口。

补充：如果宿主机目录不存在导致挂载报错，可以先执行mkdir -p /xiaomusic_music /xiaomusic_conf创建目录（README 中对 Docker 场景同样有此提示，见 README.md）。

启动服务

编排文件就绪后，进入目录并后台拉起服务：

cd /xiaomusic docker compose up -d

启动完成后，即可通过浏览器访问 Web 后台：

http://nasip:58090

把nasip替换为你 NAS 的实际 IP（如http://192.168.1.100:58090）。首次启动时镜像会自动拉取，之后每次up -d都会复用本地已有的镜像层，速度很快。

后台设置：绑定小爱音箱的关键步骤

容器起来后，打开http://nasip:58090进入设置页面，按以下顺序操作：

1. 填写账号密码（小米账号与密码），并点击“自动填 IP 和端口”让页面帮你补全主机地址与外网访问端口；
2. 滚动到页面最下方，点击保存按钮；
3. 刷新设置页面；
4. 勾选小爱音箱设备，再次保存。

需要说明的是：这两个设置页截图位于原 Issue 文档中（远端附件），本仓库内并不包含这两张图片，因此不在此处插入图片。逻辑上，第二次保存是为了把“已发现的小爱音箱设备列表”绑定到账号下。README 也指出：初次配置时需要在页面上输入小米账号和密码保存后，才能获取到设备列表（见 README.md）。多设备场景下，mi_did支持以逗号分隔的多个设备 ID（见 config.py）。

配置保存后，音乐目录、口令（关键词）映射、delay_sec切歌延迟等参数都可以继续在设置页面调整，无需再改环境变量。完整的默认参数集合见 config-example.json，可作为排障时的对照基准。

更新镜像

xiaomusic 迭代较快，更新镜像只需两条命令（注意/xiaomusic是docker-compose.yml所在目录）：

cd /xiaomusic docker compose pull docker compose up -d

docker compose pull会拉取 compose 文件中image指定的最新镜像，随后的up -d会基于新镜像重建容器。如果想使用最新开发版，把image换成hanxi/xiaomusic:main即可（见 README.md）。

关闭服务

cd /xiaomusic docker compose down

该命令会停止并移除由 compose 创建的容器与默认网络，但不会删除挂载卷中的配置与音乐数据，因此重启用up -d即可无缝恢复。若需要同时清理数据卷，可自行执行docker compose down -v（注意：这会删除挂载卷数据，请谨慎使用）。

进阶实战：评论区常见问题与源码级解答

原 Issue 评论区沉淀了真实用户遇到的三个典型问题，结合仓库源码可以给出更完整的说明。

1. QNAP 等 NAS 上文件归属 root 导致无法删除（user 指令）

评论 1（tiger326）反馈：QNAP NAS 已禁用默认 admin 账户，而容器默认以 root 执行，导致 tmp、download 目录及下载文件都归属于 root，自建管理员账户无法删除编辑。作者 hanxi 给出的方案是在 compose 中添加user指令指定普通用户：

mkdir -p /xiaomusic cat <<EOF > /xiaomusic/docker-compose.yml services: xiaomusic: image: docker.hanxi.cc/hanxi/xiaomusic container_name: xiaomusic restart: unless-stopped user: username ports: - 58090:8090 environment: XIAOMUSIC_PUBLIC_PORT: 58090 volumes: - /xiaomusic_conf:/app/conf - /xiaomusic_music:/app/music EOF

其中username换成普通用户名即可；也可以直接写 UID 数字，一般 NAS 上首个普通用户是1000。原理上，user会让容器内进程以该用户身份运行，写入的音乐文件因此归属于该用户，宿主机上同名（或同 UID）用户即可正常删除与编辑。这是 Docker 官方 compose 的user字段语义，与 xiaomusic 镜像本身无关。

2. 切歌时下一首的开头被播一小段（delay_sec 与负数延迟）

评论 3-8（worrywast 与 hanxi）讨论：一首歌播完后，会先播下一首的开头一点点才切歌。作者解释这是“正常现象”，并建议把延迟设为 0；随后进一步优化为“允许设置成负数”。

从源码看，这个现象与切歌定时器的计算逻辑直接相关。在 device_player.py 中：

# 计算获取时长的执行耗时 duration_execution_time = time.time() - self._start_time # 调整定时器时长，减去获取音乐时长的执行时间 adjusted_sec = sec + self.config.delay_sec - duration_execution_time # 确保调整后的时长不会过小，最小保留0.1秒 adjusted_sec = max(adjusted_sec, 0.1) await self.set_next_music_timeout(adjusted_sec)

也就是说，定时器实际等待时长 = 歌曲时长 +delay_sec− 获取时长本身的执行耗时。由于“获取时长”这一步有耗时，定时器会比理想情况晚触发，表现为上一首播完后多播了一点下一首的开头；把delay_sec设为 0 甚至负数，可以补偿这部分误差。当前版本的delay_sec定义如下（config.py）：

delay_sec: int = int(os.getenv("XIAOMUSIC_DELAY_SEC", 0)) # 下一首歌延迟播放秒数

即该参数现在可以直接填写负数，对应 Web 设置页面的“下一首歌延迟播放秒数(支持负数)”选项（见 setting.html）。默认值为 0（config-example.json），若仍有轻微“多播开头”的现象，可尝试改为 -1 或 -2 微调。

3. “暂不支持下载本地 音乐”与本地歌曲口令点播问题

评论 9-10（jkjoy、pjlpl）反馈：本地音乐被提示“暂不支持下载本地 音乐”，以及口令点播本地歌曲时总提示不存在、但“播放本地歌曲”口令可随机播放。这两条在仓库中没有对应实现层面的修复记录，属于用户环境差异（如enable_cmd_del_music等开关、playlocal口令匹配方式）导致的现象，官方在 Issue 中未继续回复。遇到此类问题时，建议优先检查 Web 设置页面中的音乐目录路径、keywords_playlocal关键词配置（默认“播放本地歌曲,本地播放歌曲”，见 config-example.json），并确认镜像已更新到最新版本。对于无法从仓库确认的细节，本文不做臆测。

常见排障速查

总结

本教程覆盖了 xiaomusic 基于 Docker Compose 的完整生命周期：创建docker-compose.yml、启动、Web 后台绑定小爱音箱、更新镜像与关闭服务。核心要点可归纳为四条规则：容器内 8090 端口不动、宿主机 58090 端口可改但两处需同步、/app/conf与/app/music两个挂载点固定、其余参数一律在 Web 设置页配置。配合评论区沉淀的user指令、负数切歌延迟等实战经验，绝大多数 NAS 用户都能快速、稳定地跑通这套方案。进一步深入时，可对照 Dockerfile、config-example.json、config.py 与 device_player.py 阅读源码，理解镜像构建与切歌调度等底层实现。

<输出文章>

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