★ FEATURED ARTICLE Folia 全屏歌词音乐播放器 NAS Docker 部署指南三步跑起私有曲库与跳舞歌词【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major用 Docker Compose 在 NAS 上部署开源全屏歌词动画音乐播放器 Folia部署完成后打开浏览器就能播放网易云、酷狗、QQ 音乐和你自己的 Navidrome 曲库歌词还会逐字点亮。适合会基础 Linux 命令、想把家用 NAS 变成私人音乐站的你。部署完你能拿到什么一个浏览器访问入口http://NAS-IP:18080网易云、酷狗、QQ 音乐三个在线源都能搜索和播放全屏歌词动画播放时歌词随旋律逐行、逐字点亮支持 pendolo、lumi 等多套视觉主题接入 Navidrome 后你 NAS 上托管的音乐文件直接进入曲库与在线源混排播放独立的 Sync Server端口13000负责多台设备间的播放进度与数据同步三个音乐源接口全部跑在 Docker 内部隔离网络folia-internal为internal: true外部无法绕过网关直接访问开工清单环境要求NAS 终端逐条核对Docker Engine 24 及以上核对docker versionDocker Compose v2核对docker compose version能输出版本号端口 18080、13000 未被占用核对ss -ltnp | grep -E 18080|13000没有任何输出所需文件只需要两个不用保留整个源码仓库文件仓库内路径用途编排文件deploy/docker/compose.yaml定义 6 个容器、4 个 Docker 网络与健康检查配置模板deploy/docker/.env.example重命名为.env后填入必填项部署实操整个栈共 6 个容器gatewayNginx 网关唯一对外入口、backendWeb API负责 AI 主题与歌词分词、netease-api/kugou-api/qq-api三个音乐源接口仅内网、sync-server数据同步服务。第 1 步把两个文件放到 NAS 上目的在 NAS 上建一个只放部署文件的目录。执行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 步生成令牌并填写必填配置目的SYNC_TOKEN是 Sync Server 的访问令牌为空时 Compose 会拒绝启动。先生成 64 位随机字符串openssl rand -hex 32验证命令打印一行 64 位十六进制字符串。把它粘贴进.env确认至少这两行有值FOLIA_IMAGE_NAMESPACEpapersman SYNC_TOKEN上一步的64位字符串验证FOLIA_IMAGE_NAMESPACE在模板里已预填papersman只需确认SYNC_TOKEN已填AI 密钥GEMINI_API_KEY/OPENAI_API_KEY留空不影响播放。配置就绪先让 Compose 解析一遍再拉镜像。第 3 步校验配置并拉取镜像目的先发现.env写法问题再下载 6 个镜像。执行cd folia-docker docker compose config验证完整展开输出 YAML 且末尾无报错说明.env解析通过。docker compose pull验证依次拉取 6 个镜像folia-web、folia-web-api、folia-netease-api、folia-kugou-api、folia-qq-api、folia-sync-server无失败项。第 4 步启动并等待健康检查通过目的--wait会阻塞到所有容器的健康检查通过才返回省去手动轮询。执行docker compose up -d --wait docker compose ps验证docker compose ps中 6 个服务的 STATUS 列全部显示(healthy)没有restarting。失败时跑docker compose logs --tail200 服务名看具体报错。全部绿灯后从用户视角做最后验收。第 5 步验收对外入口目的确认网关与 Sync Server 都对外可达。执行curl http://NAS-IP:18080/healthz curl http://NAS-IP:13000/health验证第一条返回{ok:true,service:folia-gateway}第二条返回 HTTP 200。最后浏览器打开http://NAS-IP:18080能看到首页即部署成功。配置项说明其余变量保持模板默认即可。只有这几项需要你亲自确认变量默认值作用不填会怎样FOLIA_IMAGE_NAMESPACE模板已填papersman镜像命名空间Compose 直接拒绝启动SYNC_TOKEN空Sync Server 的 Bearer 令牌至少 8 位up时报错无法启动FOLIA_HTTP_PORT/FOLIA_SYNC_PORT18080/13000Web 网关与 Sync Server 的对外端口端口被占用时需改成其他值GEMINI_API_KEY/OPENAI_API_KEY空AI 主题生成与歌词分词这两个功能不可用播放正常NAVIDROME_URL/NAVIDROME_USERNAME/NAVIDROME_PASSWORD空服务端预置 Navidrome 自动登录每台设备都要手动填一次账号FOLIA_STACK_VERSIONlatest固定 Web 堆栈版本当前版本 1.2.2见 deploy/docker/VERSION每次pull都跟随 latest 走首次使用先接在线源打开页面后进入对应标签页扫码。QQ 音乐支持微信扫码、手机 QQ 扫码和 QQ 音乐 App 扫码三种方式扫码成功后该源即可搜索播放。再让自己的歌进场需要一个 Navidrome 实例托管音乐文件还没托管就先部署一个。Folia 有两条接入路径二选一手动填在 Folia 的 Navidrome 设置页填地址如http://NAS-IP:4533和账号密码测试通过即可。代价是手机、电脑各浏览器都要填一遍。服务端预置在.env填NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项之后新打开的浏览器自动登录。代价有二NAVIDROME_URL必须写成各设备都能直连的地址不能写 Docker 内部主机名⚠️ 能打开 Folia 页面的人理论上都能读到这组凭据建议在 Navidrome 里单独建一个账号给 Folia 用。三项填好后重建 backend 让配置生效docker compose up -d --force-recreate backend验证新打开一个浏览器访问http://NAS-IP:18080Navidrome 标签页处于已登录状态能看到你的专辑卡片。上生产环境的选项域名 HTTPShttp://NAS-IP:18080能搜索、能播放但局域网 IP HTTP 不属于浏览器安全上下文以下能力会直接缺席本地音乐目录导入File System Access APIPWA 安装与离线运行音频输出设备选择标准剪贴板复制要解锁这些让 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、登录态、本地曲库索引不会自动迁移需要重新登录一次。避坑手册1.docker compose up报Set SYNC_TOKEN to at least 8 characters现象启动命令直接失败。原因SYNC_TOKEN为空或不足 8 位FOLIA_IMAGE_NAMESPACE缺失会报类似错误。处理openssl rand -hex 32把输出填进.env的SYNC_TOKEN重新执行docker compose up -d --wait。2. 端口 18080 被占用了现象gateway 起不来或提示端口冲突。原因FOLIA_HTTP_PORT与 NAS 上其他服务冲突。处理# .env 中改为空闲端口如 # FOLIA_HTTP_PORT18081 docker compose up -d3. 网页能打开但某个在线源搜索没结果现象首页正常指定源的搜索为空。原因对应 API 容器异常或上游限流。处理docker compose ps docker compose logs --tail200 netease-api把服务名换成kugou-api或qq-api容器是(healthy)且无报错时等几分钟再试。4. 改了FOLIA_AI_PROVIDER或 Navidrome 账号界面没变化现象.env已改但行为不变。原因环境变量只在容器重建时注入。处理docker compose up -d --force-recreate gateway backend再刷新页面。5. QQ 扫码总提示装置异常想从头来过现象扫码后报装置错误。原因qq-api-state卷里残留了失效的装置身份该卷只存 Android device 识别值不存账号凭证。处理docker compose down docker volume rm folia_qq-api-state docker compose up -d --wait下次扫码以新装置身份注册。注意正常更新镜像不需要这步装置状态是跨重启复用的。6. 想固定版本、回滚或备份数据现象升级后想回到旧版本或担心同步数据丢失。原因latest标签不会自动更新版本由.env决定数据全部在FOLIA_SYNC_DATA_DIR默认./data/sync。处理# 回滚.env 加一行 FOLIA_STACK_VERSION1.2.1然后 docker compose pull docker compose up -d # 备份停服打包再恢复 docker compose stop sync-server tar -czf folia-sync-backup.tar.gz ./data/sync docker compose start sync-server收尾到这里你的 NAS 上已经跑着一个多源播放 全屏歌词动画的 Folia 音乐站手机、平板、电脑访问同一个地址就能听歌。完整的环境变量表、QQ 登录态加密保存与 Navidrome 预置的边界情况见 deploy/docker/README.mdQQ 音乐部署细节见 docs/qq-music-deployment.md当前版本见 deploy/docker/VERSION。【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
