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因此这两个挂载点是固定约定。关于路径与端口必须记住的规则/xiaomusic_conf是配置文件存放目录一般不需要修改xiaomusic 运行时会把账号、口令、播放设置等写入该目录conf_path的默认值就是conf见 config-example.json。/xiaomusic_music是音乐存放目录可以替换想改的话填绝对路径——Linux 下以/开头如/data/musicWindows 下以盘符开头如D:/music。容器内端口 8090 不要修改它是 Web 服务在容器内的监听端口port的默认值即8090config.pyDockerfile 亦以EXPOSE 8090声明Dockerfile。宿主机端口 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进入设置页面按以下顺序操作填写账号密码小米账号与密码并点击“自动填 IP 和端口”让页面帮你补全主机地址与外网访问端口滚动到页面最下方点击保存按钮刷新设置页面勾选小爱音箱设备再次保存。需要说明的是这两个设置页截图位于原 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 -ddocker 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 指令评论 1tiger326反馈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-8worrywast 与 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.pydelay_sec: int int(os.getenv(XIAOMUSIC_DELAY_SEC, 0)) # 下一首歌延迟播放秒数即该参数现在可以直接填写负数对应 Web 设置页面的“下一首歌延迟播放秒数(支持负数)”选项见 setting.html。默认值为 0config-example.json若仍有轻微“多播开头”的现象可尝试改为 -1 或 -2 微调。3. “暂不支持下载本地 音乐”与本地歌曲口令点播问题评论 9-10jkjoy、pjlpl反馈本地音乐被提示“暂不支持下载本地 音乐”以及口令点播本地歌曲时总提示不存在、但“播放本地歌曲”口令可随机播放。这两条在仓库中没有对应实现层面的修复记录属于用户环境差异如enable_cmd_del_music等开关、playlocal口令匹配方式导致的现象官方在 Issue 中未继续回复。遇到此类问题时建议优先检查 Web 设置页面中的音乐目录路径、keywords_playlocal关键词配置默认“播放本地歌曲,本地播放歌曲”见 config-example.json并确认镜像已更新到最新版本。对于无法从仓库确认的细节本文不做臆测。常见排障速查现象排查方向访问http://nasip:58090打不开确认容器已启动docker compose ps、宿主机防火墙放行 58090、nasip是否正确音乐无法播放URL 端口不对检查ports与XIAOMUSIC_PUBLIC_PORT是否同步修改挂载目录报错提前mkdir -p创建宿主机目录见 README.md下载的文件无法删除添加user: 用户名或UID见上文评论区解法切歌时多播开头将“下一首歌延迟播放秒数”设为 0 或负数device_player.py登录后获取不到设备列表确认已保存账号密码并刷新页面重新勾选小爱音箱后再次保存总结本教程覆盖了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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因此这两个挂载点是固定约定。关于路径与端口必须记住的规则/xiaomusic_conf是配置文件存放目录一般不需要修改xiaomusic 运行时会把账号、口令、播放设置等写入该目录conf_path的默认值就是conf见 config-example.json。/xiaomusic_music是音乐存放目录可以替换想改的话填绝对路径——Linux 下以/开头如/data/musicWindows 下以盘符开头如D:/music。容器内端口 8090 不要修改它是 Web 服务在容器内的监听端口port的默认值即8090config.pyDockerfile 亦以EXPOSE 8090声明Dockerfile。宿主机端口 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进入设置页面按以下顺序操作填写账号密码小米账号与密码并点击“自动填 IP 和端口”让页面帮你补全主机地址与外网访问端口滚动到页面最下方点击保存按钮刷新设置页面勾选小爱音箱设备再次保存。需要说明的是这两个设置页截图位于原 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 -ddocker 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 指令评论 1tiger326反馈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-8worrywast 与 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.pydelay_sec: int int(os.getenv(XIAOMUSIC_DELAY_SEC, 0)) # 下一首歌延迟播放秒数即该参数现在可以直接填写负数对应 Web 设置页面的“下一首歌延迟播放秒数(支持负数)”选项见 setting.html。默认值为 0config-example.json若仍有轻微“多播开头”的现象可尝试改为 -1 或 -2 微调。3. “暂不支持下载本地 音乐”与本地歌曲口令点播问题评论 9-10jkjoy、pjlpl反馈本地音乐被提示“暂不支持下载本地 音乐”以及口令点播本地歌曲时总提示不存在、但“播放本地歌曲”口令可随机播放。这两条在仓库中没有对应实现层面的修复记录属于用户环境差异如enable_cmd_del_music等开关、playlocal口令匹配方式导致的现象官方在 Issue 中未继续回复。遇到此类问题时建议优先检查 Web 设置页面中的音乐目录路径、keywords_playlocal关键词配置默认“播放本地歌曲,本地播放歌曲”见 config-example.json并确认镜像已更新到最新版本。对于无法从仓库确认的细节本文不做臆测。常见排障速查现象排查方向访问http://nasip:58090打不开确认容器已启动docker compose ps、宿主机防火墙放行 58090、nasip是否正确音乐无法播放URL 端口不对检查ports与XIAOMUSIC_PUBLIC_PORT是否同步修改挂载目录报错提前mkdir -p创建宿主机目录见 README.md下载的文件无法删除添加user: 用户名或UID见上文评论区解法切歌时多播开头将“下一首歌延迟播放秒数”设为 0 或负数device_player.py登录后获取不到设备列表确认已保存账号密码并刷新页面重新勾选小爱音箱后再次保存总结本教程覆盖了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考