8 分钟在 NAS 上跑起私有音乐站：Folia Docker Compose 部署实录

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

家里 NAS 常年开机，却一直只能存歌不能播？想让手机、平板、电脑打开同一个地址，就能听网易云、酷狗、QQ 音乐，还能挂上自己的 Navidrome 曲库看全屏歌词动画——Folia 的 Docker 部署把这套私有音乐站打包好了，NAS 搭音乐站不用自己拼项目，两个文件加几条命令，零编译就能跑起来。

🚀 先跑起来再说

不用先啃文档，先用最少配置把栈拉起来，跑通之后再回头补高级项。

1. 备目录：在 NAS 上建一个空目录，例如folia-docker。看到目录建好、里面空空如也，就对了。

2. 取文件：从仓库下载 deploy/docker/compose.yaml 和 deploy/docker/.env.example 放进该目录，后者重命名为.env。看到目录下只剩compose.yaml和.env两个文件，这一步完成。

3. 生成令牌：在终端执行下面命令，把输出的一长串十六进制字符复制下来，作为 Sync Server 的认证令牌。看到 64 位随机字符串生成，令牌就备好了。

   openssl rand -hex 32

4. 编辑.env：确认FOLIA_IMAGE_NAMESPACE为papersman，把上一步的字符串填进SYNC_TOKEN，其余项先保持模板默认。

5. 启动并验证：依次执行下面 4 条命令。docker compose ps里 6 个容器全部 healthy、浏览器打开http://NAS-IP:18080能看到 Folia 界面、http://NAS-IP:13000/health返回正常，部署就算成了。

docker compose config docker compose pull docker compose up -d --wait docker compose ps

📦 机器里到底跑了什么

六个容器组成完整栈，端口收得比较紧。排障之前先搞清楚谁管哪块，能省一半时间。

几个值得放心的设计：

• 端口收敛：整个栈对外只发布18080和13000两个端口，三个音乐源 API 都挂在internal: true的内部网络里，外部地址够不着，只能走网关。
• 只读容器：六个容器全部read_only: true并启用no-new-privileges，就算某个服务被利用，破坏面也被压在内存里。
• 健康检查：每个服务都配了 healthcheck，up -d --wait会等六个服务全部就绪才返回，ps一片绿才代表栈真的能用。

网关的路由规则一句话：/netease/、/kugou/、/qq/分别转给对应的 API，/api/转给 backend，其余路径回前端页面。

🔧 哪些变量要动

模板里大多数项保持默认就行，真正要碰的按三档看，改完统一用docker compose up -d生效。

必填，缺了不启动

• FOLIA_IMAGE_NAMESPACE：镜像命名空间，模板已给papersman，这一行被删掉时 compose 直接报错拒绝启动。
• SYNC_TOKEN：Sync Server 认证令牌，至少 8 位，不填同样起不来。

建议确认

• FOLIA_HTTP_PORT/FOLIA_HTTP_BIND：网关监听，默认18080/0.0.0.0，端口被占就改这里。
• FOLIA_SYNC_PORT/FOLIA_SYNC_BIND：Sync 端监听，默认13000/0.0.0.0。
• FOLIA_SYNC_DATA_DIR：同步数据库目录，默认./data/sync，想固定挂到某块盘就改它。
• FOLIA_STACK_VERSION：不填走latest，想锁版本见「长期用下去」。
• FOLIA_FORWARD_CLIENT_IP：默认false，别动它，保持false才能避免登录地点显示成"局域网"。

可留空

• GEMINI_API_KEY/OPENAI_API_KEY（连同OPENAI_API_URL、OPENAI_API_MODEL、OPENAI_API_TEMPERATURE）：留空不影响搜索和播放，只是没法用 AI 主题生成和歌词分词。
• NAVIDROME_URL/NAVIDROME_USERNAME/NAVIDROME_PASSWORD：三项都填才触发 Navidrome 自动登录，下文细说。
• QQ_AUTH_SESSION_PATH/QQ_SESSION_SECRET：两项同时填后，QQ 登录态加密存进卷里，重启不掉线。
• DASHBOARD_TOKEN、FOLIA_TRUSTED_PROXIES、ENABLE_GENERAL_UNBLOCK：特殊场景才需要，默认不用管。

两项必填填好后，站点已经能跑，界面长这样：

🔓 把高级功能解锁

基础栈跑稳之后，下面三块按需选装：不配都不报错，只是私有音乐播放这块的体验会打折。

Navidrome 私有曲库：三行配置换全端自动登录

.env里三项都填上后，新打开的浏览器会自动登录这个 Navidrome 并开启曲库，手机、电视、电脑不用再各输一次密码：

NAVIDROME_URL=http://NAS-IP:4533 NAVIDROME_USERNAME=folia NAVIDROME_PASSWORD=...

• 不配置会怎样：凭据存在各浏览器自己的 localStorage 里，每台设备都要手动登录一次。
• NAVIDROME_URL必须是各设备直接能访问的地址，不能写 Docker 内部主机名；Folia 走 HTTPS 时它也得是 HTTPS，否则浏览器拦截混合内容。
• 这组凭据在局域网内是明文下发的，能打开页面的人都能读到，建议单开一个 Navidrome 账号给 Folia 专用；来源范围用NAVIDROME_PRESET_ALLOW控制，默认private只放行局域网。

改完执行docker compose up -d --force-recreate backend gateway生效。

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

注意三点：证书要是浏览器信任的完整证书链，自签的不算安全上下文；代理需传X-Forwarded-Host/X-Forwarded-Proto: https/X-Forwarded-For并把 HTTP 重定向到 HTTPS；同时把FOLIA_HTTP_BIND和FOLIA_SYNC_BIND改成127.0.0.1，避免绕过代理直连。另外 HTTP 和 HTTPS 是两个 origin，切过去后旧缓存、登录态和曲库索引不会自动迁移。

AI 主题与歌词分词：留空 Key 的代价

FOLIA_AI_PROVIDER决定走google/gemini/openai哪家。不填GEMINI_API_KEY或OPENAI_API_KEY，播放、搜索、歌词匹配照常，只是 AI 配色主题和智能歌词分词用不了。填上密钥后切换 provider，只需重建 gateway 和 backend 两个容器，不用重新构建镜像：

docker compose up -d --force-recreate gateway backend

🛠️ 长期用下去

栈跑稳之后，剩下的事都收敛到.env和两三条命令里。

更新版本：latest不会自动拉新，要手动执行：

docker compose pull docker compose up -d

回滚：在.env里加FOLIA_STACK_VERSION=1.1.1（当前发布版见 deploy/docker/VERSION，现为 1.1.2）再重复上面两条命令；Sync Server 另有FOLIA_SYNC_VERSION可单独锁。

备份数据库：数据全在FOLIA_SYNC_DATA_DIR下，停掉服务打包再启动：

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://NAS-IP:18080/healthz curl http://NAS-IP:18080/api/healthz curl http://NAS-IP:13000/health

ps里哪个容器不 healthy，就先翻哪个的日志，十分钟内基本能定位。

跑通之后，这份清单存下来备用：

• 现在能做什么：浏览器打开18080端口，网易云、酷狗、QQ 三个源随便搜，全屏歌词动画直接看；
• 填好 Navidrome 三项后，手机、电视各开一个新标签页，应自动进入私有曲库；
• 想锁版本，在.env加FOLIA_STACK_VERSION；想备份，打包./data/sync走人；
• 出问题先看哪里：docker compose ps哪个容器不 healthy，就先看哪个的日志；
• 同步端不通，curl http://NAS-IP:13000/health探一下，再查SYNC_TOKEN是否被客户端正确携带；
• 端口被占或想换绑定地址，改FOLIA_HTTP_PORT、FOLIA_HTTP_BIND后重新up -d。

两个文件、五步命令，NAS 上的私有音乐站就算落地了——剩下的时间，留给挑歌。

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