LX Music Sync Server (Enhanced Edition)

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

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

✨ Web 播放器核心特性

1. 现代化界面与全能播放控制

采用清新现代的响应式 UI 设计，支持深浅色模式切换与沉浸式全屏歌词；底栏集成音质切换、倍速播放、睡眠定时等完整控制。

2. 多源聚合搜索与歌手专辑

聚合各大音乐平台在线资源，秒级检索歌曲、歌手与完整专辑，支持一键收藏与作品快速回溯。

3. 多平台歌单与播放队列管理

支持同步浏览多平台热门网络歌单与详情；右侧便捷抽屉面板支持播放队列拖拽排序及自动化本地缓存管理。

4. 本地音乐库与共享收藏

统一管理服务器本地存储、下载及缓存的音频文件，支持无损规格解析、布尔逻辑搜索（&、|、!）、状态查漏与批量操作；支持开启多用户公共共享曲库。

5. 个性化主题、歌词卡片与自定义源

提供多套精美色彩主题与暗亮模式切换；支持一键生成多比例高清歌词分享卡片；支持导入自定义音源脚本扩展无限可能。

6. Subsonic 协议与多端互联

全面兼容 Subsonic API 协议，支持使用各类第三方客户端（音流、Feishin 等）连接播放，支持客户端内全网在线搜索与本地资源检索。

🔒 访问控制与安全

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

开启方式

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

权限与公开源限制矩阵 (当 `user.enablePublicRestriction` 开启时)

用户类型	查看列表	使用/切换(仅个人)	修改默认音质	上传/导入公开源	删除/修改公开源
管理员	✅ 允许	✅ 允许	✅ 允许	✅ 允许	✅ 允许
已登录用户	✅ 允许	✅ 允许	✅ 允许	❌ 禁止	❌ 禁止
未登录访客	❌ 隐藏	❌ 禁止	❌ 禁止	❌ 禁止	❌ 禁止

📱 移动端适配

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

🚀 快速启动

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

方式一：桌面客户端

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

📦 最新版本下载: GitHub Releases
✨ 桌面端优势:
- 单窗口管理: 服务器管理与 Web 播放器合二为一，界面更统一。
- 托盘常驻: 窗口关闭后自动缩回托盘，服务在后台始终运行。
- 全架构支持: 提供 Windows (x64/x86/ARM64 Setup 及 Portable)、macOS (Intel/Apple Silicon) 及 Linux (amd64/arm64/armv7l) 全家桶。

方式二：使用 Docker

本项目支持从 Docker Hub 或 GitHub Packages 拉取镜像：

Docker Hub: xcq0607/lxserver:latest
GitHub Packages: ghcr.io/xcq0607/lxserver:latest

Docker Run 示例：

docker run -d \
  -p 9527:9527 \
  -v $(pwd)/data:/server/data \
  -v $(pwd)/logs:/server/logs \
  -v $(pwd)/cache:/server/cache \
  -v $(pwd)/music:/server/music \
  --name lx-sync-server \
  --restart unless-stopped \
  xcq0607/lxserver:latest

Docker Compose 示例：

新建 docker-compose.yml 文件：

version: '3'
services:
  lx-sync-server:
    image: xcq0607/lxserver:latest
    container_name: lx-sync-server
    restart: unless-stopped
    ports:
      - "9527:9527"
    volumes:
      - ./data:/server/data
      - ./logs:/server/logs
      - ./cache:/server/cache
      - ./music:/server/music
    environment:
      - NODE_ENV=production
      # - ADMIN_PASSWORD=123456
      # - ENABLE_WEBPLAYER_AUTH=true
      # - WEBPLAYER_PASSWORD=yourpassword
      # - ADMIN_PATH=/music
      # - PLAYER_PATH=/

方式三：直接运行 (Git Clone)

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

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

# 3. 启动服务
npm start

方式四：使用 Release 版本

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

3. 服务连接与客户端配置指南

① Web 界面访问

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

② LX Music 客户端同步配置（桌面端 / 移动端）

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

模式一：用户路径模式（推荐，默认开启 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 音乐客户端配置（音流 / Feishin / Symfonium 等）

全面兼容 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 会自动平滑迁移）。环境变量优先级最高：

环境变量	对应配置项	说明	默认值
`PORT`	`port`	服务端口	`9527`
`ADMIN_PATH`	`admin.path`	后台管理界面访问路径	`/admin`
`PLAYER_PATH`	`player.path`	Web 播放器访问路径 (默认为根路径 `/`)	`/`
`ADMIN_PASSWORD`	`admin.password`	管理员密码（用于登录控制台和音乐播放器管理员登录）	`123456`
`SERVER_NAME`	`serverName`	同步服务名称（客户端连接展示名称及管理后台标题）	`LX Sync Server`
`PLAYER_NAME`	`player.name`	Web 播放器名称（播放器网页标题及登录卡片标题）	`LX Music Web`
`ENABLE_DEBUG`	`debug.enabled`	是否启用 DEBUG 模式 (开启后输出详细调试日志与音源内部日志，默认关闭)	`false`
`MAX_SNAPSHOT_NUM`	`maxSnapshotNum`	保留的最大快照数量	`10`
`CONFIG_PATH`	-	指定外部配置文件的绝对路径 (默认使用 `data/config.js`)	-
`DATA_PATH`	-	指定数据存储目录的绝对路径	`./data`
`LOG_PATH`	-	指定日志输出目录的绝对路径	`./logs`
`PROXY_HEADER`	`proxy.header`	代理转发 IP 头 (如 `x-real-ip`)	-
`USER_ENABLE_ROOT`	`user.enableRoot`	启用根路径 (开启后连接URL即为 `ip:port`，不允许不同用户密码相同)	`false`
`USER_ENABLE_PATH`	`user.enablePath`	启用用户路径 (开启后连接URL需为 `ip:port/用户名`，允许密码相同)	`true`
`WEBDAV_ENABLE`	`webdav.enable`	是否启用 WebDAV 同步与备份	`false`
`WEBDAV_URL`	`webdav.url`	WebDAV 地址	-
`WEBDAV_USERNAME`	`webdav.username`	WebDAV 用户名	-
`WEBDAV_PASSWORD`	`webdav.password`	WebDAV 密码	-
`WEBDAV_SYNC_PATH`	`webdav.syncPath`	WebDAV 增量同步远端路径	`/lx-sync`
`WEBDAV_BACKUP_PATH`	`webdav.backupPath`	WebDAV 全量备份远端路径	`/lx-sync-backups`
`SYNC_INTERVAL`	`sync.interval`	WebDAV 增量同步检测间隔(分钟)	`60`
`BACKUP_INTERVAL`	`sync.backupInterval`	WebDAV 全量备份间隔(小时)	`24`
`WEBDAV_EXCLUDE_CACHE`	`webdav.excludeCache`	排除缓存目录同步 (`data/<用户>/cache`)，开启后不参与增量同步及全量备份（已同步的文件不会被删除）	`false`
`WEBDAV_EXCLUDE_MUSIC`	`webdav.excludeMusic`	排除下载目录同步 (`data/<用户>/music`)，开启后不参与增量同步及全量备份（已同步的文件不会被删除）	`false`
`ENABLE_WEBPLAYER_AUTH`	`player.enableAuth`	是否启用 Web 播放器访问密码	`false`
`WEBPLAYER_PASSWORD`	`player.password`	Web 播放器访问密码	`123456`
`DISABLE_TELEMETRY`	`disableTelemetry`	是否禁用匿名数据统计，系统更新提示以及系统公告提示	`false`
`ENABLE_PUBLIC_USER_RESTRICTION`	`user.enablePublicRestriction`	是否启用公开用户权限限制 (限制上传、删除公开源、缓存到服务器等)	`true`
`ENABLE_PUBLIC_NON_ADMIN_LOCAL_MUSIC`	`user.enablePublicNonAdminLocalMusic`	是否开启非管理员访问本地音乐 (允许未登录管理员的公开账号访问本地音乐)	`false`
`ENABLE_PUBLIC_NON_ADMIN_BROWSER_DOWNLOAD`	`user.enablePublicNonAdminBrowserDownload`	是否开启非管理员浏览器下载 (允许未登录管理员的公开/普通账号使用浏览器下载歌曲)	`true`
`ENABLE_PUBLIC_NON_ADMIN_SERVER_CACHE`	`user.enablePublicNonAdminServerCache`	是否开启非管理员服务器缓存 (允许未登录管理员的公开/普通账号将歌曲缓存到服务器)	`false`
`ENABLE_PUBLIC_FAVORITES`	`user.enablePublicFavorites`	是否开启公开收藏和歌曲 (开启后允许公开/未登录用户查看及播放公开收藏)	`false`
`ENABLE_PUBLIC_NON_ADMIN_ACCESS`	`user.enablePublicNonAdminAccess`	是否开启非管理员访问公开收藏和歌曲 (允许未登录管理员的公开账号查看)	`false`
`ENABLE_CUSTOM_MUSIC_DIR`	`user.enableCustomMusicDir`	是否开启自定义歌曲目录总开关	`false`
`ENABLE_LOGIN_USER_CACHE_RESTRICTION`	`user.enableLoginCacheRestriction`	是否启用登录用户缓存限制 (开启后限非管理员登录用户的缓存设置)	`false`
`ENABLE_CACHE_SIZE_LIMIT`	`user.enableCacheSizeLimit`	是否启用缓存空间限制 (开启后超出容量将按 LRU 自动清理)	`false`
`CACHE_SIZE_LIMIT`	`user.cacheSizeLimit`	缓存空间限制大小 (单位: MB)	`2000`
`CONFIG_BACKUP_ENABLE`	`configBackup.enable`	是否启用配置文件自动备份功能 (每天生成一份历史配置副本)	`true`
`CONFIG_BACKUP_RETENTION_DAYS`	`configBackup.retentionDays`	配置文件备份保留天数 (自动清理过期备份)	`7`
`CONFIG_BACKUP_DIR`	`configBackup.dir`	配置文件备份存储目录路径 (支持绝对路径或相对 `./data`)	`backups`
`SNAPSHOT_BACKUP_PATH`	`snapshot.backupPath`	歌单快照自定义存储路径 (支持绝对路径或相对 `./data`，各用户独立隔离)	-
`LIST_ADD_MUSIC_LOCATION_TYPE`	`list.addMusicLocationType`	添加歌曲到列表时的位置 (`top` / `bottom`)	`top`
`PROXY_ALL_ENABLED`	`proxy.all.enabled`	是否启用外发请求代理 (针对 Music SDK)	`false`
`PROXY_ALL_ADDRESS`	`proxy.all.address`	代理地址 (支持 http:// 或 socks5://)	-
`SINGER_SOURCE_PRIORITY`	`singer.sourcePriority`	歌手信息获取来源优先级 (如 `tx,wy` 或 `wy,tx`)	`tx,wy`
`SUBSONIC_ENABLE`	`subsonic.enable`	是否启用 Subsonic 协议支持	`true`
`SUBSONIC_PATH`	`subsonic.path`	Subsonic 接口访问路径 (默认为 `/rest`)	`/rest`
`SUBSONIC_PORT`	`subsonic.port`	Subsonic 独立监听端口 (`0` 为关闭独立端口，与主服务共用端口)	`0`
`SUBSONIC_ENABLE_DEBUG`	`subsonic.enableDebug`	是否开启 Subsonic 调试日志模式	`false`
`SUBSONIC_ONLINE_SEARCH`	`subsonic.onlineSearch`	是否开启 Subsonic 在线全网搜索	`true`
`SUBSONIC_ONLINE_SEARCH_MODE`	`subsonic.onlineSearchMode`	Subsonic 在线搜索模式 (`fallback` / `merge` / `local_only`)	`fallback`
`SUBSONIC_ONLINE_SEARCH_SOURCES`	`subsonic.onlineSearchSources`	Subsonic 在线搜索默认音源列表	`wy,tx,kw,kg,mg`
`SUBSONIC_PUBLIC_LEADERBOARDS`	`subsonic.publicLeaderboards`	是否开启 Subsonic 公开排行榜 (将在线排行榜映射为只读歌单)	`true`
`SUBSONIC_LEADERBOARD_SOURCE`	`subsonic.leaderboardSource`	Subsonic 公开排行榜默认音源平台 (仅支持单选, 如 `tx`, `wy` 等)	`tx`
`SUBSONIC_LYRIC_TRANSLATION`	`subsonic.lyricTranslation`	Subsonic 歌词中是否包含翻译	`true`
`SUBSONIC_CACHE_ON_PLAY`	`subsonic.cacheOnPlay`	Subsonic 播放时是否触发服务器自动缓存保存 (落盘到用户目录)	`false`
`SUBSONIC_PLAY_CACHE_FIRST`	`subsonic.playCacheFirst`	Subsonic 播放时是否优先使用服务器已有的本地缓存/下载文件直接传输	`true`
`SUBSONIC_QUALITY_ENABLED`	`subsonic.quality.enabled`	Subsonic 是否开启音质优选	`true`
`SUBSONIC_QUALITY_PRIORITY`	`subsonic.quality.priority`	Subsonic 音质优选优先级列表 (如 `flac,320k,128k`)	`flac,320k,128k`
`ARTIST_MAX_FETCH_PAGES`	`artist.maxFetchPages`	歌手歌曲最大抓取页数	`20`
`CACHE_NAMING_PATTERN`	`cache.namingPattern`	缓存文件命名规则 (`simple` / `custom`)	`simple`
`SYSTEM_ALLOW_UNSAFE_VM`	`system.allowUnsafeVM`	是否允许运行 VM 模式自定义源脚本 (需注意安全风险)	`false`
`LX_USER_<用户名>`	`users` 数组	快速添加用户，值为该用户的密码 (如 `LX_USER_test=123`)	-

高级用户配置说明：环境变量 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 匿名数据统计，主要用于：

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

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

🤝 贡献与致谢

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

👥 贡献者 (Contributors)

📈 Star History

📄 开源协议

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

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

一、数据来源

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

二、免责声明

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

三、其他

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

Name		Name	Last commit message	Last commit date
.github		.github
.husky		.husky
.vscode		.vscode
docs		docs
electron		electron
image/changelog		image/changelog
md		md
notice		notice
packaging		packaging
public		public
scripts		scripts
src		src
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.ncurc.js		.ncurc.js
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
changelog.md		changelog.md
commitlint.config.js		commitlint.config.js
config.js		config.js
docker-compose.yml		docker-compose.yml
ecosystem.config.js		ecosystem.config.js
electron-builder.yml		electron-builder.yml
function.md		function.md
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation