帮助文档 Documentation | 同步服务器 SyncServer | 更新日志 Changelog | English
本项目内置了一个功能强大的 Web 播放器，让你可以随时随地在浏览器中享受音乐。同时，它也是一个增强版的 LX Music 数据同步服务端。
采用清爽的现代化 UI 设计，支持深色模式，提供极致的视觉体验。
支持聚合搜索各大音乐平台的资源，想听什么搜什么。
支持多平台歌单的浏览、搜索与一键播放，提供直观的歌单详情面板，包含封面、作者、简介等完整信息。播放队列支持拖拽排序、批量管理及快速定位当前播放。
支持播放模式切换、音质选择、歌词显示、睡眠定时、播放倍数等功能。
内置全自动化缓存系统，可自动保存歌词、链接及歌曲文件，通过专门的缓存控制面板实现颗粒化管理，极大提升弱网环境下的播放流畅度。
新增歌词卡片分享功能，支持自定义卡片比例（竖版/横版/方版）、色彩风格（深色/浅色/专辑色）及歌词行数，一键生成精美海报，支持旋转缩放。
支持多套现代化主题（如森之韵、深海鲨、暖阳意、绯红月等），并可根据系统自动切换暗亮模式。系统设置支持自动更新网络歌单、账号设置自动备份及多维度代理配置，确保播放顺滑稳定。
支持导入自定义源脚本，扩展更多音乐来源。
支持搜索专辑与歌手，并支持一键收藏，方便快速找回你喜爱的音乐人与专辑。
全面适配 Subsonic 协议，支持使用各类 Subsonic 客户端（如音流、Feishin 等）连接并播放本站资源。
为了保护你的隐私，Web 播放器支持开启访问密码。
- 环境变量配置（推荐 Docker 用户使用）：
ENABLE_WEBPLAYER_AUTH=true: 开启认证WEBPLAYER_PASSWORD=yourpassword: 设置访问密码
- Web 界面配置： 登录管理后台（默认端口 9527），进入 "系统配置"，勾选 "启用 Web 播放器访问密码" 并设置密码。
| 用户类型 | 查看列表 | 使用/切换(仅个人) | 上传/导入公开源 | 删除/修改公开源 |
|---|---|---|---|---|
| 管理员 | ✅ 允许 | ✅ 允许 | ✅ 允许 | ✅ 允许 |
| 已登录用户 | ✅ 允许 | ✅ 允许 | ❌ 禁止 | ❌ 禁止 |
| 未登录访客 | ❌ 隐藏 | ❌ 禁止 | ❌ 禁止 | ❌ 禁止 |
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 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:latestDocker 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
# - FRONTEND_PASSWORD=123456
# - ENABLE_WEBPLAYER_AUTH=true
# - WEBPLAYER_PASSWORD=yourpassword
# - ADMIN_PATH=
# - PLAYER_PATH=/music# 1. 克隆项目
git clone https://github.com/XCQ0607/lxserver.git && cd lxserver
# 2. 安装依赖并编译
npm ci && npm run build
# 3. 启动服务
npm start- 在 GitHub Releases 下载压缩包。
- 解压后运行
npm install --production。 - 执行
npm start启动。
- Web 播放器:
http://your-ip:9527/music(默认路径，可通过PLAYER_PATH修改) - 同步管理后台:
http://your-ip:9527(默认路径，可通过ADMIN_PATH修改，默认密码:123456)
本项目基于 Node.js 采用前后端分离架构：
- Backend (Express + WebSocket): 核心同步逻辑与 WebDAV 备份。
- Console (Vanilla JS): 位于根目录，负责用户与数据管理。
- WebPlayer (Vanilla JS): 负责音乐播放业务，默认访问路径为
/music。
可以直接编辑 config.js。环境变量优先级最高：
| 环境变量 | 对应配置项 | 说明 | 默认值 |
|---|---|---|---|
PORT |
port |
服务端口 | 9527 |
BIND_IP |
bindIP |
绑定 IP | 0.0.0.0 |
ADMIN_PATH |
admin.path |
后台管理界面访问路径 (默认为空，即根路径 /) |
(空) |
PLAYER_PATH |
player.path |
Web 播放器访问路径 (默认为 /music) |
/music |
SUBSONIC_ENABLE |
subsonic.enable |
是否启用 Subsonic 协议支持 (服务默认开启) | true |
SUBSONIC_PATH |
subsonic.path |
Subsonic 访问路径 (默认为 /rest) |
/rest |
FRONTEND_PASSWORD |
frontend.password |
Web 管理界面访问密码 | 123456 |
SERVER_NAME |
serverName |
同步服务名称 | My Sync Server |
MAX_SNAPSHOT_NUM |
maxSnapshotNum |
保留的最大快照数量 | 10 |
CONFIG_PATH |
- | 指定外部配置文件的绝对路径 | - |
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_URL |
webdav.url |
WebDAV 地址 | - |
WEBDAV_USERNAME |
webdav.username |
WebDAV 用户名 | - |
WEBDAV_PASSWORD |
webdav.password |
WebDAV 密码 | - |
SYNC_INTERVAL |
sync.interval |
WebDAV 自动备份间隔(分钟) | 60 |
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_LOGIN_USER_CACHE_RESTRICTION |
user.enableLoginCacheRestriction |
是否启用登录用户缓存限制 (开启后限非管理员登录用户的缓存设置) | false |
ENABLE_CACHE_SIZE_LIMIT |
user.enableCacheSizeLimit |
是否启用缓存空间限制 (开启后超出容量将按 LRU 自动清理) | false |
CACHE_SIZE_LIMIT |
user.cacheSizeLimit |
缓存空间限制大小 (单位: MB) | 2000 |
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 |
LX_USER_<用户名> |
users 数组 |
快速添加用户，值为该用户的密码 (如 LX_USER_test=123) |
- |
提示：目前服务支持
启用根路径(URL配置为ip:port) 和启用用户路径(URL配置为ip:port/username) 两种数据同步连接方式。如果没有启用用户路径，则必须保证每一个同步用户的鉴权密码不重复。
本项目集成了 PostHog 匿名数据统计，主要用于：
- Bug 追踪: 收集版本号、环境类型。
- 通知推送: 弹出 版本更新提醒 与 紧急维护公告。
- 绝对匿名: 绝不收集 IP、用户名或具体歌单内容。
- 关闭方法: 环境变量设置
DISABLE_TELEMETRY=true。注意：关闭后将无法收到新版本通知。
- 修改自 lyswhut/lx-music-sync-server。
- Web 播放器逻辑参考 lx-music-desktop。
- 接口实现基于
musicsdk。
本项目基于 Apache License 2.0 许可证发行，以下协议是对于 Apache License 2.0 的补充，如有冲突，以以下协议为准。
Apache License 2.0 copyright (c) 2026 xcq0607
词语约定：本协议中的“本项目”指 LX Music Web 播放器；“使用者”指签署本协议的使用者；“官方音乐平台”指对本项目内置的包括酷我、酷狗、咪咕等音乐源的官方平台统称；“版权数据”指包括但不限于图像、音频、名字等在内的他人拥有所属版权的数据。
- 官方平台: 本项目的各官方平台在线数据来源原理是从其公开服务器中拉取数据，经过对数据简单地筛选与合并后进行展示(与未登录状态在官方APP获取的数据相同)，因此本项目不对数据的合法性、准确性负责。
- 音频数据: 本项目本身没有获取某个音频数据的能力，所使用的在线音频数据来源来自设置内“自定义源”所选择的“源”返回的在线链接。本项目无法校验其准确性，使用过程中可能会出现播放异常。
- 其他数据: 本项目的非官方平台数据（例如“我的列表”内列表）来自服务器存储数据，本项目不对这些数据的合法性、准确性负责。
- 版权数据: 使用本项目的过程中可能会产生版权数据。对于这些版权数据，本项目不拥有它们的所有权。为了避免侵权，使用者务必在 24 小时内 清除使用本项目的过程中所产生的版权数据。
- 责任承担: 由于使用本项目产生的包括由于本协议或由于使用或无法使用本项目而引起的任何性质的任何直接、间接、特殊、偶然或结果性损害由使用者负责。
- 法律法规: 本项目完全免费，且开源发布于 GitHub 面向全世界人用作对技术的学习交流。禁止在违反当地法律法规的情况下使用本项目。对于使用者在明知或不知当地法律法规不允许的情况下使用本项目所造成的任何违法违规行为由使用者承担。
- 资源使用: 本项目内使用的部分包括但不限于字体、图片等资源来源于互联网。如果出现侵权可联系本项目移除。
- 非商业性质: 本项目仅用于对技术可行性的探索及研究，不接受任何商业（包括但不限于广告等）合作及捐赠。
- 接受协议: 若你使用了本项目，即代表你接受本协议。