企业官网建设流程全解析

Folia sync-server 部署指南：5 分钟搭好 AI 主题跨设备同步

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

Folia 是一款支持 Navidrome 与多家在线曲库的本地歌词动画播放器。在 A 设备上把 AI 主题调满意了，不想在 B 设备上再折腾一遍？它自带的 sync-server 能帮你做增量同步，改过的才搬运，没动过的不传。本文从生成密钥、部署服务到客户端配对，一条线走完。

选一条部署路线，再生成两把钥匙

🔑 三种部署方式共用同一套路由和数据模型，区别只在载体，按你手头的机器挑：

不管走哪条路，先备好两把钥匙：

两条路任选其一：

openssl rand -hex 16

或者在浏览器按F12，控制台里跑crypto.randomUUID()。SYNC_TOKEN少于 8 位时服务会直接拒绝启动，这是防字典爆破的硬校验，别为了省事填「12345678」。

推荐：Cloudflare Workers 零服务器，两次输入发布

先拿源码：

git clone https://gitcode.com/GitHub_Trending/fo/folia-major cd folia-major/sync-server bash ./install.sh

Windows PowerShell 换成.\install.ps1。脚本会列出1) Node2) Docker3) Cloudflare Workers菜单，输入3进入 Workers 流程。之后全自动：创建 D1 数据库 → 生成wrangler.local.toml→ 提示你输入SYNC_TOKEN→ 自动生成并注入DASHBOARD_TOKEN→ 发布上线。全程只需输入两次。

结束后的输出务必抄进密码管理器：Worker 域名 +DASHBOARD_TOKEN。这个看板令牌只在部署时明文显示一次，且 Cloudflare 部署后 Token 是加密状态、无法回读，丢了只能重新部署。另外脚本生成的wrangler.local.toml里带着你的数据库 ID，已被.gitignore忽略，别提交进任何仓库。

成功标志：发布命令输出一个 Worker 域名。下一节客户端「测试」能通过，就说明服务端没问题。

有 VPS：Docker 一条命令，监听 13000 端口

在sync-server/目录下建.env：

SYNC_TOKEN="前面生成的密钥" DASHBOARD_TOKEN="可选的看板密钥"

回仓库根目录启动：

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

这份单服务编排见 deploy/docker/compose.sync.yaml：服务映射到宿主机13000 端口，SQLite 数据库落在sync-server/data/folia-sync.db。验证是否起来：

curl http://127.0.0.1:13000/health

返回含{"ok":true的 JSON 即成功。如果你还想把在线音乐后端一起部署成完整 Web 栈，改用deploy/docker/compose.yaml。

只有家里一台常开机：Node 24 直跑 + SQLite

和 Docker 方案比只少一步容器。同样在sync-server/下建.env（SYNC_TOKEN必填，PORT默认 3000，DB_PATH默认./folia-sync.db），然后：

cd sync-server npm install npm run start:node

底层是 better-sqlite3，长期运行可以交给 PM2 管起来。验证方式与 Docker 一节相同，把端口换成3000再请求/health。

客户端接入：设置页三步走完

服务跑起来后，打开 Folia 的设置 → 存储设置 → Sync Server：

1. 打开「启用同步服务」开关
2. 「Sync Server URL」填根地址（不带路径，别写/health）：Cloudflare 域名或http://NAS-IP:13000都行；「Bearer Token」填SYNC_TOKEN，点保存
3. 点「测试」，提示「测试成功」就是通了

接着点「同步 AI 主题」手动跑一次，能看到「主题同步完成，上传 X 个，下载 Y 个」的提示。此后每次启动 Folia 都会自动做增量同步，设置页显示「上次同步」时间，无需再手动操作。

到底在同步什么：设置快照 + AI 主题，只传差异

🎧 同步内容分两块，数据结构定义在 src/services/sync/syncTypes.ts：

• 外观设置快照：可视化模式、背景与透明度、字幕样式、歌词字体、首页布局等。两端按时间戳比较，时间戳新的那一端生效，旧版本不会反向覆盖新版本
• AI 主题库：主题按指纹分进 256 个 bucket，先只比对每个桶的摘要哈希，发现哪个桶变了才去取内容——几百首歌的主题，实际网络传输只有差量

桶比对与差量拉取的实现在 src/services/sync/syncMerkle.ts，其余客户端协调逻辑集中在src/services/sync/目录。

看板、zip 备份与故障自查

💾 两个附加能力别忘了用：

• 只读看板：部署时配了DASHBOARD_TOKEN的话，浏览器访问你的域名/?token=你的DASHBOARD_TOKEN，能看到主题数量和最近更新时间，页面只读
• zip 导入 / 导出：同步设置同一界面就有「导出 zip / 导入 zip」，整份库可以备份成文件，甚至完全绕开服务端在两台电脑间直接迁移；若同步已启用，导入内容也会顺手推到服务端。Docker 部署直接打包sync-server/data目录做备份，Cloudflare 方案建议定期用客户端导出留底

出问题时按这个顺序排查：

想深入：协议细节与源码入口

完整 API 表格与协议约束（schema 版本1、主题 manifest 固定 256 个 bucket、批量写入上限 500）见 sync-server/README.md；客户端协调逻辑集中在src/services/sync/，服务端入口在sync-server/src/app.ts。

做完之后的画面：电脑上新生成一个 AI 主题，手机打开就是同款外观——歌词动画、字体、背景处处一致。

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