企业官网建设流程全解析

Folia sync-server 自托管完整指南：Docker 与 Node + SQLite 多端同步实战

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

Folia 是一款以歌词动画著称的开源音乐播放器，官方 sync-server 让你自托管一套多端同步后端：AI 生成的主题与视觉设置在所有设备间实时同步，数据完全由你自己掌握。

先搞懂：它能同步什么

在动手之前，先确认这个服务到底替你同步了什么。

• 视觉设置快照：按时间戳拉取/推送，旧时间戳永远不会覆盖新数据
• AI 生成的主题：固定 256 个 bucket 的增量同步，换设备后只拉取缺的部分
• 隐藏网页看板：带 Token 的浏览器页面，一眼看到主题数量与最近更新时间

服务端核心实现在 sync-server/src/app.ts（Hono 路由、Bearer 鉴权与全部同步 API），客户端对应的协议逻辑在 src/services/sync/，两端完全对齐。

开工前：先生成两个 Token

无论走哪条部署路线，都要先备好两个 Token：

一行命令生成高强度随机 Token：

openssl rand -hex 16

执行后会输出一串 32 位十六进制字符，复制下来备用。

⚠️ 服务端强制要求SYNC_TOKEN长度 ≥ 8 位，过短会直接拒绝启动。另外 Token 通常只在部署时明文显示一次，请立即存入密码管理器。

Docker 路线：五步跑通

有 VPS 或 NAS 的话，这条路线最省心，全程只需四条命令。

第 1 步：克隆仓库。

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

第 2 步：写.env。进入sync-server目录新建.env文件：

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

第 3 步：compose 一键启动。回到仓库根目录执行：

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

首次运行会先构建镜像再启动，稍等片刻。

第 4 步：验证/health。浏览器访问http://你的服务器IP:13000/health，返回 JSON 即部署完成。

第 5 步：确认持久化。数据库落在sync-server/data/folia-sync.db，重启容器不丢数据。

这套编排在 deploy/docker/compose.sync.yaml 中定义，几个关键行为值得知道：

• 容器内监听3000，映射到宿主机13000端口
• 内置健康检查，每15 秒自动探测一次/health
• read_only文件系统 +no-new-privileges容器加固

💡 如果你还需要完整 Web 堆栈（Web 版 Folia + 在线音乐 API），改用 deploy/docker/compose.yaml 即可。

没有 Docker？用 Node 顶上

个人电脑或轻量 VPS 上装不了 Docker，直接用 Node.js 跑也一样。底层是better-sqlite3，与 Docker 版共用同一套路由和表结构，数据模型完全同构，随时可以互相迁移。

前置要求：

• Node.js ≥ 24（与 sync-server/package.json 的 engine 声明一致）
• npm

在sync-server目录下创建.env：

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

安装依赖并启动：

npm install npm run start:node

终端出现 ASCII 风格的 "FOLIA SYNC SERVER" Logo、并打印端口与数据库路径，即启动成功。

不想手动配置？官方安装向导 sync-server/install.sh（Windows 用 install.ps1）提供 Node (PM2) / Docker / Cloudflare 三选一菜单，会自动生成.env和看板 Token。

长期挂机建议用 PM2 守护 Node 进程：

pm2 start "npx tsx src/node.ts" --name folia-sync

把客户端接上，验证成果

在 Folia 客户端打开存储设置，填写两项：

• workerBaseUrl：服务根地址，例如http://127.0.0.1:13000
• SYNC_TOKEN：前面生成的 Token，客户端通过Authorization: Bearer发送

常用 API 一览（除/health外均需要SYNC_TOKEN鉴权）：

配置了DASHBOARD_TOKEN时，用浏览器访问http://你的服务地址/?token=你的DASHBOARD_TOKEN，看板只读展示主题数量与最近更新时间，适合日常一眼确认服务状态。

部署之后：日常维护与排坑

忘记看板 Token 怎么办？

重新生成DASHBOARD_TOKEN并重启服务即可。但注意SYNC_TOKEN一旦重置，所有已接入的客户端配置都要同步更新。

暴露公网安全吗？

建议在 Nginx/WAF 边缘层配置频率限制（Rate Limiting）防字典爆破；如果只同步内网设备，让服务留在局域网内最稳妥。

想要免费 Serverless？

官方还推荐 Cloudflare Workers + D1 路线：免费、免运维，仓库提供了自动创建数据库、注入 Secret 的一键安装脚本，详见 sync-server/README.md。

核心文件速查：

现在，你手里已经有一套完全可控的多端同步服务。换机重装、设备切换，视觉设置和收藏的 AI 主题都能一键找回。下一步可以试试在两台设备间各存一个主题，看它们如何在几秒内互相出现。

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