Folia NAS 部署完整教程：一条命令拉起三大在线音源与私有曲库

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

Folia 是一款以全屏歌词动画为核心的私有音乐播放器，Folia 部署到 NAS 后，手机、平板、电脑打开同一个地址，就能同时听网易云、酷狗、QQ 音乐，还能把 Navidrome 托管的本地曲库接进来，歌词随播放逐字点亮。整个编排方案由仓库里的 deploy/docker/compose.yaml 定义，对外只暴露两个端口，全部数据都留在你自己的机器上。

跑起来之后是一个由 6 个容器组成的栈，先记住这张分工表，排障时按它对号入座：

开始前问自己三个问题：环境和端口

动手前把环境核对一遍，能省掉后面 80% 的来回折腾。

docker version docker compose version

判断标准：第一条输出 Client 版本为 24 及以上；第二条能打出v2.x.x版本号。只装过docker-compose1.x 的老环境需要先升级到 Compose v2。

再看两个端口有没有被占：

ss -ltnp | grep -E ":(18080|13000)"

判断标准：没有任何输出说明 18080（Web）和 13000（Sync）都空闲，直接往下走；有输出就记下是哪个服务占着，稍后在.env里把FOLIA_HTTP_PORT/FOLIA_SYNC_PORT改成空闲端口即可。

从仓库取两个部署文件：不需要源码

部署不跑源码，只取编排文件和配置模板这两样东西。

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

mkdir -p folia-docker cp folia-major/deploy/docker/compose.yaml folia-docker/ cp folia-major/deploy/docker/.env.example folia-docker/.env

判断标准：folia-docker/里只有compose.yaml和.env两个文件。之后所有命令都在这个目录里执行，克隆下来的folia-major/目录不再需要。

.env 里 2 个必填项怎么填，外加 4 个可选项

进入目录后，先生成 Sync Server 的访问令牌：

openssl rand -hex 32

判断标准：终端打出一串 64 位十六进制字符串，把它填进.env，保证这两行有值：

FOLIA_IMAGE_NAMESPACE=papersman SYNC_TOKEN=上一步的64位字符串

为什么要手动生成：Compose 对这两项做了硬性校验，缺一个就直接拒绝启动；SYNC_TOKEN同时是 Sync 客户端的 Bearer 凭证，相当于密码，别用弱口令。

其余项保持默认即可，下表是仅有的几个需要你过目的值：

版本不用动：FOLIA_STACK_VERSION不设置就是latest。想锁版本就显式写一个A.B.C标签，当前版本为 1.2.2，以仓库 deploy/docker/VERSION 为准。

拉起六容器栈并确认健康检查全绿

三条命令依次执行，每条都有明确的成功信号。

docker compose config

判断标准：完整展开一份 YAML 且末尾无报错，说明.env解析通过。

docker compose pull

判断标准：依次拉取 folia-web、folia-web-api、folia-netease-api、folia-kugou-api、folia-qq-api、folia-sync-server 共 6 个镜像，速度取决于 NAS 的网络。

docker compose up -d --wait

--wait会阻塞到所有健康检查通过才返回，不用手动估时间，冷启动一般 1~2 分钟。

判断标准：docker compose ps里 6 个服务的 STATUS 全部是(healthy)，没有restarting。再用两条 curl 从用户视角确认：

curl http://NAS-IP:18080/healthz curl http://NAS-IP:13000/health

第一条返回{"ok":true,"service":"folia-gateway"}，第二条返回 200，就可以打开浏览器访问http://NAS-IP:18080了。

在线音源零配置：打开页面直接扫码

在线源不需要任何环境变量，页面上对应标签页里直接扫码登录即可：网易云、酷狗按提示操作；QQ 音乐支持手机 QQ、微信、QQ 音乐 App 三种扫码方式。

QQ 的装置状态保存在qq-api-state卷里，跨容器重启自动复用，所以正常更新镜像后不需要重新注册装置。

接入 Navidrome 曲库：告别每台设备重新填账号

前提是你的音乐文件已经由一个 Navidrome 实例托管（它负责扫描文件和维护元数据）。Folia 提供两条连接路径，按需求二选一：

• 手动填：在 Folia 的 Navidrome 设置页填地址和账号，测试通过即可。缺点是手机、电脑、电视各填一遍。
• 服务端预置（推荐）：在.env里同时填NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，之后新打开的浏览器会自动登录：

NAVIDROME_URL=http://NAS-IP:4533 NAVIDROME_USERNAME=folia NAVIDROME_PASSWORD=你的密码

改完执行下面命令让 backend 重新加载：

docker compose up -d --force-recreate backend

判断标准：重新打开浏览器后 Navidrome 标签页已自动进入登录态。

两个注意点：NAVIDROME_URL必须写成每台设备都能直连的地址，不能写 Docker 内部主机名；Folia 走 HTTPS 时这里也得是 HTTPS，否则浏览器会拦截混合内容。另外预置凭据默认只下发给局域网来源（NAVIDROME_PRESET_ALLOW=private），理论上能打开 Folia 页面的人都能读到它，建议在 Navidrome 里单独建一个账号专供 Folia 使用。

挂上 HTTPS：解锁本地曲库与离线能力的三件配套事

http://NAS-IP:18080搜索、播放都没问题，但局域网 IP 加 HTTP 不属于浏览器的"安全上下文"，下面这些能力会直接缺席：本地音乐目录导入（File System Access API）、PWA 安装与离线运行、音频输出设备选择、标准剪贴板复制。

想解锁，就让 NAS 上现成的反向代理（Nginx Proxy Manager、Traefik、Caddy 均可）终止 HTTPS：

https://folia.example.com/ -> http://127.0.0.1:18080 https://sync.example.com/ -> http://127.0.0.1:13000

三件配套的事缺一不可：

1. 证书必须是浏览器信任的完整证书链，自签名证书不算数；
2. 代理要转发Host、X-Forwarded-Host、X-Forwarded-Proto: https、X-Forwarded-For，并把 HTTP 请求重定向到 HTTPS；
3. 在.env里把FOLIA_HTTP_BIND、FOLIA_SYNC_BIND改成127.0.0.1防止绕过代理直连，同时把代理自己的确切地址填进FOLIA_TRUSTED_PROXIES（这一项不接受整个局域网段）。

提醒一句：HTTP 和 HTTPS 是两个独立的 origin，切过去之后旧的 IndexedDB、登录态、本地曲库索引不会自动迁移，需要重新登录一次。

长期运营：更新、回滚、备份、健康检查全在这里

更新（latest标签不会被 Docker 自动拉新，必须手动执行）：

docker compose pull docker compose up -d

回滚：在.env里加一行FOLIA_STACK_VERSION=加一个先前的A.B.C标签（当前为 1.2.2，历史标签以 deploy/docker/VERSION 核对），再重复上面两条命令。

备份：全部数据在FOLIA_SYNC_DATA_DIR（默认./data/sync），停服打包最稳妥：

docker compose stop sync-server tar -czf folia-sync-backup.tar.gz ./data/sync docker compose start sync-server

日常健康检查，四个端点加一条日志：

curl http://127.0.0.1:18080/healthz curl http://127.0.0.1:18080/api/healthz curl http://127.0.0.1:18080/qq/login/status curl http://127.0.0.1:13000/health

docker compose logs --tail=200 gateway backend netease-api kugou-api qq-api sync-server

重置 QQ 装置身份（换设备注册、装置状态异常时才需要）：

docker compose down docker volume rm folia_qq-api-state docker compose up -d --wait

排障速查：症状、原因、处理一张表

更多环境变量细节、独立服务说明和网络隔离设计，见官方文档 deploy/docker/README.md。

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