xcq0607/lxserver repository overview

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

⁠✨ Web 播放器核心特性

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

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

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

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

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

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

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

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

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

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

⁠6. Subsonic 协议与多端互联

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

⁠🔒 访问控制与安全

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

⁠开启方式

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

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

⁠📱 移动端适配

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

⁠🚀 快速启动 (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=/

⁠📂 持久化卷映射 (Volumes)

为了确保数据在容器更新、重启或镜像升级后永久保存，请挂载以下数据卷：

⁠🌐 服务连接与客户端配置指南

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

⁠🛡️ 数据收集与隐私说明

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

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

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

⁠🤝 贡献与致谢

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

⁠👥 贡献者 (Contributors)

⁠

⁠📈 Star History

⁠

⁠📄 开源协议

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

Apache License 2.0 copyright (c) 2026 xcq0607⁠

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

⁠一、数据来源

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

⁠二、免责声明

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

⁠三、其他

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