企业官网建设流程全解析

Folia 同步服务免费部署完全指南：多端 AI 主题外观一致

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

Folia 是一款主打绚丽歌词动画效果的本地音乐播放器。本文带你免费部署它的官方 sync-server：完成后，同一账号下所有设备的 AI 主题与外观设置自动保持一致，不用再逐台重调。

先选定部署路线

三条路线共用同一套路由与数据模型：Node 入口是sync-server/src/node.ts，Cloudflare 入口是sync-server/src/cloudflare.ts，核心路由在sync-server/src/app.ts，换路线不影响客户端行为。没有服务器就直接选 Cloudflare，有服务器则按你更熟悉的工具选即可。

路线一：用一条脚本部署到 Cloudflare Workers（推荐）

前提：一个 Cloudflare 账号，本机可用 Node.js 24+ 与 npm。

第 1 步，获取源码。

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

部署脚本就放在仓库的sync-server/子目录里。

第 2 步，运行脚本并在菜单里选 Cloudflare 流程。

bash ./install.sh

Windows 上改用 PowerShell 执行.\install.ps1。菜单有三个选项：1) Node (PM2)、2) Docker、3) Cloudflare Workers（菜单定义见 sync-server/install.sh），输入3走本路线。首次运行时 Wrangler 可能要求跳转浏览器登录 Cloudflare 授权，属于正常现象。

第 3 步，按提示注入凭证并发布。

脚本会自动创建 D1 数据库并生成wrangler.local.toml，然后提示你输入SYNC_TOKEN，粘贴提前生成的即可；DASHBOARD_TOKEN会自动生成。脚本结束时输出 Worker 域名和DASHBOARD_TOKEN，两者都是后文接入要用的凭证，随手记下。

⚠️ 生成的wrangler.local.toml内含你的数据库 ID，只作为本地文件保留，不要提交到仓库（配置模板是 sync-server/wrangler.toml）。

路线二：用 Docker 在你自己的服务器上部署

第 1 步，在sync-server/下创建.env文件，写入：

SYNC_TOKEN=你的Token DASHBOARD_TOKEN=你的Token # 可选

第 2 步，回到仓库根目录，构建并后台启动：

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

该命令会构建镜像并拉起容器。服务监听宿主机13000端口（容器内 3000），SQLite 数据库持久化在sync-server/data/folia-sync.db。

⚠️ 部署在远程机器上时，确认13000端口真实暴露，否则客户端永远连不上。若要部署含在线音乐的 Folia 完整 Web 栈，改用deploy/docker/compose.yaml，同步服务仍对外提供13000端口的/health健康检查。

路线三：用 Node.js 自托管

第 1 步，在sync-server/.env写入三项：SYNC_TOKEN、PORT（默认 3000）、DB_PATH。

第 2 步，安装依赖并启动：

cd sync-server npm install npm run start:node

两个注意点：要求 Node.js 24+（数据库层是 better-sqlite3，含原生绑定）；不想手动跑的话，install.sh的选项 1 会自动装依赖并用 PM2 托管，连日志轮转都配好了。

通用准备：生成两个 Token 并接入客户端

先备好两个 Token

两种最快的生成方式：按F12打开浏览器控制台，运行crypto.randomUUID()；Linux/macOS 终端则执行openssl rand -hex 16。服务端会强制SYNC_TOKEN长度不小于 8 位，否则拒绝启动，目的是挡掉字典爆破。

⚠️ 生成后立刻把两个 Token 存入密码管理器。Cloudflare 部署中 Token 加密存储、无法回读：DASHBOARD_TOKEN丢失只能重新部署注入新的；SYNC_TOKEN忘记则必须重新生成，并同步更新所有客户端的配置。

客户端接入只需要两个字段

1. 打开设置 → 连接与集成，找到「同步服务」区块，打开启用开关
2. 在「Sync Server 地址」填入服务根地址（你的 Cloudflare 域名，或http://NAS-IP:13000，不带路径后缀），在「Bearer Token」填入SYNC_TOKEN，点击保存
3. 点击测试，出现绿色对勾即连通 ✅
4. 点同步 AI 主题立即跑一次同步；此后每次启动 Folia 都会自动增量同步，界面显示「上次同步」时间

连通性验证：「测试」按钮就是连通性检查，服务端另提供/health端点（Docker compose 的健康检查即用它）。失败不必猜，直接对照下文的速查表对号入座。

功能原理速览：同步数据怎么跑、怎么保安全

• 增量差量，只传变化：主题按指纹分入 256 个 bucket，两端只比对桶的摘要哈希，几百首歌也只传差量部分（实现见 src/services/sync/syncMerkle.ts）
• 时间戳仲裁，互不覆盖：批量写入按时间戳判断新旧，只采纳更新的记录，两端各改各的不会互相冲掉（协议定义见 src/services/sync/syncTypes.ts）
• 只读状态看板：部署时配置了DASHBOARD_TOKEN后，访问你的域名/?token=你的Token可看主题数量与最近更新时间，页面无任何敏感交互
• zip 导入/导出：同一界面提供「导出 zip / 导入 zip」，能把整份同步库备份成文件、脱离服务端迁移到另一台电脑；若同步已启用，导入的内容也会推送到服务端

常见问题速查：按现象对号入座

到这里，跨设备同步就闭环了：电脑上新生成一个 AI 主题，手机上打开 Folia 就是同款外观，歌词动画、字体、背景全部一致。想深挖协议细节，完整说明在 sync-server/README.md；客户端同步源码集中在src/services/sync/目录，随时可以翻看。

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