Folia 自托管同步服务：Docker 与 Node.js 两条路线部署完整指南

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 路由，同时支持三种运行形态，按你的环境对号入座：

Cloudflare 路线由安装脚本里的第 3 项菜单驱动，会自动创建 D1 数据库并注入密钥，细节以 sync-server/README.md 最新说明为准。下面两条路线的数据模型完全同构——同一套表结构、同一份路由，SQLite 文件拷走即可互迁。

生成两个 Token 并存进密码管理器

无论走哪条路线，服务端都靠两个环境变量运转：

任选一条命令生成高强度随机串：

openssl rand -hex 16

没有 OpenSSL 的终端可以换用 Node 一行式：

node -e "console.log(crypto.randomBytes(16).toString('hex'))"

⚠️SYNC_TOKEN短于8位时服务会直接拒绝启动，终端报 "SYNC_TOKEN is too weak"；Token 只在生成时明文出现这一次，建议立刻存入密码管理器。

路线 A · 用 Docker 三步拉起容器服务

克隆仓库并写入 .env

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

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

SYNC_TOKEN="你的随机字符串" DASHBOARD_TOKEN="你的随机字符串"

在仓库根目录构建并启动容器

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

启动后的默认行为都写在 deploy/docker/compose.sync.yaml 里：容器内部监听3000端口，映射到宿主机13000；SQLite 数据库落在sync-server/data/folia-sync.db，重启不丢数据；容器以read_only+no-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/目录下创建.env：

SYNC_TOKEN="你的SYNC_TOKEN" DASHBOARD_TOKEN="你的DASHBOARD_TOKEN" PORT=3000 DB_PATH="./folia-sync.db"

PORT与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:13000（Docker 路线）或http://127.0.0.1:3000（Node 路线）
• 鉴权 Token：填入SYNC_TOKEN，客户端会以Authorization: Bearer头随每次请求发送

先点「测试」按钮确认连通，成功后保存配置，再点「同步主题」和「同步视觉设置」各触发一次。页面还提供了「导出 zip」「导入 zip」，用于把完整主题库打包搬运。

首次同步完成后，新设备上的 AI 主题立刻可用，效果类似这样：

同步过程中实际走的接口，服务端实现在 sync-server/src/app.ts：

打开隐藏看板确认数据在流动

配置过DASHBOARD_TOKEN时，在浏览器访问：

http://你的服务地址/?token=你的DASHBOARD_TOKEN

Token 正确会看到黑色极简页面，展示已同步主题数、主题最近更新时间、设置最近更新时间三项指标；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.yaml：Docker 独立编排文件

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