Folia sync-server 五分钟免费部署：从零跑通跨设备 AI 主题同步
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是以歌词动画见长的本地音乐播放器，曲库支持本地文件夹和 Navidrome、网易云、QQ、酷狗等在线源。仓库自带的 Folia sync-server 负责把你的外观设置和 AI 主题在多台设备间同步。你不需要服务器和运维经验，照下面的步骤做完，电脑上新生成的主题，手机打开 Folia 就是同一套歌词动画和字体。
同步成功长什么样
做完后你看到两个画面：
- 客户端「测试」按钮提示测试成功；点「同步 AI 主题」后，界面汇报上传、下载的主题数和处理的桶数，「上次同步」显示时间戳
- 终端里
curl http://<服务地址>/health返回 200；不带 Token 访问其他接口一律 401
带着这两个验收标准往下做。
选一条部署路线
三条路线共用同一套路由和数据模型（实现在 sync-server/src/ 目录），客户端只管指向其中一个地址。
| 路线 | 适合谁 | 成本 | 一句话结论 |
|---|---|---|---|
| Cloudflare Workers | 没有服务器、不想运维 | 免费 | 一条脚本命令，自动建库、注入 Token 并上线 |
| Docker | 有 VPS 或 NAS 且装了 Docker | 用已有机器 | 宿主机13000端口，compose 一条命令 |
| Node 自托管 | 常开机器但不想装 Docker | 用已有机器 | 底层 better-sqlite3，默认3000端口 |
部署前需要准备的材料
| 材料 | 要求 | 为什么 |
|---|---|---|
SYNC_TOKEN | 8 位以上随机字符串，必填 | 客户端读写同步数据的凭证；少于 8 位服务端直接拒绝启动，防字典爆破 |
DASHBOARD_TOKEN | 16 位以上，选填 | 访问隐藏状态看板；不配就没有看板，不影响同步 |
| Node.js 24+ | 三条路线都要（Docker 仅构建镜像时） | 跑安装脚本和 Node 服务的硬性版本要求 |
| 密码管理器 | 无 | 存两把 Token |
生成 Token 有现成命令，浏览器按F12打开控制台执行：
crypto.randomUUID()Cloudflare 部署后 Token 会被加密存储、无法再回读明文，丢了只能重新部署。所以先把 Token 存进密码管理器，再开始部署。
Cloudflare Workers 一键部署步骤
菜单只需两次输入：SYNC_TOKEN一次、确认流程一次，其余自动化。
git clone https://gitcode.com/GitHub_Trending/fo/folia-major cd folia-major/sync-server bash ./install.shWindows 在 PowerShell 里执行.\install.ps1；被执行策略拦截时改用powershell -ExecutionPolicy Bypass -File .\install.ps1。菜单里输3。
脚本依次完成：创建 D1 数据库（Cloudflare 托管的 SQLite）→ 生成wrangler.local.toml→ 提示输入SYNC_TOKEN→ 自动生成DASHBOARD_TOKEN→ 发布。首次运行 Wrangler 会拉起浏览器要求登录授权，属正常现象。
结束确认两件事：
- 终端输出 Worker 域名和
DASHBOARD_TOKEN。DASHBOARD_TOKEN明文只显示这一次，没抄下来就只能重新部署换新的。两个值立刻存进密码管理器 - 脚本生成的
wrangler.local.toml内含你的数据库 ID，这个文件不要提交进任何仓库，泄露等于暴露数据库位置；它的作用只是下次重新部署时复用
Docker 一条命令起容器
在sync-server/下新建.env，只放必须字段：
# 必填：客户端鉴权 Token（至少 8 位） SYNC_TOKEN="你的SYNC_TOKEN" # 选填：看板访问 Token（至少 16 位） DASHBOARD_TOKEN="你的DASHBOARD_TOKEN"回仓库根目录启动：
docker compose -f deploy/docker/compose.sync.yaml up -d --buildToken 少于 8 位时容器会反复重启，docker logs folia-sync能看到报错原因，改完.env后重新 up 即可。
确认容器运行且13000端口已暴露：
curl -i http://127.0.0.1:13000/health出现HTTP/1.1 200即成功。数据库文件持久化在sync-server/data/folia-sync.db，迁移时打包整个sync-server/data目录即可。
Node.js 自托管最短路径
同样在sync-server/下建.env（PORT默认 3000、DB_PATH可选），然后：
cd sync-server npm install npm run start:node确认启动：
curl -i http://127.0.0.1:3000/health启动日志会打印端口和数据库路径；SQLite 文件默认生成在sync-server/目录里。机器需要常驻的话用 PM2 管理进程。
客户端连接同步服务并验证同步 🔑
打开 Folia 客户端，只需填两个字段、四步走完：
- 进入设置 → 存储设置 → 同步服务一节，打开「启用同步服务」开关
- 「Sync Server 地址」填服务的根地址（Worker 域名，或
http://NAS-IP:13000），后面不带任何路径；「Bearer Token」填SYNC_TOKEN，点保存 - 点「测试」：提示测试成功即连通；提示「连接失败或凭证无效」，按下面表格排查
- 点「同步 AI 主题」手动执行一次，界面汇报上传、下载的主题数和处理的桶数——看到数字说明链路全通，「上次同步」出现时间戳
验收排错：连通性验证与状况对照
连通性验证两条命令：
curl -i http://<服务地址>/health # 应返回 200 curl -i http://<服务地址>/state # 不带 Token，应返回 401| 状况 | 处理 |
|---|---|
SYNC_TOKEN忘了 | 明文只在部署当时显示一次，丢了只能重新部署注入新的；换新后把每台客户端的「Bearer Token」同步改掉，否则旧客户端全部报凭证无效 |
| 测试提示「连接失败或凭证无效」 | 三查：地址是否根地址（别带路径）、Token 是否完整复制、Docker 是否真把13000暴露出来 |
| 启动即报 Token 过弱 | 服务端硬性要求 8 位以上，改.env后重启进程或容器 |
| 服务暴露在公网 | 除/health外所有接口都要鉴权，泄露面不大；在 WAF/Nginx 层加频率限制更稳 |
| 想备份或迁移 | 同一设置界面有「导出 zip / 导入 zip」，同步已启用时导入内容会顺手推送到服务端 |
完整 API 表和手动部署细节在 sync-server/README.md，客户端协调逻辑集中在 src/services/sync/ 目录——每个主题按指纹归入 256 个 bucket，像按首字母归档的文件柜，客户端只拉变化的桶，几百首歌的主题也只传差量。五分钟搭好这套同步，从此一处生成、处处一致。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
