Folia 自托管同步服务部署指南Docker 与 Node.js 两条路线【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFolia 是一款以绚丽歌词动画著称的开源音乐播放器其官方 sync-server 支持自托管部署AI 主题与视觉设置可在多台设备间实时同步。本文带你用 Docker 或 Node.js SQLite 两种方式完成部署、接线并验证全程只需要改一个.env文件。数据散落在每台机器上Folia sync-server 解决什么Folia 客户端是本地优先的AI 生成的主题、主题同步 registry 存在本机 IndexedDB视觉设置快照也默认保存在本机。这意味着你的收藏只属于这一台电脑——换机、重装系统、格式化 C 盘之前收集的主题就找不回来了。sync-server 是官方提供的同步后端一套业务逻辑同时跑在三种形态里Cloudflare Workers、Docker、Node 自托管。部署之后它负责三件事视觉设置快照按时间戳拉取/推送旧时间戳不会覆盖新数据AI 生成的主题按 256 个固定 bucket 做增量同步隐藏网页看板在浏览器里查看主题数量与最近更新时间 服务端核心在 sync-server/src/app.ts客户端同步协议在 src/services/sync/两端完全对齐。Node 版通过 sync-server/src/d1-emulator.ts 模拟 Cloudflare D1 的接口D1 是 Cloudflare 的 serverless 数据库所以三种形态共用同一套路由和表结构数据可以随时互相迁移。部署前先一行命令生成两个 Token两种方案都靠这两个凭证运行部署前一次性准备好SYNC_TOKEN必填8 ~ 32 位随机字符Folia 客户端凭它读取和写入同步数据DASHBOARD_TOKEN选填建议 16 位以上访问只读看板时防扫描用Linux/macOS 终端一行生成高强度随机串openssl rand -hex 16没有 OpenSSL 也可以浏览器控制台执行crypto.randomUUID()或 Node 终端执行node -e console.log(crypto.randomBytes(16).toString(hex))。⚠️ 服务端强制要求SYNC_TOKEN长度 ≥ 8 位过短会直接拒绝启动。Token 只在部署时明文显示一次请立即存入密码管理器。Docker 一条命令部署从克隆到 /health 返回 JSON适合有 VPS 或 NAS 的用户独立编排文件是 deploy/docker/compose.sync.yaml。克隆仓库并进入 sync-server 目录git clone https://gitcode.com/GitHub_Trending/fo/folia-major cd folia-major/sync-server在该目录新建.env把两个 Token 写进去SYNC_TOKEN你的随机字符串 DASHBOARD_TOKEN你的随机字符串回到仓库根目录启动容器监听 3000映射到宿主机默认 13000cd .. docker compose -f deploy/docker/compose.sync.yaml up -d --build启动后的运行行为宿主机端口默认13000可用环境变量FOLIA_SYNC_PORT/FOLIA_SYNC_BIND覆盖SQLite 数据库持久化在sync-server/data/folia-sync.db重启容器不丢数据内置健康检查定期请求接口确认存活每 15 秒探测一次/health容器以read_onlyno-new-privileges加固默认更安全验证浏览器访问http://你的服务器IP:13000/health。✅/health能返回 JSON 即部署成功——它是全服务唯一免鉴权的接口。如果你的目标是一整套 Web 堆栈Web 版 Folia 三大在线音乐 API改用 deploy/docker/compose.yaml说明见 deploy/docker/README.md。没有 Docker 怎么跑Node.js SQLite 方案个人电脑或轻量 VPS 装不了 Docker 时直接用 Node 跑即可底层是better-sqlite3表结构与 Docker 版同构。前置要求Node.js ≥ 24与 sync-server/package.json 的 engine 声明一致npm在sync-server目录下创建.envSYNC_TOKEN你的SYNC_TOKEN DASHBOARD_TOKEN你的DASHBOARD_TOKEN PORT3000 DB_PATH./folia-sync.db安装依赖并启动cd sync-server npm install npm run start:node终端出现彩色 ASCII 风格的 FOLIA SYNC SERVER Logo、并打印出端口与数据库路径即启动成功配了DASHBOARD_TOKEN时还会直接打印看板链接。长期挂机建议用 PM2 托管。 不想手写配置官方安装向导 sync-server/install.shWindows 用 sync-server/install.ps1提供1) Node (PM2)/2) Docker/3) Cloudflare Workers三选一菜单会自动生成.env和看板 Token。选 Cloudflare 的话脚本会替你完成 D1 建库、Secret 注入和发布零成本 Serverless。客户端接入填两个字段按测试按钮服务跑起来后打开 Folia 客户端设置 → 连接与集成找到同步区域填两项workerBaseUrl服务根地址例如http://127.0.0.1:13000Token 输入框前面生成的SYNC_TOKEN客户端会以Authorization: Bearer方式发送同区域还有几个按钮各司其职立即同步主题、同步视觉设置设置快照、测试连通性、导出/导入完整主题库 zip、保存。客户端启动时会自动做主题同步视觉设置的拉取/推送和主题库导入导出由上面的按钮或命令面板触发。✅ 点测试显示成功、立即同步后主题列表出现新条目说明两端协议握手正常。验证与日常维护看板、常用 API、公网暴露配了DASHBOARD_TOKEN时浏览器打开http://你的服务地址:13000/?token你的DASHBOARD_TOKEN页面只读展示当前存储的主题数量与最近更新时间没有任何敏感交互日常扫一眼就能确认服务活着。需要自己写脚本对接时常用接口一览GET /health连通性与 schema 版本检查唯一免鉴权GET/PUT /settings按时间戳读取/更新视觉设置快照GET /themes/manifest读取 256 个 bucket 的摘要POST /themes/bucket按 bucket 增量拉取单请求最多 32 个 bucketPOST /themes/put批量写入主题单批上限 500旧时间戳不覆盖新记录POST /themes/get/POST /themes/list按 fingerprint 读取 / 分页导出list 单次最多 1000 条GET /state查看设置与主题的更新时间和主题数量维护时最常碰到的三个问题忘记看板 Token重新生成DASHBOARD_TOKEN并重启服务即可重置SYNC_TOKEN所有已连接的客户端都要同步更新配置否则会鉴权失败暴露公网安全吗在 Nginx/WAF 层加频率限制防字典爆破如果只在内网设备之间同步让服务留在局域网内最稳妥下次换新设备时填进同一个地址和 Token之前收集的 AI 主题与视觉设置会原样出现在库里——换机不用再重新收集。完整文档见 sync-server/README.md。【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考