企业官网建设流程全解析

5 分钟跑通 Folia sync-server 自托管：Docker 与 Node 两条路线实测

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

换了新电脑，Folia 里收藏的 AI 主题和歌词动画却留在了旧机器上——这就是 Folia sync-server 要解决的问题。它是官方提供的同步后端，把视觉设置快照和 AI 生成主题在多端之间同步，自托管（把服务部署在自己的机器上）支持 Docker 与 Node.js 两种路线，5 分钟就能跑通。

30 秒选路线

不想常驻服务器的话，官方还提供 Cloudflare Workers + D1 的 Serverless 路线，免费且带一键脚本自动建库、注入 Secret，本文不展开。

动手前：一行命令生成两个 Token

无论走哪条路线，先执行下面这行命令，生成高强度随机串：

openssl rand -hex 16

两类 Token 的用途如下：

⚠️ 服务端强制要求SYNC_TOKEN长度 ≥ 8 位，不达标会直接拒绝启动。Token 生成后只明文出现这一次，请立即存入密码管理器。

路线 A：Docker 部署

克隆仓库，进入sync-server目录：

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

创建.env文件，填入两个 Token：

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

回到仓库根目录，执行构建并启动（编排文件为deploy/docker/compose.sync.yaml）：

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

启动后核对三个关键点：

• 容器监听 3000，映射到宿主机13000端口
• 数据库持久化在sync-server/data/folia-sync.db，重启不丢数据
• 每 15 秒自动探测/health，容器另启用read_only与no-new-privileges加固

路线 B：Node.js + SQLite 部署

先确认 Node 版本满足Node.js ≥ 24（与package.json的 engines 声明一致）：

node -v

在sync-server目录创建.env：

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

安装依赖并启动，存储层由better-sqlite3承担：

npm install npm run start:node

💡 终端打印出 "FOLIA SYNC SERVER" Logo 即启动成功。长期挂机建议用 PM2 托管；不想手动配置时，执行官方安装向导install.sh（Windows 用install.ps1），选 Node (PM2) 菜单会自动生成.env。

客户端接入与 30 秒验收

打开 Folia 客户端的存储设置，填入两项：

• workerBaseUrl：服务根地址。Docker 路线填http://你的服务器IP:13000，本机填http://127.0.0.1:3000
• Token：之前生成的SYNC_TOKEN，客户端通过Authorization: Bearer发送

浏览器访问http://你的服务地址:13000/health，返回含"ok": true的 JSON 即通过——这是唯一免鉴权接口。

服务同步三类内容：视觉设置快照按时间戳读写，旧时间戳不会覆盖新数据；AI 主题按 256 个 bucket 做增量同步，单批写入上限 500 条；配置了看板 Token 后，访问http://你的服务地址/?token=你的DASHBOARD_TOKEN可只读查看主题数量与最近更新时间。

常用端点一览：

避坑清单

• 忘记看板 Token？重新生成DASHBOARD_TOKEN并重启即可；但SYNC_TOKEN一旦重置，所有设备的客户端配置都要同步更新。
• 暴露公网安全吗？建议在 Nginx 或 WAF 层配置频率限制，防字典爆破；只在内网设备间同步时，别对外放端口最稳妥。
• 想省掉服务器成本？Cloudflare Workers + D1 是官方推荐的免费 Serverless 替代，仓库内置的脚本会自动创建数据库并注入 Secret。
• 两条路线能互换吗？能。同一套路由与表结构，迁移时搬走 SQLite 数据库文件、复用同一组 Token 即可。

写在最后

一个 Token、一份小服务，换机重装后主题与设置都能一键找回，数据文件就躺在你自己的磁盘上。

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