BoleServer 是 shellsec 维护的 LX 音源服务版本，基于 XCQ0607/lxserver，保留 LX Music 客户端和音源脚本兼容性。原项目版权和 Apache-2.0 许可继续保留。

新增：LX 音源订阅与自动切换。Docker 镜像由本仓库自动构建，使用 ghcr.io/shellsec/boleserver:latest，支持 Linux amd64 / arm64。桌面端产物以 Releases 实际发布内容为准。

帮助文档 Documentation | 同步服务器 SyncServer | 更新日志 Changelog | English

本项目内置了一个功能强大的 Web 播放器，让你可以随时随地在浏览器中享受音乐。同时，它也是一个增强版的 LX Music 数据同步服务端。

以下为 2026-10-23 当前 BoleServer 本地版本的实拍截图；在线歌单内容会随平台更新。手机图为 390 × 660 浏览器视口，播放页展示未播放状态。

聚合搜索歌曲、歌手与专辑，保留排行榜、收藏和本地音乐入口。音乐馆采用浅色背景与清晰排版。

浏览多平台网络歌单，查看曲目、歌手和专辑，支持收藏、批量操作与播放队列管理。

内置「音乐馆」与「播放室」，提供青瓷、潮汐、麦芽、暮紫、莓红五套配色，每套适配浅色与深色模式。播放室采用更大的歌单封面。

支持导入 LX 音源脚本和订阅清单；按顺序尝试音源，全部失败后检查订阅更新。详情见 音源订阅说明。

填写入口：播放器 → 设置 → 系统 → 自定义源 → 管理员登录 → 管理 / 添加 →「音源订阅清单」。填写 sources.json 的完整 HTTP(S) 地址，点击「保存并更新订阅」。这里不是填写歌曲或歌单链接。

手机浏览器支持歌单双列布局、底部播放控制和全屏播放页。未安装可用音源时，界面截图不代表已验证实际播放。

新安装首次访问后台时自行设置管理密码；已有部署保留原密码。后台可管理同步用户、配置、缓存和音源，继续兼容 LX Music 同步与 Subsonic 客户端。

为了保护你的隐私，Web 播放器支持开启访问密码。

1. 环境变量配置（推荐 Docker 用户使用）：
   • ENABLE_WEBPLAYER_AUTH=true: 开启认证
   • WEBPLAYER_PASSWORD=yourpassword: 设置访问密码
2. Web 界面配置： 登录管理后台（默认端口 9527），进入 "系统配置"，勾选 "启用 Web 播放器访问密码" 并设置密码。

Web 播放器针对移动端进行了深度优化，手机浏览器访问也能获得原生 App 般的体验。

Windows、macOS、Linux 桌面本地构建步骤见 跨平台构建说明。

本项目基于 Node.js 开发，支持多种部署方式。

可以通过桌面端更方便地运行 BoleServer，支持 Windows、macOS 和 Linux。

• 📦 最新版本下载: GitHub Releases
• ✨ 桌面端优势:
  • 单窗口管理: 服务器管理与 Web 播放器合二为一，界面更统一。
  • 托盘常驻: 窗口关闭后自动缩回托盘，服务在后台始终运行。
  • 本次已发布架构: Windows x64、macOS Intel / Apple Silicon、Linux x64。其他架构以实际发布附件为准。

桌面程序内置服务端，不需要 Docker。安装或运行后，首次选择数据目录并在后台设置管理密码；更新时保留数据目录。

全部附件与版本说明 · SHA256 校验文件

适用于已安装 Docker Engine 和 Docker Compose 插件的 Linux 服务器，支持 amd64 / arm64。首次启动需能访问选用的镜像下载地址。

国内加速一键安装（默认安装到 /opt/boleserver，脚本下载和镜像拉取均通过 gh-proxy.com）：

curl -fsSL https://gh-proxy.com/https://raw.githubusercontent.com/shellsec/boleserver/d2762bcfbc773a0baf81cbca5df1ba1bde2d7a29/deploy/install.sh -o /tmp/boleserver-install.sh && sudo env BOLE_IMAGE=gh-proxy.com/docker/ghcr.io/shellsec/boleserver:latest bash /tmp/boleserver-install.sh

已是 root 用户时去掉 sudo 即可。gh-proxy.com 为第三方加速服务；如无法访问或希望直连，使用下方官方命令。镜像加速地址会保存在安装目录的 .env，后续升级继续使用。

官方直连安装：

curl -fsSL https://raw.githubusercontent.com/shellsec/boleserver/main/deploy/install.sh -o /tmp/boleserver-install.sh && sudo bash /tmp/boleserver-install.sh

脚本检查 Docker、拉取镜像、创建持久化目录并启动服务，健康检查成功后显示后台地址。不会安装 Docker 或更改防火墙。自定义安装目录可在命令末尾添加目录，例如 /opt/my-boleserver。

首次打开 http://服务器IP:9527/admin/，输入两次自己选择的管理员密码（8–128 位），保存后进入后台。没有默认管理密码，也不需要查找随机密码。 密码保存在挂载的 data/config.js，容器重启、升级后仍保留。已有部署继续使用原密码。

登录后可在「系统配置 → 管理员密码」修改密码，在「用户管理」添加同步用户。音源入口是「播放器 → 设置 → 系统 → 管理员登录 → 管理 / 添加 → 音源订阅清单」，填写 LX sources.json 地址并保存；也可上传音源脚本。

手动 Compose 部署：

mkdir -p /opt/boleserver && cd /opt/boleserver
curl -fsSL https://gh-proxy.com/https://raw.githubusercontent.com/shellsec/boleserver/main/deploy/compose.yaml -o compose.yaml
printf 'BOLE_IMAGE=gh-proxy.com/docker/ghcr.io/shellsec/boleserver:latest\n' > .env
mkdir -p data cache music cover_cache
sudo chown 1000:1000 data cache music cover_cache
docker compose pull
docker compose up -d
docker compose logs -f

镜像：ghcr.io/shellsec/boleserver:latest；端口：9527。Compose 示例见 deploy/compose.yaml。data/ 保存密码、用户配置和音源；日志位于 data/logs/；cache/、music/、cover_cache/ 为持久化文件。

标准配置不设置 ADMIN_PASSWORD，方便在后台修改密码。如果手动设置了它，环境变量具有最高优先级，后台将禁止修改管理密码，需修改部署环境后重新创建容器。播放器访问密码独立，可在后台设置。

升级：先备份数据目录与 Compose 文件，然后执行：

cd /opt/boleserver
docker compose pull
docker compose up -d

升级保留数据和密码；不要删除数据目录。latest 跟随 main 分支通过测试的构建，也可使用镜像包页面上的 sha- 标签固定版本。现有本地镜像部署需先将 Compose 中 image 改为上述 GHCR 地址；仓库推送和镜像发布不会自动升级运行中的服务。

从源码构建（可选，无需在宿主机安装 Node.js）：

git clone https://github.com/shellsec/boleserver.git
cd boleserver
docker build -t boleserver:local .

忘记管理密码时，停止容器并在服务器重置为自选密码（执行时不会回显密码）：

cd /opt/boleserver
docker compose stop
read -rsp '新的管理员密码（8–128 位）: ' BOLE_NEW_PASSWORD; echo
export BOLE_NEW_PASSWORD
docker compose run --rm -e BOLE_NEW_PASSWORD --entrypoint node boleserver -e '
const fs = require("fs");
const p = process.env.BOLE_NEW_PASSWORD;
if (!p || p.trim().length < 8 || p.length > 128) throw new Error("密码长度需为 8–128 位");
const file = "/server/data/config.js";
const c = require(file); c["admin.password"] = p;
fs.writeFileSync(file, "module.exports = " + JSON.stringify(c, null, 2), { mode: 0o600 });'
unset BOLE_NEW_PASSWORD
docker compose up -d

如果设置了 ADMIN_PASSWORD，应直接修改该环境变量后执行 docker compose up -d --force-recreate。

# 1. 克隆项目
git clone https://github.com/shellsec/boleserver.git && cd boleserver

# 2. 安装依赖并编译
npm ci && npm run build

# 3. 启动服务
npm start

1. 在 GitHub Releases 下载压缩包。
2. 解压后运行 npm install --production。
3. 执行 npm start 启动。

• Web 播放器: http://<服务器IP>:9527（默认根路径，可通过 PLAYER_PATH 环境变量或后台配置自定义路径，如 /music）
  • 若启用了播放器访问密码认证（ENABLE_WEBPLAYER_AUTH），首次访问需输入播放器密码（默认 123456）。
• 管理后台: http://<服务器IP>:9527/admin（默认路径为 /admin，可通过 ADMIN_PATH 自定义，首次访问设置管理员密码，已有部署使用原密码）。

进入客户端「设置 → 同步设置」，选择自定义连接：

• 模式一：用户路径模式（推荐，默认开启 USER_ENABLE_PATH=true）
  • 连接 URL: http://<服务器IP>:9527/<用户名>（例如：http://192.168.1.100:9527/user1）
  • 连接密码: 对应用户的独立密码
  • 特点: 通过 URL 中的用户名精确路由到各用户独立存储空间，允许多个不同用户使用相同密码。
• 模式二：根路径模式（需配置 USER_ENABLE_ROOT=true）
  • 连接 URL: http://<服务器IP>:9527（例如：http://192.168.1.100:9527）
  • 连接密码: 对应用户的密码
  • 特点: URL 无需携带用户名，服务端通过鉴权密码自动匹配用户。注意：此模式下所有用户的密码必须唯一，不允许不同用户使用相同密码。

全面兼容 Subsonic API 协议，客户端中填写：

• 服务器地址 (Server URL):
  • 默认共享主端口: http://<服务器IP>:9527/rest（子路径由 SUBSONIC_PATH 决定，默认 /rest）
  • 独立监听端口模式（若配置了 SUBSONIC_PORT > 0，例如 4533）: http://<服务器IP>:4533/rest
• 用户名 & 密码: 在后台“用户管理”中配置的用户名及其同步密码。
• 在线搜索: 支持在 Subsonic 客户端中直接全网搜索与播放，可使用 wy:、tx:、kw:、kg:、mg: 指定平台，或使用 online: / local: 强制在线/本地搜索。

本项目基于 Node.js 采用前后端分离架构：

• Backend (Express + WebSocket): 核心同步逻辑与 WebDAV 备份。
• WebPlayer (Vanilla JS): 负责音乐播放业务，默认访问路径为根路径 /。
• Console (Vanilla JS): 位于 /admin 路径，负责用户与数据管理。

系统配置文件已默认持久化在数据目录中的 data/config.js（Docker 部署只需挂载 ./data 卷即可在容器更新、重启后永久保留配置，若根目录下存在旧 config.js 会自动平滑迁移）。环境变量优先级最高：

高级用户配置说明：环境变量 LX_USER_<用户名> 仅用于快速添加用户及设置密码。若需为特定用户配置独立的高级选项（如开启个人自定义音乐目录、分配操作权限 allowOperateCustomMusicDir 或写入权限 allowWriteCustomMusicDir、调整快照数量等），请直接在 config.js 的 users 数组中手动配置对应字段，或者在后台管理界面的“用户管理”面板中通过图形界面修改。

布尔类型环境变量说明：所有布尔类型的环境变量支持灵活的写法（不区分大小写），开启支持 true / 1 / yes / y / on；关闭支持 false / 0 / no / n / off。

提示：目前服务支持 启用根路径 (URL配置为 ip:port) 和 启用用户路径 (URL配置为 ip:port/username) 两种数据同步连接方式。如果没有启用用户路径，则必须保证每一个同步用户的鉴权密码不重复。

本项目集成了 PostHog 匿名数据统计，主要用于：

1. Bug 追踪: 收集版本号、环境类型。
2. 通知推送: 弹出 版本更新提醒 与 紧急维护公告。

• 绝对匿名: 绝不收集 IP、用户名或具体歌单内容。
• 关闭方法: 环境变量设置 DISABLE_TELEMETRY=true。注意：关闭后将无法收到新版本通知。

• 修改自 lyswhut/lx-music-sync-server。
• Web 播放器逻辑参考 lx-music-desktop。

本项目基于 Apache License 2.0 许可证发行，以下协议是对于 Apache License 2.0 的补充，如有冲突，以以下协议为准。

Apache License 2.0 copyright (c) 2026 xcq0607

词语约定：本协议中的“本项目”指 BoleServer 播放器；“使用者”指签署本协议的使用者；“官方音乐平台”指对本项目内置的包括酷我、酷狗、咪咕等音乐源的官方平台统称；“版权数据”指包括但不限于图像、音频、名字等在内的他人拥有所属版权的数据。

1. 官方平台: 本项目的各官方平台在线数据来源原理是从其公开服务器中拉取数据，经过对数据简单地筛选与合并后进行展示(与未登录状态在官方APP获取的数据相同)，因此本项目不对数据的合法性、准确性负责。
2. 音频数据: 本项目本身没有获取某个音频数据的能力，所使用的在线音频数据来源来自设置内“自定义源”所选择的“源”返回的在线链接。本项目无法校验其准确性，使用过程中可能会出现播放异常。
3. 其他数据: 本项目的非官方平台数据（例如“我的列表”内列表）来自服务器存储数据，本项目不对这些数据的合法性、准确性负责。

1. 版权数据: 使用本项目的过程中可能会产生版权数据。对于这些版权数据，本项目不拥有它们的所有权。为了避免侵权，使用者务必在 24 小时内 清除使用本项目的过程中所产生的版权数据。
2. 责任承担: 由于使用本项目产生的包括由于本协议或由于使用或无法使用本项目而引起的任何性质的任何直接、间接、特殊、偶然或结果性损害由使用者负责。
3. 法律法规: 本项目完全免费，且开源发布于 GitHub 面向全世界人用作对技术的学习交流。禁止在违反当地法律法规的情况下使用本项目。对于使用者在明知或不知当地法律法规不允许的情况下使用本项目所造成的任何违法违规行为由使用者承担。

1. 资源使用: 本项目内使用的部分包括但不限于字体、图片等资源来源于互联网。如果出现侵权可联系本项目移除。
2. 非商业性质: 本项目仅用于对技术可行性的探索及研究，不接受任何商业（包括但不限于广告等）合作及捐赠。
3. 接受协议: 若你使用了本项目，即代表你接受本协议。