Folia 私有音乐站 NAS 部署教程：Docker Compose 6 个容器，10 分钟上线

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

想在同一个页面里搜网易云、酷狗、QQ 音乐，顺便放 NAS 上的本地曲库？Folia 把浏览器变成一个私有音乐站。在 NAS 上用 Docker Compose 拉起 6 个容器，全程约 10 分钟，不下载源码、不编译。

你将得到

• 在线多源播放：登录网易云、酷狗、QQ 音乐（QQ 支持扫码）后即可直接搜索、播放；
• 全屏歌词动画：播放时歌词铺满整屏做动画，还能用 AI 给当前歌曲生成一套配色；
• Navidrome 本地曲库：接入后专辑、歌单、文件夹都以卡片浏览，播放同样带全屏歌词；
• 多设备共用：手机、平板、电脑打开同一地址，就是一个站。

部署前要准备什么

NAS 上有 Docker Engine 24+ 和 Docker Compose v2 即可，这是唯一的环境要求。

新建一个空目录（如docker/folia-docker），从仓库里只放两个文件进去：

folia-docker/ ├── compose.yaml └── .env

目录里只留这两个文件，日后升级只需替换它们。

再生成一把同步令牌：

openssl rand -hex 32

把输出的随机串填进.env的SYNC_TOKEN。🔐 它是同步客户端对接 Sync Server 时出示的凭据，至少 8 位；compose 文件里对它做了必填校验，留空时docker compose config会直接报错，栈起不来。

.env里至少确认这两项（其余保持模板默认）：

FOLIA_IMAGE_NAMESPACE=papersman SYNC_TOKEN=填入刚生成的随机串

FOLIA_IMAGE_NAMESPACE指定镜像从哪个空间拉取，缺失时整个栈拒绝启动。

四条命令把栈跑起来

docker compose config # 先校验配置，变量写错在启动前就暴露 docker compose pull # 拉取全部 6 个镜像 docker compose up -d --wait # 启动，并等每个服务通过健康检查 docker compose ps # 查看各容器状态

--wait的意义在于：命令会等到所有容器健康检查通过才返回，不用自己猜启动时机。

✅ 三条都满足即部署成功：

1. docker compose ps里 6 个容器全部healthy；
2. 浏览器打开http://NAS-IP:18080能看到 Folia 首页；
3. curl http://NAS-IP:13000/health返回正常，Sync Server 就绪。

顺带看清这 6 个容器：gateway（Nginx）托管前端并做全部对外路由，/netease/、/kugou/、/qq/、/api/的分流规则写在 nginx.conf.template；backend 承接 AI 主题、歌词分词等 Web API；netease-api / kugou-api / qq-api 是三个平台接口；sync-server 是独立的数据同步服务，用 SQLite 存储。三个平台接口被放在internal: true的私有网络里，只能经 gateway 到达，外部设备无法绕路直连；每个容器还都设了read_only: true与no-new-privileges，单个容器被打穿也难以落盘文件或提权。

用好它

Folia 接入 Navidrome：两个字段让本地曲库跑起来

Folia 自己不存音乐文件，本地曲库交给 Navidrome 托管。进入 Folia 的 Navidrome 设置页，填两项：

• 地址：http://NAS-IP:4533（Navidrome 的 Web 端口）
• 账号 / 密码：任意一组 Navidrome 凭证

连接成功后，本地专辑、歌单、文件夹会整理成卡片，搜索、播放、歌词匹配直接可用：

AI 密钥要不要填：GEMINI_API_KEY 与 OPENAI_API_KEY 可留空

两个 key 都留空，播放、在线搜索、歌词都不受影响，缺的只是 AI 主题生成与 AI 歌词分词。

想让新打开的浏览器自动连上曲库的话，在.env填NAVIDROME_URL/NAVIDROME_USERNAME/NAVIDROME_PASSWORD三项，backend 会自动下发凭据。注意能打开 Folia 页面的人都能读到这组凭据，建议在 Navidrome 里单开一个专用账号给它。

Folia 反代 HTTPS 配置：正式使用必做项

局域网 HTTP 能正常搜索播放，但浏览器不把它当安全上下文：本地音乐目录导入（File System Access API）、PWA 离线安装、音频输出设备选择都会被关掉。正式使用要由 NAS 上现成的反向代理（Nginx Proxy Manager、Traefik 等）终结 HTTPS：

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

必做的三件事：

1. 证书必须是浏览器信任的完整链，自签名不算数；
2. 反代要转发X-Forwarded-Host/X-Forwarded-Proto: https/X-Forwarded-For，并把 HTTP 重定向到 HTTPS；Folia 前面挂了代理时，把代理自身地址填进FOLIA_TRUSTED_PROXIES，gateway 才能还原真实客户端 IP；
3. 把.env的FOLIA_HTTP_BIND与FOLIA_SYNC_BIND改为127.0.0.1，流量只从代理进来。

⚠️ 再提一个坑：HTTP 与 HTTPS 是两个不同 origin，切换之后原 HTTP 下的 IndexedDB、登录态、本地曲库索引不会自动迁移。

长期运营

更新镜像：latest 不会自动拉新

docker compose pull docker compose up -d

回滚：固定 FOLIA_STACK_VERSION 到旧版本

在.env里加FOLIA_STACK_VERSION=1.2.0（现行版本号见 VERSION），再跑上面两条更新命令。

备份：只需打包 FOLIA_SYNC_DATA_DIR

数据都集中在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 sync-server curl http://NAS-IP:18080/healthz

变量细节与 QQ 登录态持久化的做法，见 deploy/docker/README.md。

附录 · 配置速查

镜像与端口

AI 与行为

Sync Server

Navidrome 预置

以后无论手机还是电脑，打开同一个地址，在线三源、NAS 曲库、全屏歌词动画就都在手边。

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