Folia 私有音乐播放器 NAS 部署教程：把家用 NAS 变成打开浏览器就能听歌的音乐站

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

把 Folia 私有音乐播放器架在 NAS 上，手机、电脑打开浏览器，网易云、酷狗、QQ 音乐和你自己的 Navidrome 曲库都能播，歌词还会全屏逐字动起来。整套 Docker 部署只带走仓库里 2 个文件、敲 4 条左右命令，占用 18080、13000 两个端口，配完之后你只需要记住一个网址。

Folia 部署后长什么样：多源曲库浏览与全屏歌词动画

首页是横向 3D 封面轮播，顶部搜索框直接搜三个在线源。点进歌曲，歌词进入全屏动画模式：

歌词动画不止一种风格，另一种偏海报式大字排版的效果长这样：

Folia Docker 部署清单：环境、端口与要带走的 2 个文件

NAS 终端里跑一条命令确认环境：

docker version && docker compose version

判断标准：Docker Engine 输出 24 及以上的版本号，docker compose version能正常输出一行 v2 信息。另外确认 18080、13000 两个端口没被其他服务占用。

部署不需要同整个源码，deploy/docker/ 目录下只需要带走两个文件：

提前知道 6 个容器的分工，排障时能省不少时间：

• gateway：Nginx 网关，唯一对外入口，占 18080
• backend：Web API（AI 主题、歌词分词），仅内网
• netease-api/kugou-api/qq-api：三个音乐源接口，仅内网
• sync-server：数据同步服务，占 13000

"仅内网"指这几个容器挂在 Docker 的internal: true网络上，外部无法绕过网关直接访问它们；Sync Server 更独立，挂在单独的folia-sync网络上。

Folia NAS 一条命令跑通：拉配置、生成令牌、点火启动

第 1 步：把两个文件弄到 NAS 上（约 1~2 分钟，看网速）：

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/之后不再需要。

第 2 步：生成同步令牌：

openssl rand -hex 32

判断标准：终端打印出一串 64 位十六进制字符。这是 Sync Server 的 Bearer 令牌，可以理解为客户端访问同步接口时出示的身份凭证。

第 3 步：写配置。打开.env，至少保证这两行有值：

FOLIA_IMAGE_NAMESPACE=papersman SYNC_TOKEN=粘贴第2步的64位字符串

FOLIA_IMAGE_NAMESPACE是镜像所在命名空间，模板已填好，保留即可。AI 密钥两行留空没关系，只是暂时用不了 AI 主题生成和歌词分词，播放照常。

第 4 步：校验并启动：

cd folia-docker docker compose config

判断标准：完整打印出展开后的 YAML，末尾没有required variable之类报错，说明.env解析通过。

docker compose pull

判断标准：依次拉下 folia-web、folia-web-api、folia-netease-api、folia-kugou-api、folia-qq-api、folia-sync-server 六个镜像。这是全程最慢的一步，首次拉镜像大小几百 MB，耐心等待。

docker compose up -d --wait

--wait会一直等到所有健康检查通过才返回。判断标准：命令无报错地结束，一般 1~3 分钟。

第 5 步：自检：

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，能看到首页就算部署成功。

Folia 配置速查：哪两个变量必填，哪几个可选

.env.example 里其余项保持默认即可，只有下表需要你亲自过一遍：

版本不用操心：不设FOLIA_STACK_VERSION就是latest。想固定版本就显式写出A.B.C标签，当前版本见 deploy/docker/VERSION。

接入自己的曲库：Navidrome 账号手动填还是服务端预置

前提：你的音乐文件已经由一个 Navidrome 实例托管（Navidrome 负责管理本地音乐文件和元数据）。没有就先部署一个，这一步与 Folia 无关。

在线源的登录很简单：页面上对应标签页里扫码即可，QQ 音乐支持手机 QQ 扫码和微信扫码。想让"自己的歌"进场，Navidrome 有两条连接路径：

• 手动填：在 Folia 的 Navidrome 设置页填地址（例如http://NAS-IP:4533）和账号密码，测试通过即可。适合只在一两台设备上用。代价是每台设备（手机、电脑）都要重复填一遍。
• 服务端预置：.env里填NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，之后新打开的浏览器自动登录。注意NAVIDROME_URL必须写成各设备都能直连的地址，不能写 Docker 内部主机名；改完执行docker compose up -d --force-recreate backend。

预置有代价要知道：凭据默认只下发给局域网来源（NAVIDROME_PRESET_ALLOW=private），能打开 Folia 页面的人理论上都能读到这组账号密码，建议在 Navidrome 里单建一个专用账号给 Folia 用。

为什么要把 Folia 放到带域名的 HTTPS 后面：三件配套配置

http://NAS-IP:18080能搜能播，但局域网 IP + HTTP 不属于浏览器"安全上下文"，这几项能力直接缺席：

• 本地音乐目录导入（File System Access API）
• PWA 安装与离线运行
• 音频输出设备选择
• 标准剪贴板复制

想让本地音乐进场，就靠 NAS 上现成的反向代理（Nginx Proxy Manager、Caddy、Traefik 都行）终止 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，否则局域网访问限制看到的永远是代理地址。

两点提醒：应用不支持挂在/folia/子路径下，建议独立子域；HTTP 和 HTTPS 是两个独立 origin，切过去后旧的 IndexedDB、登录态、本地曲库索引不会自动迁移，重新登录一次即可。

Folia 日常运维速记：更新、回滚、备份五个常用动作

# 更新：latest 不会自动拉新，必须手动执行 docker compose pull docker compose up -d

# 回滚：.env 里加一行 FOLIA_STACK_VERSION=1.2.2（历史版本自行填 A.B.C），再跑上面两条

# 备份：数据全在 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

# 查日志与健康检查 docker compose ps docker compose logs --tail=200 gateway backend netease-api kugou-api qq-api 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

# 重置 QQ 装置身份（换设备注册时才需要） docker compose down docker volume rm folia_qq-api-state docker compose up -d --wait

装置状态存在具名卷qq-api-state里，正常更新镜像跨重启复用，不需要动它。

Folia 部署排错：6 个高频问题的现象、原因与解法

1.docker compose up直接报Set SYNC_TOKEN to at least 8 characters现象：启动命令当场报错退出。原因：SYNC_TOKEN为空或少于 8 位；FOLIA_IMAGE_NAMESPACE缺失也会触发同样的硬性校验。解法：openssl rand -hex 32生成 64 位字符串填进.env，再执行docker compose up -d --wait。

2. 网关反复重启，日志提示端口冲突现象：18080 起不来，docker compose ps里 gateway 状态是restarting。原因：NAS 上已有别的服务占了 18080。解法：.env里把FOLIA_HTTP_PORT改成空闲端口（如18081），docker compose up -d重建。

3. 网页能打开，但某个在线源搜索没结果现象：只有单一音源无结果或超时，其他源正常。原因：对应 API 容器不健康，或上游在限流。解法：先docker compose ps确认容器 healthy，再看docker compose logs --tail=200 netease-api（换成对应服务名）里的上游报错；限流一般隔几分钟再试即可恢复。

4. 改了FOLIA_AI_PROVIDER或 Navidrome 账号，界面没变化现象：.env改完刷新页面，行为还是旧的。原因：环境变量只在容器重建时重新注入。解法：执行docker compose up -d --force-recreate gateway backend再刷新页面。

5. QQ 扫码总是提示装置异常，重新扫码也没用现象：反复出现装置类报错，换网络也一样。原因：装置状态卷里残留的旧状态与新设备冲突。解法：执行上面运维速记里的"重置 QQ 装置身份"三条命令，下次扫码会以新装置身份注册。

6. 预置的 Navidrome 不自动登录，新浏览器还要手动填现象：.env三项都填了，新设备打开仍是未登录状态。原因：三项必须同时完整，且NAVIDROME_URL要是浏览器能直连的完整 http(s) 地址，缺一项或地址不通，backend 日志会有警告，预置静默不生效。解法：补齐三项并核对地址，docker compose up -d --force-recreate backend，再看docker compose logs backend确认警告消失。

下一步：官方文档与版本信息

到这里，NAS 上已经跑着整套多源播放 + 全屏歌词动画的 Folia 私有音乐站。更完整的环境变量表、QQ 登录态持久化和本地镜像验证方法，看官方文档 deploy/docker/README.md；镜像与版本信息见 deploy/docker/VERSION。

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