企业官网建设流程全解析

1Panel 面板安装运行 XiaoMusic：应用商店部署、端口配置与反向代理全指南

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

本指南完整讲解如何在 1Panel 面板中安装、配置并运行 XiaoMusic（基于小爱音箱的无限听歌服务），覆盖应用商店安装、端口外部访问、WebUI 跳转、面板默认访问地址设置，以及反向代理场景下 Web 访问地址的修改方法。读完本文，你将能够在 1Panel 上从零部署一个可通过浏览器访问的小爱音箱音乐服务。

1Panel 安装运行概述

XiaoMusic 是一个使用小爱音箱播放音乐的开源项目，音乐使用 yt-dlp 下载（见仓库根目录 README.md 的项目描述）。它以 Docker 镜像为主要分发形式，官方 Dockerfile（见 Dockerfile）基于多架构构建，暴露 8090 端口提供 Web 服务。

1Panel 作为开源 Linux 服务器运维管理面板，提供了可视化的应用商店，用户可以在其中一键安装 XiaoMusic，无需手写 docker compose 或 docker run 命令。本文档（来源：docs/issues/600.md）将指导你完成整个流程。

前提条件

在开始安装前，请确保你已完成以下准备工作：

• 已安装并运行 1Panel 面板。

如需详细安装 1Panel 面板，请参考1Panel 官方安装文档中的在线安装章节（1Panel 提供脚本化在线安装方式）。

安装完成后，通过安装输出提示的访问地址和初始账号密码登录 1Panel。

登录后的第一件事

登录 1Panel 后建议先进入面板设置页面设置好默认访问地址。文档明确建议：在使用 XiaoMusic 的 WebUI 前，先在面板设置中完成默认访问地址的配置，这会影响后续 WebUI 跳转时生成的 URL 是否正确。

在应用商店安装 XiaoMusic

登录 1Panel 后，按照以下步骤安装：

1. 进入应用商店；
2. 搜索xiaomusic；
3. 点击安装即可。

应用商店安装本质上是在 1Panel 的容器编排体系（Docker / Docker Compose）中拉取并运行hanxi/xiaomusic官方镜像，这与仓库 README.md 提供的docker run -p 58090:8090 -v /xiaomusic_music:/app/music -v /xiaomusic_conf:/app/conf hanxi/xiaomusic命令的端口与目录映射逻辑一致。

配置参数说明

安装时请根据实际需求配置以下参数：

• 高级设置：根据实际需要勾选端口外部访问，勾选后即可通过外部 IP 访问 XiaoMusic。

保持默认配置也可以完成安装，但建议根据实际需求调整。

从仓库源码可以进一步理解这两个关键参数背后的映射关系：

• 容器内部端口固定为 8090：这是 XiaoMusic HTTP 服务实际的监听端口。xiaomusic/config.py 中port字段默认值为8090，xiaomusic/cli.py 中async_main使用该端口启动 uvicorn 服务（监听0.0.0.0与::）。因此在 1Panel 中该端口不应被随意改动。
• 外部访问端口默认 58090：这是暴露给宿主机/局域网的入口端口。源码中public_port默认值为58090，用于生成歌曲访问地址（见 xiaomusic/config.py 中get_self_netloc将hostname与public_port拼接为对外网络地址）。勾选端口外部访问相当于把 8090 映射到面板指定端口（默认 58090），外部访问地址形如http://NAS_IP:58090。

此外，安装时 1Panel 通常会要求配置存储目录挂载。结合 Dockerfile 中的卷定义：

提示：源码在启动时会检查conf_path与music_path是否相同并输出警告“配置文件目录和音乐目录建议设置为不同的目录”（见 xiaomusic/xiaomusic.py 的XiaoMusic.__init__），1Panel 安装时请将两个目录挂载到不同的主机路径。

访问 XiaoMusic WebUI

安装完成后：

1. 进入 1Panel 的已安装页面；
2. 找到 xiaomusic 应用，点击跳转即可进入 XiaoMusic 的WebUI页面。

XiaoMusic 的 WebUI 由 FastAPI 应用提供（见 xiaomusic/api/app.py），首页路由返回xiaomusic/static/index.html（见 xiaomusic/api/routers/system.py 的/路由），同时仓库还提供了多套前端主题（如static/default、static/tailwind、static/pure等）。

使用前建议在面板设置页面设置好默认访问地址，否则 1Panel 生成的跳转链接可能无法正确访问。

首次使用的必要配置

进入 WebUI 后（设置页面即setting.html，对应前端代码见 xiaomusic/static/tailwind/setting.html），根据 README.md 的说明：

• 带有*号的配置是必须要配置的，其他的用不上时不用修改；
• 初次配置时需要在页面上输入小米账号和密码保存后，才能获取到设备列表（对应后端getsetting/savesetting接口，见 xiaomusic/api/routers/system.py）；
• 在 Web 设置页面可以配置其余参数，不再需要设置环境变量。

设置保存后会写入配置目录下的setting.json（由 xiaomusic/config_manager.py 的do_saveconfig实现），修改 HTTP 相关配置（如端口、hostname、认证开关）时会通过reset_http_server热重置服务器（见 xiaomusic/api/dependencies.py）。

反向代理场景下的访问地址配置

如果后续配置了反向代理（例如用 Nginx、Caddy 或 1Panel 自带的反向代理功能将域名转发到 XiaoMusic），可以在已安装 → 参数页面修改Web 访问地址。

该操作本质上修改的是配置中的hostname与public_port字段：

• hostname：默认值为http://192.168.2.5（见 xiaomusic/config.py），用于拼接生成歌曲的对外播放地址。源码__post_init__会自动为未带协议前缀的 hostname 补上http://。
• public_port：默认值为58090，与 hostname 拼接后通过get_self_netloc生成网络地址。

通过反向代理对外提供服务时，需要将 Web 访问地址调整为代理后的公网地址（例如http://music.example.com:58090或https://music.example.com），否则小爱音箱或浏览器拿到的歌曲 URL 将指向内网地址，导致无法播放。修改后配置会被持久化保存，相关实现见 xiaomusic/api/routers/system.py 的modifiysetting接口（其中会检测disable_httpauth、httpauth_username、httpauth_password、port、hostname等 HTTP 相关字段，并调用reset_http_server热更新）。

安全注意事项

无论通过 1Panel 还是命令行部署，XiaoMusic 官方在 README.md 中都给出了明确的安全提醒，1Panel 用户同样适用：

1. 如果配置了公网访问xiaomusic，请一定要开启密码登录，并设置复杂的密码；不要在公共场所的 WiFi 环境下使用，否则可能造成小米账号密码泄露。
2. 强烈不建议将小爱音箱的小米账号绑定摄像头，代码难免存在 bug，一旦小米账号密码泄露，可能监控录像也会泄露。

在 XiaoMusic 的 Web 设置中，disable_httpauth（默认true）、httpauth_username、httpauth_password三个参数控制 HTTP 基础认证。当disable_httpauth为false且设置了用户名密码后，访问 API 与静态资源都会要求 Basic Auth 认证（认证逻辑见 xiaomusic/api/dependencies.py 中的verification依赖与AuthStaticFiles静态文件类）。公网暴露前请务必完成此项配置。

常见问题排查

• 无法访问 WebUI：检查 1Panel 是否勾选了端口外部访问，并确认防火墙放行了对应外部端口（默认 58090）。
• 歌曲无法播放：确认 Web 设置中的访问地址（hostname + 端口）与实际访问地址一致，特别是在配置反向代理之后。
• 日志查看：Web 设置页面底部提供【下载日志文件】按钮，可下载日志（xiaomusic.log.txt）用于排查问题；反馈问题时请先确认日志中不含账号密码等敏感信息。
• 配置与音乐目录分离：确认音乐目录与配置目录挂载到了不同主机路径，避免源码启动时的目录混用告警。

总结

通过 1Panel 应用商店安装 XiaoMusic 是个人 NAS / 服务器部署该服务最便捷的方式：一键安装、可视化参数配置、WebUI 跳转。本文结合仓库源码梳理了安装过程中的关键参数（端口 8090/58090、/app/music与/app/conf卷映射）、首次使用的账号配置流程，以及反向代理场景下 Web 访问地址的调整原理，帮助你顺利完成从安装到稳定运行的全过程。

延伸阅读

• 项目总体安装方式与功能特性：README.md
• Docker 镜像构建细节（端口、卷、环境变量）：Dockerfile
• 配置参数完整清单（默认值、环境变量）：config-example.json、xiaomusic/config.py
• 启动入口与命令行参数（--port、--config等）：xiaomusic/cli.py
• Web 设置相关接口实现：xiaomusic/api/routers/system.py

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