Folia sync-server 完整部署指南：多设备共用一套 AI 主题外观，免重复配置

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

Folia 官方自带的 sync-server 让「每台设备都重调一遍主题」成为历史：把它部署到任意一台机器上，多台客户端接入同一个同步服务，AI 主题与外观设置就全部打通。本文按「备料 → 部署 → 配对 → 验证」的操作顺序走完整个流程，最后覆盖故障排查、隐藏看板和 zip 备份。

先搞清楚：同步到底同步什么

同步范围分两块，字段定义在 src/services/sync/syncTypes.ts：

• 外观设置快照：可视化模式、背景与透明度、字幕样式、歌词字体、首页布局等。两端记录按updatedAt时间戳比对，较新的记录生效，改过的一端不会被另一端旧数据覆盖。
• AI 主题库：每首歌曲的主题带稳定指纹，先归入固定 256 个 bucket，只比较各桶的摘要哈希（实现在 src/services/sync/syncMerkle.ts）。哪个桶变了才拉取哪个桶的内容，几百首歌曲的主题实际只传输差量。

sync-server 只做主题和外观的中转，曲库文件不经过它。

部署前准备：生成并保存两个 Token

在 Linux/macOS 终端运行下面这条命令即可得到 32 位十六进制串：

openssl rand -hex 16

另外两种方式：浏览器按F12打开控制台执行crypto.randomUUID()；装有 Node 的机器上执行node -e "console.log(crypto.randomBytes(16).toString('hex'))"。生成后立刻存入密码管理器。

⚠️ Cloudflare 部署时 Token 以加密形式存储，部署完成后无法回读明文，丢了只能重新部署注入，所以生成后先存好再动手。

三种部署方式

三者共用同一套路由与数据模型（服务端核心在 sync-server/src/app.ts），换部署方式不影响客户端。先获取源码：

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

进入克隆下来的目录后即可选择下面任意一条路径。

Cloudflare Workers：不需要服务器

零费用，服务跑在 Cloudflare 边缘网络，无需维护机器。前置条件：Cloudflare 账号 + 本机 Node.js 24+。

cd sync-server bash ./install.sh

Windows 用户在 PowerShell 里执行.\install.ps1（被执行策略拦截时改用powershell -ExecutionPolicy Bypass -File .\install.ps1）。菜单中选择3进入 Workers 流程，脚本自动串起后续步骤：创建 D1 数据库 → 生成wrangler.local.toml→ 提示输入SYNC_TOKEN→ 自动生成DASHBOARD_TOKEN并把两个 Token 注入 Cloudflare → 发布上线。整个过程只需要两次输入。

部署结束后立即抄录两样东西：Worker 域名和DASHBOARD_TOKEN（明文只显示这一次）。脚本生成的wrangler.local.toml内含你的 D1 数据库 ID，已被.gitignore忽略，不要提交进任何仓库。

Docker：VPS/NAS 上一条 compose 启动

在sync-server/下新建.env，写入SYNC_TOKEN（必填）与可选的DASHBOARD_TOKEN：

SYNC_TOKEN="你的TOKEN" DASHBOARD_TOKEN="可选的看板TOKEN"

回到仓库根目录执行构建与启动：

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

启动后服务监听宿主机13000端口，SQLite 数据库落盘在sync-server/data/folia-sync.db。如果还要连同在线音乐后端部署整套 Web 栈，改用 deploy/docker/compose.yaml。

Node 自托管：家里有一台常开的机器

前置条件同样是 Node.js 24+，底层数据库为 better-sqlite3。在sync-server/下建.env：

SYNC_TOKEN="你的TOKEN" PORT=3000 DB_PATH="./folia-sync.db"

安装依赖并启动：

npm install npm run start:node

PORT默认 3000，DB_PATH不写则默认在当前目录生成数据库文件。需要长期运行时可交给 PM2 或 Docker 托管。

客户端配对：填两栏、点两次

打开 Folia 的设置 → 存储设置 → Sync Server一节：

1. 打开「启用同步服务」开关
2. 「Sync Server URL」填根地址（URL 不带任何路径后缀），Cloudflare 域名或http://NAS-IP:13000均可；「Bearer Token」填SYNC_TOKEN，保存
3. 点「测试」按钮，测试结果通过即代表连通成功

随后点一次「同步 AI 主题」手动执行全量同步。此后每次启动 Folia 都会自动做增量同步，界面上能看到「上次同步」时间戳。

故障排查对照表

进阶：隐藏看板与 zip 备份

🖥 部署时配置了DASHBOARD_TOKEN的话，浏览器打开https://你的域名/?token=你的DASHBOARD_TOKEN即可看到当前主题数量与最近更新时间。页面纯只读，可以放心常开。

💾 同步设置同一界面还提供「导出 zip / 导入 zip」：整份主题库加外观设置可以打包成单个文件留底，也能完全绕过服务端在两台电脑之间直接迁移；若同步已启用，导入的内容会一并推送到服务端。两种方案的数据侧备份方式不同——Docker 部署打包挂载的数据目录即可（deploy/docker/compose.sync.yaml 对应sync-server/data，完整compose.yaml由FOLIA_SYNC_DATA_DIR控制）；Cloudflare 方案没有本地数据目录，建议定期用客户端导出 zip 留底。

协议与接口的完整说明见 sync-server/README.md，客户端侧的同步协调逻辑集中在 src/services/sync/。部署完成后，在一台设备上新生成的 AI 主题，另一台设备启动即可看到同样的歌词动画、字体与背景。

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