企业官网建设流程全解析

Folia 私有音乐播放器 NAS 部署指南：一条命令拉起多源播放与全屏歌词动画

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

Folia 是一款以全屏歌词动画为核心的在线音乐播放器，这篇 Folia NAS 部署教程把它整套搬上 Docker：网易云、酷狗、QQ 音乐，外加你自己的 Navidrome 曲库，手机、平板、电脑打开同一个地址就能听，歌词跟着旋律逐字点亮。写配置加启动大约 5 分钟，镜像拉取时间另算。

部署前核对清单

在 NAS 终端里逐项过一遍，全部满足再往下走：

材料只缺仓库里的两个文件，不用下载完整源码：

模板里其余值保持默认即可，只有下面这几项需要你亲自过一遍：

FOLIA_STACK_VERSION不设置就是latest；想固定版本，对照 deploy/docker/VERSION 里的当前标签，显式写出A.B.C即可。

部署主线：5 步把容器跑起来

第 1 步——取文件。整套部署只需要编排文件和配置模板，clone 仓库后拷出这两个文件就够了。

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 步——生成同步令牌。SYNC_TOKEN是模板里唯一的硬性必填项，缺了容器直接起不来。

openssl rand -hex 32

把输出粘贴进.env，至少保证这两行有值：

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

两行都有值即通过。GEMINI_API_KEY、OPENAI_API_KEY留空没关系——只是暂时用不了 AI 主题生成和歌词分词，播放完全不受影响。

第 3 步——干跑一次配置。先让 Compose 展开一遍 YAML，语法错误在拉镜像之前就能暴露。

cd folia-docker docker compose config

完整输出展开后的 YAML、末尾无报错即通过。若报required variable ... is missing a value，错误信息会指向.env的具体行，对照上面的表格补齐。

第 4 步——预拉镜像。提前把 6 个镜像拉下来，启动那一步就不会卡在网络下载上。

docker compose pull

输出里依次出现 folia-web、folia-web-api、folia-netease-api、folia-kugou-api、folia-qq-api、folia-sync-server 六个镜像即通过；任何一个失败，下一步都会卡住。

第 5 步——启动并等健康检查。--wait会阻塞到所有健康检查转绿才返回，命令一回来就说明容器已就绪。

docker compose up -d --wait

命令正常返回即通过，冷启动一般 1~2 分钟。若长时间不返回，跑一次docker compose ps看哪个服务停在starting或restarting，再进该服务的日志定位。

跑起来之后

6 个容器分工明确，先记一下，后面排障全靠这张表：

三个音乐源接口全部挂在 Docker 内部网络folia-internal（internal: true）上，外部无法绕过网关直接摸到它们。

宿主机侧先看服务状态：

docker compose ps

6 个服务的 STATUS 列全部是(healthy)、没有restarting才算齐。

再从用户视角探两针：

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

第一条应返回{"ok":true,"service":"folia-gateway"}，第二条返回 200 即代表 Sync Server 就绪。最后浏览器打开http://NAS-IP:18080，首页正常加载，部署就算完成。

在线源：扫码即登。打开页面，到对应标签页扫码即可；QQ 音乐支持扫码和微信扫码两种方式。登录成功后，全屏歌词动画随播放逐字点亮：

私有曲库：接上 Navidrome。想让"自己的歌"进场，需要一个 Navidrome 实例托管音乐文件（没有就先部署一个，它负责文件与元数据管理）。Folia 有两条连接路径，按需求二选一：

• 手动填：在 Folia 的 Navidrome 设置页填地址（如http://NAS-IP:4533）和账号密码，测试通过即可。代价是手机、电脑每个浏览器都要各填一遍。
• 服务端预置：在.env里填NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，之后新打开的浏览器自动登录。NAVIDROME_URL必须写成各设备都能直连的地址，不能填 Docker 内部主机名。填完让 backend 重建一次：

docker compose up -d --force-recreate backend

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

从局域网到正式环境

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 compose pull docker compose up -d

回滚。在.env中加一行FOLIA_STACK_VERSION，设为之前使用的A.B.C标签（对照 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

查日志与健康检查。状态、日志、探针一次看齐：

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 装置身份。装置状态存放在qq-api-state卷里，跨重启复用；换设备注册想从头来时，删掉该卷，下次扫码就以新装置身份注册：

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