Folia NAS 部署完整教程一条命令拉起三大在线音源与私有曲库【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFolia 是一款以全屏歌词动画为核心的私有音乐播放器Folia 部署到 NAS 后手机、平板、电脑打开同一个地址就能同时听网易云、酷狗、QQ 音乐还能把 Navidrome 托管的本地曲库接进来歌词随播放逐字点亮。整个编排方案由仓库里的 deploy/docker/compose.yaml 定义对外只暴露两个端口全部数据都留在你自己的机器上。跑起来之后是一个由 6 个容器组成的栈先记住这张分工表排障时按它对号入座容器对外端口角色gateway18080Nginx 网关唯一对外入口backend仅内网Web API负责 AI 主题生成与歌词分词netease-api/kugou-api/qq-api仅内网三个平台的接口挂在internal: true网络上外部无法绕过网关直连sync-server13000多设备数据同步数据落在./data/sync开始前问自己三个问题环境和端口动手前把环境核对一遍能省掉后面 80% 的来回折腾。docker version docker compose version判断标准第一条输出 Client 版本为 24 及以上第二条能打出v2.x.x版本号。只装过docker-compose1.x 的老环境需要先升级到 Compose v2。再看两个端口有没有被占ss -ltnp | grep -E :(18080|13000)判断标准没有任何输出说明 18080Web和 13000Sync都空闲直接往下走有输出就记下是哪个服务占着稍后在.env里把FOLIA_HTTP_PORT/FOLIA_SYNC_PORT改成空闲端口即可。从仓库取两个部署文件不需要源码部署不跑源码只取编排文件和配置模板这两样东西。git clone https://gitcode.com/GitHub_Trending/fo/folia-major folia-majormkdir -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_NAMESPACEpapersman SYNC_TOKEN上一步的64位字符串为什么要手动生成Compose 对这两项做了硬性校验缺一个就直接拒绝启动SYNC_TOKEN同时是 Sync 客户端的 Bearer 凭证相当于密码别用弱口令。其余项保持默认即可下表是仅有的几个需要你过目的值变量默认值用途不填会怎样FOLIA_HTTP_PORT18080Web 网关端口端口被占时需改成空闲值GEMINI_API_KEY/OPENAI_API_KEY空AI 主题生成与歌词分词这两个功能不可用播放不受影响NAVIDROME_URL/NAVIDROME_USERNAME/NAVIDROME_PASSWORD空Navidrome 服务端预置登录每台设备都要手动填一次账号FOLIA_TRUSTED_PROXIES空前面挂了反向代理时填代理地址局域网访问限制看到的是代理 IP版本不用动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_URLhttp://NAS-IP:4533 NAVIDROME_USERNAMEfolia NAVIDROME_PASSWORD你的密码改完执行下面命令让 backend 重新加载docker compose up -d --force-recreate backend判断标准重新打开浏览器后 Navidrome 标签页已自动进入登录态。两个注意点NAVIDROME_URL必须写成每台设备都能直连的地址不能写 Docker 内部主机名Folia 走 HTTPS 时这里也得是 HTTPS否则浏览器会拦截混合内容。另外预置凭据默认只下发给局域网来源NAVIDROME_PRESET_ALLOWprivate理论上能打开 Folia 页面的人都能读到它建议在 Navidrome 里单独建一个账号专供 Folia 使用。挂上 HTTPS解锁本地曲库与离线能力的三件配套事http://NAS-IP:18080搜索、播放都没问题但局域网 IP 加 HTTP 不属于浏览器的安全上下文下面这些能力会直接缺席本地音乐目录导入File System Access API、PWA 安装与离线运行、音频输出设备选择、标准剪贴板复制。想解锁就让 NAS 上现成的反向代理Nginx Proxy Manager、Traefik、Caddy 均可终止 HTTPShttps://folia.example.com/ - http://127.0.0.1:18080 https://sync.example.com/ - http://127.0.0.1:13000三件配套的事缺一不可证书必须是浏览器信任的完整证书链自签名证书不算数代理要转发Host、X-Forwarded-Host、X-Forwarded-Proto: https、X-Forwarded-For并把 HTTP 请求重定向到 HTTPS在.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/healthdocker compose logs --tail200 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排障速查症状、原因、处理一张表症状原因处理up报Set SYNC_TOKEN to at least 8 charactersSYNC_TOKEN为空或不足 8 位openssl rand -hex 32生成后填进.env再启动启动被拒提示Set FOLIA_IMAGE_NAMESPACE镜像命名空间缺失确认.env里有FOLIA_IMAGE_NAMESPACEpapersman端口 18080 被占用其他服务占用了该端口改FOLIA_HTTP_PORT为空闲端口docker compose up -d重建页面能开但某个在线源搜不出结果对应 API 容器不健康或上游限流docker compose ps确认状态再看该服务日志里的上游报错限流就隔几分钟再试改了FOLIA_AI_PROVIDER或 Navidrome 账号界面没变化环境变量只在容器重建时生效docker compose up -d --force-recreate gateway backend再刷新页面QQ 扫码反复提示装置异常装置状态卷里残留旧身份执行上面的重置 QQ 装置身份三步下次扫码以新装置注册更多环境变量细节、独立服务说明和网络隔离设计见官方文档 deploy/docker/README.md。【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考