LX Music Sync Server (Enhanced Edition)

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

---

LX Music Sync Server 是一个可以自行部署的音乐同步服务。它在 LX Music 同步服务端 的基础上加入了 Web 播放器、本地音乐管理、服务端下载、Subsonic 接口和管理后台。

同一套服务可以供浏览器、LX Music 桌面端/移动端以及支持 Subsonic 的客户端使用。LX 客户端同步的是歌单等数据；服务器上的音频文件由本地音乐库管理，不会随歌单同步自动传到每台设备。

文档导航

• 部署与首次使用
• 连接客户端
• 播放器与音乐管理
• 账号与权限
• 数据目录与备份
• 配置方式
• 常见问题
• 开发与接口

完整文档见 文档站，接口说明见 API 参考 和 路由索引。英文介绍见 README_EN.md。

部署与首次使用

选择运行方式

方式	适用情况	需要准备
Docker / Docker Compose	NAS、服务器、长期运行	Docker，保存配置和音乐的宿主机目录
Node.js 源码运行	本地开发、自行修改或编译	Node.js 22 或更高版本、npm、Git
Release 服务端压缩包	使用已编译的服务端	Node.js，包含编译产物的发行包
桌面客户端	在桌面窗口中管理与使用服务	与操作系统、CPU 架构匹配的安装包
PM2 托管	已编译的 Node.js 服务长期运行	单独安装 PM2，先完成构建

默认主端口是 9527。启动后，播放器位于 /，管理后台位于 /admin，Subsonic 路径为 /rest。

Docker Compose

在准备保存数据的目录中创建 compose.yaml：

services:
  lx-sync-server:
    image: xcq0607/lxserver:latest
    container_name: lx-sync-server
    restart: unless-stopped
    ports:
      - "9527:9527"
    volumes:
      - ./data:/server/data
      - ./cache:/server/cache
      - ./music:/server/music
      # 使用已有音乐目录时再添加挂载，例如：
      # - /mnt/nas/music:/library:ro
    environment:
      NODE_ENV: production
      ADMIN_PASSWORD: "replace-with-your-admin-password"
      ENABLE_WEBPLAYER_AUTH: "true"
      WEBPLAYER_PASSWORD: "replace-with-your-player-password"
      # 创建同步用户，也可以启动后在后台添加：
      # LX_USER_user1: "replace-with-your-user-password"

执行：

docker compose up -d
docker compose logs -f --tail=100

也可以将镜像名换成 ghcr.io/xcq0607/lxserver:latest。固定版本部署时，把 latest 换成镜像仓库实际存在的版本标签。

镜像默认将日志写入 /server/data/logs，上述 data 挂载已包含日志。如需单独保存，增加 ./logs:/server/logs 挂载，并同时设置 LOG_PATH: /server/logs。只挂载 /server/logs 不会改变默认日志位置。

cache 和 music 挂载用于程序根目录存储模式；选择数据目录存储后，相应文件位于 /server/data 下。保留这三个挂载，可以在切换存储模式和更新容器时继续使用原文件。

Docker Run

以下为 Bash 示例，路径相对于当前目录：

docker run -d \
  --name lx-sync-server \
  --restart unless-stopped \
  -p 9527:9527 \
  -v "$(pwd)/data:/server/data" \
  -v "$(pwd)/cache:/server/cache" \
  -v "$(pwd)/music:/server/music" \
  -e ADMIN_PASSWORD="replace-with-your-admin-password" \
  -e ENABLE_WEBPLAYER_AUTH=true \
  -e WEBPLAYER_PASSWORD="replace-with-your-player-password" \
  xcq0607/lxserver:latest

Windows PowerShell 用户可以使用上面的 Compose 文件，避免多行命令和路径语法的差异。

从源码运行

git clone https://github.com/XCQ0607/lxserver.git
cd lxserver
npm ci
npm run build
npm start

构建会生成服务端 JavaScript、播放器样式和文件管理器前端资源，并检查音频指纹工具。安装和首次构建需要访问依赖仓库及相关二进制下载地址。

本地开发使用 npm run dev。修改 TypeScript 源码后，生产运行方式需要重新执行 npm run build；npm start 加载的是 server/ 中的编译结果。

Release 与桌面客户端

从 GitHub Releases 下载对应文件。桌面版选择匹配系统与架构的安装包，具体提供哪些构建以该次发布的附件为准。

服务端压缩包需要包含 server/、public/、index.js 和 package.json 等运行文件。解压后安装生产依赖并启动：

npm install --omit=dev
node index.js

GitHub 自动生成的 Source code 压缩包是源码，不能当作已编译的服务端包使用；使用源码包时按前面的源码步骤构建。

node index.js 直接运行编译产物，不执行 npm 生命周期脚本；npm start 还会执行音频指纹工具检查和构建信息刷新。使用 npm 启动时需保留发行包中的 scripts/。桌面版使用独立的存储设置，端口被占用时会尝试其他端口，以应用实际显示的地址为准。

PM2 托管与自行构建镜像

先完成依赖安装和构建，再在项目目录执行：

npm install -g pm2
npm run prd
pm2 status
pm2 logs lx-music-sync-server
pm2 save

npm run prd 调用 pm2 start ecosystem.config.js --env production，不会自动构建。PM2 不在项目依赖内，需要单独安装；pm2 save 保存进程列表，系统开机自启还需按部署系统配置。

如需使用自己修改的 Docker 镜像：

docker build -t lxserver:local .

把 Compose 中的镜像改为 lxserver:local 后启动。桌面包构建命令为 npm run electron:dist，原生模块与打包环境要求取决于目标系统；它属于开发构建流程，不是普通服务端的启动命令。

第一次启动后

1. 打开 http://服务器IP:9527/admin，使用设置的管理员密码登录。未配置时，默认密码是 123456。
2. 在“用户管理”中创建个人账号，设置用户名和同步密码。
3. 打开 http://服务器IP:9527/。若启用了播放器访问认证，先输入播放器访问密码，再按需登录个人账号。
4. 需要在线播放时，在自定义源管理中导入可用的音源脚本并启用。
5. 需要管理本地歌曲时，检查存储位置、目录挂载和账号权限，再扫描音乐目录。

管理员密码、播放器访问密码、个人账号密码用途不同，详见“账号与权限”。

连接客户端

浏览器

入口	默认地址	用途
Web 播放器	http://服务器IP:9527/	搜索、播放、歌单和本地音乐管理
管理后台	http://服务器IP:9527/admin	用户、系统配置、备份、日志和文件管理

可以通过 PLAYER_PATH 和 ADMIN_PATH 改变路径。例如播放器设为 /music 后，访问 http://服务器IP:9527/music。两个路径不能相同，也不能占用 /api 路径；根路径使用 /。

手机和电脑使用相同地址访问。音频自动播放、锁屏播放和媒体按键行为还受浏览器及系统权限影响。

LX Music 桌面端与移动端

在 LX Music 的“设置 → 同步设置”中选择自定义服务器。

模式	连接地址示例	密码	要求
用户路径模式，默认开启	http://192.168.1.100:9527/user1	user1 的同步密码	USER_ENABLE_PATH=true，按用户名区分用户，允许不同用户密码相同
根路径模式，默认关闭	http://192.168.1.100:9527	对应用户的同步密码	USER_ENABLE_ROOT=true，用户密码必须唯一

这里填写个人账号的同步密码。连接同步服务不使用 /admin、/rest 或播放器访问密码。

首次同步时留意客户端给出的合并、覆盖方向。已有歌单建议先备份，再决定哪一端的数据作为基准。同步协议和配置细节见 同步服务说明。

Subsonic 客户端

支持使用音流、Feishin、Symfonium 等客户端访问已实现的 Subsonic/OpenSubsonic 接口。各客户端支持的功能不同，接口范围和已知限制见 Subsonic 状态。

默认连接信息：

项目	填写内容
服务地址	http://服务器IP:9527/rest
用户名	后台创建的个人账号
密码	该账号的同步密码

部分客户端会自动拼接 /rest；这类客户端按其提示填写主机地址，避免最终请求变成 /rest/rest。

默认与主服务共用端口。需要独立端口时，在后台开启独立监听，或在配置中设置 subsonic.standalone=true，并设置 subsonic.port。端口默认值为 4050，只设置 SUBSONIC_PORT 不会开启独立监听。Docker 还需要额外映射对应端口；协议路径由 subsonic.path 决定。

在线搜索由 subsonic.onlineSearch 和 subsonic.onlineSearchMode 控制：

模式	行为
fallback	本地搜索不足时补充在线结果
merge	合并本地与在线结果
local_only	仅搜索本地内容

搜索词还支持 wy:、tx:、kw:、kg:、mg: 指定平台，以及 online:、local: 前缀指定搜索范围。在线播放仍依赖可用的自定义音源。

Subsonic 本地曲库按当前账号的持久化存储设置读取音乐和缓存，并加入该账号已启用的自定义目录。网页中临时切换浏览目录，不会改变 Subsonic 的曲库范围。

默认返回只读的“本地歌曲”歌单；自定义目录可以单独显示。纯本地歌单保存在服务端，不进入 LX 官方客户端同步；混合歌单中的在线歌曲和本地成员分别保存。详情见 Subsonic 本地音乐库。

播放器与音乐管理

播放与界面

播放器提供播放队列、音质切换、倍速、睡眠定时、全屏歌词和主题设置。桌面和手机使用响应式布局；可以按自己的使用习惯选择主题、播放器背景和歌词展示方式。

页面会显示版本与构建指纹，例如 v2.1.4 · build 123abcd。版本来自 package.json，指纹由构建或启动脚本刷新，排查同一版本下的自定义改动时可以一并提供。

搜索、歌手与专辑

在线搜索使用酷我（kw）、酷狗（kg）、QQ 音乐（tx）、网易云（wy）和咪咕（mg）等平台数据。可以按单个平台搜索，也可以在支持的搜索类型中使用聚合模式。

单源歌曲搜索由服务端连续获取结果，前端在收到的列表中分页。平台可能限制结果深度，服务端也设有页数和耗时预算，因此页面显示的结果数不一定等于平台自报总数。歌手、专辑和歌单等搜索类型的支持情况随平台而异。

搜索到歌曲信息与取得可播放链接是两个步骤：前者来自音乐平台检索，后者由自定义音源解析。因此，能搜到歌曲但无法播放时，应先检查自定义源、音质和网络请求，而不是反复清空搜索结果。

歌单、收藏与播放队列

播放器支持个人歌单、收藏歌手与专辑、平台歌单、排行榜，以及播放队列调整。个人数据归属于登录账号；公开收藏是否显示和允许访问，由后台公共权限控制。

平台歌单与用户自己的同步歌单用途不同。对个人歌单的增删会影响同步数据；浏览平台榜单不会把整个榜单自动写入个人歌单。

本地音乐与下载

本地音乐页用于查看服务器上的音频文件，包括下载目录、缓存目录和已授权的自定义音乐目录。可查看音频规格、封面、歌词和关联状态，使用 &、|、! 组合条件筛选，并执行批量操作。

操作	文件保存位置 / 影响
浏览器下载	由浏览器保存到访问设备，受浏览器下载权限控制
服务端下载或缓存	保存到服务器目录，占用服务器磁盘和网络资源
关联在线歌曲、更新元数据	将本地文件与平台歌曲信息关联，相关操作可能改写音频标签
嵌入歌词	写入音频文件中的歌词标签，具体支持取决于格式
洗版	解析并下载其他可用音质来