Folia sync-server 完整部署指南多设备共用一套 AI 主题外观免重复配置【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFolia 官方自带的 sync-server 让「每台设备都重调一遍主题」成为历史把它部署到任意一台机器上多台客户端接入同一个同步服务AI 主题与外观设置就全部打通。本文按「备料 → 部署 → 配对 → 验证」的操作顺序走完整个流程最后覆盖故障排查、隐藏看板和 zip 备份。先搞清楚同步到底同步什么同步范围分两块字段定义在 src/services/sync/syncTypes.ts外观设置快照可视化模式、背景与透明度、字幕样式、歌词字体、首页布局等。两端记录按updatedAt时间戳比对较新的记录生效改过的一端不会被另一端旧数据覆盖。AI 主题库每首歌曲的主题带稳定指纹先归入固定 256 个 bucket只比较各桶的摘要哈希实现在 src/services/sync/syncMerkle.ts。哪个桶变了才拉取哪个桶的内容几百首歌曲的主题实际只传输差量。sync-server 只做主题和外观的中转曲库文件不经过它。部署前准备生成并保存两个 TokenToken用途必填长度要求SYNC_TOKEN客户端读写同步数据的鉴权是最短 8 位建议 8~32 位随机字符低于 8 位服务直接拒绝启动用于防字典爆破DASHBOARD_TOKEN访问隐藏的网页状态看板否建议 16 位以上随机字符在 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.shWindows 用户在 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忽略不要提交进任何仓库。DockerVPS/NAS 上一条 compose 启动在sync-server/下新建.env写入SYNC_TOKEN必填与可选的DASHBOARD_TOKENSYNC_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/下建.envSYNC_TOKEN你的TOKEN PORT3000 DB_PATH./folia-sync.db安装依赖并启动npm install npm run start:nodePORT默认 3000DB_PATH不写则默认在当前目录生成数据库文件。需要长期运行时可交给 PM2 或 Docker 托管。客户端配对填两栏、点两次打开 Folia 的设置 → 存储设置 → Sync Server一节打开「启用同步服务」开关「Sync Server URL」填根地址URL 不带任何路径后缀Cloudflare 域名或http://NAS-IP:13000均可「Bearer Token」填SYNC_TOKEN保存点「测试」按钮测试结果通过即代表连通成功随后点一次「同步 AI 主题」手动执行全量同步。此后每次启动 Folia 都会自动做增量同步界面上能看到「上次同步」时间戳。故障排查对照表症状排查与处理SYNC_TOKEN忘了部署时明文只显示一次部署后不可回读Cloudflare 加密存储重新部署注入新 Token并把所有客户端的配置同步更新「测试」连接不通过逐项核对URL 是否为不带路径的根地址Token 是否完整复制Docker 部署时宿主机13000端口是否真正对外暴露公网被扫描或高频请求在 WAF 或 Nginx 边缘层加频率限制除GET /health外所有接口都要求 Bearer 鉴权暴露面有限进阶隐藏看板与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考