Folia 自托管同步服务Docker 与 Node.js 两条路线部署完整指南【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major把工作机上的 Folia 歌词动画调到顺手回家打开另一台电脑却要重新来过把 Folia Sync Server 部署到自己的机器上做成一个自托管同步服务视觉设置与 AI 主题就都落在自己的磁盘里。本文带你走通 Docker 与 Node.js 两条路线。为什么值得自建 Folia 同步服务Folia 客户端是本地优先设计AI 生成的主题和视觉设置默认只存在本机的 IndexedDB 里换机重装就意味着全部清零。自建一台同步服务后会发生什么换机、重装系统后主题库和视觉设置一键找回不用重新生成多台设备共用同一套主题与外观改动按时间戳互相覆盖旧数据不会回退新数据数据存在自己的硬盘或 NAS 上不经过任何第三方服务器顺带得到一个只读看板随时确认同步库里有几条主题、最近一次更新时间十分钟选定部署路线官方同一套 Hono 路由同时支持三种运行形态按你的环境对号入座路线适用场景前置门槛推荐指数Docker 容器VPS / NAS 长期挂机已装 Docker★★★★★Node.js SQLite个人电脑、不便装 Docker 的轻量 VPSNode.js ≥ 24 与 npm★★★★Cloudflare Workers无服务器、走 ServerlessCloudflare 账号按需见官方 READMECloudflare 路线由安装脚本里的第 3 项菜单驱动会自动创建 D1 数据库并注入密钥细节以 sync-server/README.md 最新说明为准。下面两条路线的数据模型完全同构——同一套表结构、同一份路由SQLite 文件拷走即可互迁。生成两个 Token 并存进密码管理器无论走哪条路线服务端都靠两个环境变量运转Token作用必填推荐长度SYNC_TOKEN客户端鉴权Folia 凭它读写同步数据是8 ~ 32位随机字符DASHBOARD_TOKEN浏览器隐藏看板入口防扫描否16位以上随机字符任选一条命令生成高强度随机串openssl rand -hex 16没有 OpenSSL 的终端可以换用 Node 一行式node -e console.log(crypto.randomBytes(16).toString(hex))⚠️SYNC_TOKEN短于8位时服务会直接拒绝启动终端报 SYNC_TOKEN is too weakToken 只在生成时明文出现这一次建议立刻存入密码管理器。路线 A · 用 Docker 三步拉起容器服务克隆仓库并写入 .envgit clone https://gitcode.com/GitHub_Trending/fo/folia-major cd folia-major/sync-server在sync-server/目录新建.envSYNC_TOKEN你的随机字符串 DASHBOARD_TOKEN你的随机字符串在仓库根目录构建并启动容器cd .. docker compose -f deploy/docker/compose.sync.yaml up -d --build启动后的默认行为都写在 deploy/docker/compose.sync.yaml 里容器内部监听3000端口映射到宿主机13000SQLite 数据库落在sync-server/data/folia-sync.db重启不丢数据容器以read_onlyno-new-privileges加固每15秒探测一次/health。 宿主机端口不想用 13000 的话启动前设置FOLIA_SYNC_PORT环境变量即可覆盖无需改编排文件。访问 /health 验证部署curl http://127.0.0.1:13000/health返回形如{ok:true,schemaVersion:1,backend:hono-sync}的 JSON即部署完成。路线 B · 用 Node.js 加 SQLite 直接跑确认运行环境sync-server/package.json的 engines 要求Node.js ≥ 24外加 npm。版本不够时npm install阶段的原生依赖编译容易翻车先升级再动手。写入 .env 四个键在sync-server/目录下创建.envSYNC_TOKEN你的SYNC_TOKEN DASHBOARD_TOKEN你的DASHBOARD_TOKEN PORT3000 DB_PATH./folia-sync.dbPORT与DB_PATH均可选默认值分别是3000与当前目录下的folia-sync.db。安装依赖并启动cd folia-major/sync-server npm install npm run start:node终端打印粉紫色的 FOLIA SYNC SERVER ASCII 标识、并列出 Port 与 Database 两行信息即启动成功。需要长期挂机时用 PM2 托管或直接跑 install.sh 选第 1 项 Node (PM2) 菜单它会自动装好 PM2、启动服务并配置日志轮转。底层存储是 better-sqlite3 之上的 D1 兼容层见 sync-server/src/d1-emulator.ts与 Docker 路线共用同一套路由和表结构两边随时可切换。把 Folia 客户端接进来并完成首次同步在 Folia 客户端打开「设置 → 连接与集成」页面翻到同步服务区块打开开关后填写两项workerBaseUrl服务根地址例如http://127.0.0.1:13000Docker 路线或http://127.0.0.1:3000Node 路线鉴权 Token填入SYNC_TOKEN客户端会以Authorization: Bearer头随每次请求发送先点「测试」按钮确认连通成功后保存配置再点「同步主题」和「同步视觉设置」各触发一次。页面还提供了「导出 zip」「导入 zip」用于把完整主题库打包搬运。首次同步完成后新设备上的 AI 主题立刻可用效果类似这样同步过程中实际走的接口服务端实现在 sync-server/src/app.ts方法路径用途GET/health连通性检查唯一免鉴权接口GET/PUT/settings按时间戳读取/更新视觉设置快照旧时间戳不覆盖新数据GET/themes/manifest读取固定256个主题 bucket 的摘要POST/themes/bucket按 bucket 增量拉取主题单次最多32个 bucketPOST/themes/put批量写入主题单批上限500条POST/themes/list游标分页导出完整主题库单页上限1000条打开隐藏看板确认数据在流动配置过DASHBOARD_TOKEN时在浏览器访问http://你的服务地址/?token你的DASHBOARD_TOKENToken 正确会看到黑色极简页面展示已同步主题数、主题最近更新时间、设置最近更新时间三项指标Token 错误则只返回 404不给扫描器留线索。页面只读没有敏感交互适合作为日常状态确认入口。排障速查现象启动即退出终端报 SYNC_TOKEN is too weak →原因Token 不足8位 →解法重新生成随机串覆盖.env后重启现象客户端点「测试」失败浏览器却打得开/health→原因workerBaseUrl填了尾部斜杠或端口填错Docker 路线应为13000→解法填服务根地址并核对宿主机端口、防火墙放行现象看板始终返回 404 →原因未配置DASHBOARD_TOKEN或查询参数里的 token 不匹配 →解法重新生成后重启服务再按/?token...访问现象换 Token 后部分设备不同步了 →原因SYNC_TOKEN变更后旧设备仍持旧值 →解法逐台设备更新「连接与集成」里的鉴权 Token现象旧设备的新改动没推到云端 →原因协议设计为旧时间戳不覆盖新记录 →解法等待该设备产生更新的updatedAt再推送属预期行为⚠️ 服务要暴露公网时建议在 Nginx / WAF 边缘层加频率限制Rate Limiting防字典爆破只在内网间同步的话让服务留在局域网里最稳妥。自托管同步服务搭好之后主题与设置就真正握在自己手里两台电脑之间换机重装一键找回全部状态。sync-server/README.md三条部署路线的完整文档src/services/sync/客户端同步协议实现deploy/docker/compose.sync.yamlDocker 独立编排文件【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考