Folia sync-server 快速部署：如何 5 分钟免费打通 AI 主题与外观设置的跨设备同步

Folia sync-server 快速部署：如何 5 分钟免费打通 AI 主题与外观设置的跨设备同步

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major

Folia 是一款本地优先的音乐播放器，卖点是绚丽的歌词动画；但你在电脑上精心调好的外观，手机并不认识——打开就是默认样式。仓库自带的 Folia sync-server 负责在自己设备之间同步 AI 主题和外观设置：读完这篇，你能在 5 分钟左右完成部署并跑通第一次跨设备同步，走 Cloudflare 路线时总成本为零。

同步打通后，两台设备长什么样

你在电脑上给某首歌调好一套 AI 主题，手机里点开同一首歌，动画、字体、背景全部和电脑一致；背景、透明度、字幕样式、首页布局这类视觉设置也会跟着对齐。之后每次启动 Folia 都会自动做增量拉取，设置页能看到「上次同步」的时间戳；不想等自动时，点一下「同步 AI 主题」强制执行即可。

双向同步是怎么工作的

同步传输的内容分两类。第一类是外观设置快照：两端各存一份修改时间戳，像共享白板上的两张便签——谁新谁生效，改之前先看时间，不会出现互相覆盖。第二类是 AI 主题库：每个主题按指纹哈希进 256 个「行李箱」桶，像机场的行李分拣区。同步前两端先只比对「行李牌」（每个桶的摘要哈希），牌没变就不拆箱，只有牌变化的桶才把差量内容真正传过来——几百首歌的库，流量也非常小。协议字段在 src/services/sync/syncTypes.ts，行李牌比对实现见 src/services/sync/syncMerkle.ts。

🔑 先备齐两把钥匙和一套环境

无论走哪条路线，底层路由和数据结构都一致，准备工作完全共用：

生成钥匙：浏览器按F12进控制台跑crypto.randomUUID()，或者终端敲openssl rand -hex 16，随手就能拿到一串。

Cloudflare 部署后 Token 会被加密存储、无法回读明文，丢了只能重新部署。所以务必在部署动作之前就把钥匙存进密码管理器，而不是事后补。

三选一：零运维、一命令、常开机

先拿源码：

git clone https://gitcode.com/GitHub_Trending/fo/folia-major && cd folia-major

边缘托管：Cloudflare Workers

适合手上没有服务器的人。交互环节只有两处——选菜单、输 Token，其余全自动。进入目录执行安装脚本，菜单输3进入 Workers 流程：

cd sync-server && bash ./install.sh

Windows 在 PowerShell 里跑.\install.ps1。脚本自动串起整条链路：创建 D1 数据库（Cloudflare 托管的 SQLite）→ 生成wrangler.local.toml→ 提示输入SYNC_TOKEN→ 自动生成并注入DASHBOARD_TOKEN→ 发布上线。

成功标志：脚本结尾输出 Worker 域名和DASHBOARD_TOKEN（明文只出现这一次），立刻把两者抄进密码管理器。脚本生成的wrangler.local.toml含你的数据库 ID，不要提交进任何仓库。

一条 compose 拉容器：Docker

适合 VPS 和 NAS。在sync-server/下新建.env写上SYNC_TOKEN（选填DASHBOARD_TOKEN），然后回仓库根目录执行：

docker compose -f deploy/docker/compose.sync.yaml up -d --build

成功标志：curl http://127.0.0.1:13000/health能拿到健康响应。端口映射为容器3000到宿主13000，SQLite 文件落在sync-server/data/folia-sync.db。想连在线音乐后端一起跑，改用完整的deploy/docker/compose.yaml，单同步场景用不着。

常开机原生跑：Node

适合家里那台常开但装不了 Docker 的机器，要求 Node.js 24+。在sync-server/下建.env填好SYNC_TOKEN（PORT默认 3000、DB_PATH可选），接着：

cd sync-server && npm install

npm run start:node

成功标志：curl http://127.0.0.1:3000/health返回健康响应即说明监听正常；数据库文件默认生成在sync-server/目录，常驻可用 PM2 管理。

客户端填两个字段，跑通整条链路

服务跑起来后，打开 Folia 客户端，只填两个字段、四步走完：

1. 「设置 → 存储设置 → 同步服务」一节，打开「启用同步服务」开关
2. 「Sync Server 地址」填入服务的根地址——Cloudflare Worker 域名，或http://NAS-IP:13000——末尾不要拖任何路径；「Bearer Token」填SYNC_TOKEN，点保存
3. 点「测试」：提示测试成功说明链路已通；出现连接失败或凭证无效，看下面排查表
4. 点「同步 AI 主题」手动执行一次，界面会汇报上传、下载的主题数和处理过的差异桶数，看到数字就代表整条链路通了

上线后的三件日常事：看板、备份、排查

隐藏看板：部署时配了DASHBOARD_TOKEN的话，浏览器访问你的域名/?token=你的DASHBOARD_TOKEN能看到主题数量和最近更新时间。页面只有展示功能，配了就可以放心开着。

zip 备份与迁移：同一设置界面里有「导出 zip / 导入 zip」。导出即把整份主题库打成一份 zip；只是想在两台电脑之间搬库，也能不经服务端直接互相导入导出，同步开启时导入内容会顺手推到服务端。Docker 路线备份sync-server/data目录即可；Cloudflare 路线没有本地数据文件，建议定期用客户端导出留底。

故障排查：

完整 API 表和手动部署细节在sync-server/README.md；服务端路由实现在 sync-server/src/app.ts，客户端的同步协调逻辑集中在 src/services/sync/ 目录。

花出去的 5 分钟很值：电脑和手机上的歌词动画、字体与背景，从此同源生成、处处一致。

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major