Solara 2.1.6 介绍与选型指南

目标：说清 Solara 2.1.6「光域」是什么、架构怎么搭、功能边界在哪、和同类自托管音乐方案如何取舍。文中全部仓库数据、镜像元数据、接口回显均来自 2026-10-25 的联网溯源与本地实测（Ubuntu 22.04 + Docker 单容器，宿主端口 8136）。

一、环境信息

• 溯源与实测日期：2026-10-25（仓库数据经 GitHub API 取证，接口行为经本地容器实测）
• 上游仓库：github.com/akudamatata/Solara，默认分支 main
• 社区规模（GitHub API 2026-10-25 实测）：Star 1695 / Fork 3191 / Watch 8，仓库创建于 2025-10-05，最近一次代码推送 2026-09-17
• 本文版本：v2.1.6（2026-09-11 09:15:42 UTC 发布，当前最新稳定 tag；tags 序列 v2.1.6 → v2.1.5 → v2.1.4 …）
• 官方镜像：ghcr.io/akudamatata/solara:2.1.6（linux/amd64，765020763 字节 ≈ 765 MB，声明暴露 8787/tcp）
• 许可证：CC BY-NC-SA（禁止任何商业化行为，衍生项目须保留原项目地址并以相同协议开源）
• 实测环境：Ubuntu 22.04.5 LTS（x86_64），Docker Engine 29.9.2 + Compose v5.6.1，宿主端口 8136 → 容器 8787
• 实测资源基线：空载 CPU 0.88%、内存 195.4 MiB、进程数 71（docker stats 实测）
• 演示访问口令：q1w2e3r4

二、软件概述

Solara（中文名「光域」）是一个开源的自托管网页音乐播放器：它不托管任何音频文件，而是把第三方免费音乐聚合 API（默认 GD音乐台 music-api.gdstudio.xyz）包装成一个 Apple Design 流体美学风格的现代 Web 播放器，用户打开浏览器即可搜索、试听、收藏、看歌词。

用一句话概括其定位：Solara 是「聚合免费 API 的纯前端体验型播放器」，不是「自有曲库管理服务器」。

• 它是什么：一个单容器即可跑起来的网页播放器，搜索/歌词/封面/播放直链全部经由内置代理转发到上游聚合 API；收藏与播放状态跨设备漫游（服务端 SQLite 持久化）。
• 它不是什么：没有曲库扫描、没有 ID3 标签管理、没有多用户体系、没有 Subsonic 等开放客户端协议——它面向的是「打开网页就听歌」的轻量场景。
• 技术栈：原生 HTML/CSS/JavaScript 前端（模块化解耦，无框架构建）；后端为 Express（Node.js）+ Wrangler（Cloudflare Pages 本地开发服务器）混合双引擎；存储用 Node.js 22.5+ 内置 node:sqlite（WAL 模式）。
• 部署形态：官方支持两种——Docker 单容器（本文形态）与 Cloudflare Pages 免服务器托管。
• 许可约束：CC BY-NC-SA，禁止商用；个人与家庭内部署使用没有问题，任何商业化（含企业内部收费服务）均被许可排除。

💡 技术拓展：自托管「听音乐」方案按音源形态分三类——

形态	代表	特点
聚合免费 API 播放	Solara（本文）	零曲库成本，即搜即听；音源稳定性受制于上游
自有曲库服务器	Navidrome、Jellyfin、Emby	管理本地音频文件，功能全面；需要先拥有曲库
流媒体客户端皮肤	YesPlayMusic 等桌面端	美化官方账号体验，通常不自托管

本文主角属第一类，选型对比见第七章。

三、核心架构

Solara 2.1.6 Docker 形态采用「Express 前台 + Wrangler 后台」的混合双引擎架构，一个容器内跑两个进程：

浏览器
  │  :8787（容器内）/ 宿主映射端口
  ▼
Express 前台（server/index.js）
  ├─ /login、/api/login      → 认证（Cookie: auth=base64(口令)，48h 有效）
  ├─ /api/storage            → SQLite 读写（/data/solara.db，收藏/播放状态漫游）
  ├─ /palette                → 专辑封面调色板分析（内存缓存 1 小时）
  ├─ 静态文件与 index.html    → 直接 sendFile
  └─ /proxy                  → 转发给同机 Wrangler（127.0.0.1:8788）→ 上游 API_BASE_URL

架构要点（逐项经源码与实测核实）：

1. Express 承担高频流量：认证、存储、调色板、静态页直发全部在 Express 侧完成，音频流式管道支持切歌即时中止、防 Socket 泄漏。
2. Wrangler 只做一件事：代理 /proxy 的上游 API 请求——利用其 BoringSSL 指纹绕过上游的 Cloudflare 验证。入口脚本固定注入 WRANGLER_API_URL=http://127.0.0.1:8788，Wrangler 只监听回环地址，不对外暴露。
3. 配置注入方式：入口脚本 docker-entrypoint.sh 把 PASSWORD / API_BASE_URL / language 三个环境变量写入 /app/.dev.vars 供 Wrangler 读取，同时 Express 直接读进程环境变量。
4. 服务端存储：/data/solara.db（SQLite，WAL 模式），两张表 playback_store（播放状态/播放列表）与 favorites_store（收藏），浏览器端 localStorage 为降级兜底。/data/v3/ 是 Wrangler/miniflare 的持久化目录，Docker 形态下前端读写不走它。
5. 两级内存缓存：/proxy 上游响应缓存 5 分钟（空结果与错误不缓存），/palette 调色板结果缓存 1 小时——二次搜索同一关键词明显提速，响应头 X-Cache-Status: HIT/MISS 可观测。

💡 技术拓展：SQLite 的日志模式（journal mode）不止 Solara 所用的 WAL——

模式	特点	适用场景
DELETE	默认，写时建回滚日志、提交即删	低频写的小库
TRUNCATE / PERSIST	复用日志文件减少开销	与 DELETE 类似的优化变体
MEMORY	日志放内存，快但崩溃即丢	临时库
WAL	读写不互斥，写先落 -wal 文件	读多写多的 Web 服务

Solara 启用 WAL（PRAGMA journal_mode=WAL，数据目录可见 solara.db-wal/solara.db-shm），浏览器多端并发读写播放状态时互不阻塞，这也是备份时要连同 -wal/-shm 一起打包的原因。

四、功能特性

以下特性按「官方宣称 → 本地实测」核对，实测回显均来自 2026-10-25 对容器内服务的真实请求：

💡 技术拓展：音质选项里的 128/192/320/999 指码率（kbps）——

取值	含义	单首体积量级	取舍
128	标准音质 128 kbps mp3	~3.8 MB/首	省流量、解析最快（实测 2.9s）
192	高品音质 192 kbps	~5.7 MB/首	折中
320	极高音质 320 kbps mp3	~9 MB/首	听感上限（mp3），上游解析慢
999	无损 FLAC	20 MB+/首	体积大、上游超时风险高（实测 115s）

Solara 默认取 320；按实测稳定性，日常建议 128 或 192。

五、快速开始（最小可用示例）

本节给出一个可立即跑通的最小部署（完整部署步骤、独立网络与持久化细节见本专栏部署篇）。

1. 新建目录并写入 docker-compose.yml：

name: solara-v216-stack

services:
  solara:
    image: ghcr.io/akudamatata/solara:2.1.6
    container_name: solara-v2.1.6-app
    restart: unless-stopped
    init: true
    ports:
      - "8136:8787"
    environment:
      - PASSWORD=q1w2e3r4
      - API_BASE_URL=https://music-api.gdstudio.xyz/api.php
    volumes:
      - ./data:/data

⚠️ 注意：Compose 项目名会被 Docker 规范化（小写字母/数字/连字符，点号会被剥除）。若写成 solara-v2.1.6-stack，实际项目名会变成 solara-v216-stack，后续 docker compose 命令按规范化后的名字匹配——建议像上面一样直接写规范化形态。init: true 是官方建议，用于解决 Node/Wrangler 进程无法优雅响应 SIGTERM 导致的停止卡顿。

2. 启动并确认状态：

docker compose up -d && docker compose ps

实测输出：

NAME                IMAGE                              COMMAND                  SERVICE   CREATED          STATUS          PORTS
solara-v2.1.6-app   ghcr.io/akudamatata/solara:2.1.6   "/app/docker-entrypo…"   solara    14 minutes ago   Up 14 minutes   0.0.0.0:8136->8787/tcp, [::]:8136->8787/tcp

3. 验证访问控制与搜索链路（q1w2e3r4 为演示口令）：

# 未登录访问主页 → 302 跳登录页
curl -s -o /dev/null -w "GET / -> %{http_code} redirect=%{redirect_url}\n" http://127.0.0.1:8136/

实测输出：

GET / -> 302 redirect=http://127.0.0.1:8136/login

# 登录拿 Cookie
curl -s -c cookies.txt -X POST http://127.0.0.1:8136/api/login \
  -H 'Content-Type: application/json' -d '{"password":"q1w2e3r4"}'

实测输出：

{"success":true}

# 搜一首歌验证上游链路
curl -s -b cookies.txt --max-time 60 \
  "http://127.0.0.1:8136/proxy?types=search&source=netease&name=%E5%91%A8%E6%9D%B0%E4%BC%A6&count=5&pages=1" \
  -o /dev/null -w "HTTP %{http_code} bytes=%{size_download} time=%{time_total}s\n"

实测输出：

HTTP 200 bytes=1188 time=6.454419s

浏览器打开 http://<服务器IP>:8136，输入口令即可进入播放器。

六、适用场景与限制

6.1 适用场景

• 个人/家庭听歌：想要一个好看的网页播放器，不想维护任何音频文件。
• 零曲库成本试错：没有本地曲库、又想自托管一个音乐入口的用户。
• 多设备轻漫游：收藏与播放状态存服务端 SQLite，手机/电脑浏览器打开同一站点即同步。

6.2 限制与风险（全部经核实，按影响排序）

1. 许可禁止商用：CC BY-NC-SA 明确禁止任何商业化行为；企业内网若涉及经营用途需换方案。
2. 上游 API 是单点依赖：搜索/歌词/封面/直链全部经由默认的 GD音乐台免费 API。实测同日热歌榜接口出现 180 秒超时（HTTP 000）的波动；br=320/999 高码率直链解析 115 秒超时。上游挂了，播放器即不可用。
3. 音源覆盖与宣称不符：README 宣称「网易云/QQ/酷狗」等，实测 kuwo 源上游返回 HTTP 400 {"detail":"Value of source is not supported."}，当前仅 netease 源稳定可用（前端仍保留四源下拉）。
4. language=ENG 在 Docker 形态实测不生效：该功能依赖 Cloudflare Pages 中间件向 HTML 注入 window.SITE_LANGUAGE；Docker 形态下 Express 直接 sendFile 返回页面、绕过了 Wrangler 中间件，实测 8787 端口页面 window.SITE_LANGUAGE 计数为 0（直连 Wrangler 8788 的页面计数为 1）。英文界面仅在 Cloudflare Pages 部署形态下可用。
5. 无多用户与权限体系：全站只有一个共享口令，无账号、无角色，适合个人/家庭，不适合多人分权。
6. 启动横幅泄漏口令明文：入口脚本打印启动信息时，因 ${PASSWORD:+configured}${PASSWORD:-...} 展开瑕疵，容器日志会把口令明文拼在 configured 后面（实测日志行 Password : configuredq1w2e3r4）。生产环境务必限制 docker logs 的可见范围。
7. 镜像供应链风险：官方镜像只发布在 ghcr.io/akudamatata/solara（765 MB 级）。Docker Hub 上存在第三方重打包镜像 aexus/solara-music——仅 latest 一个标签、体积仅 51.9 MB、2025-11-16 后停更，与官方镜像差异巨大且无人维护，不要使用。
8. 无曲库管理能力：没有扫描、标签、专辑整理，也无法接入 Subsonic 客户端生态。

七、同类选型对比

7.1 量化对比表

与站内已实测的 Navidrome 0.64.2 对照（数据查询/实测日期均为 2026-10-25）：

关键差异解读：两者解决的是不同问题——没有曲库、想即搜即听选 Solara；有曲库、要长期资产化管理选 Navidrome。Solara 的 fork/star 比（3191/1695 ≈ 1.9）远高于常见项目，说明大量用户 fork 后自行 Cloudflare Pages 部署，社区以「用」为主而非「共建」；Navidrome 则是典型的成熟共建型项目。

7.2 选型建议（如果…则…）

• 如果你已有本地音乐文件（NAS/硬盘里的 CD 抓轨、合集）→ 选 Navidrome 一类自有曲库服务器。
• 如果你没有曲库、只想网页听歌且接受上游免费 API 的波动 → Solara 是最省事的选择。
• 如果你需要多人使用、每人独立账号与歌单 → Solara 不满足，选 Navidrome。
• 如果你需要手机客户端 App 离线缓存 → Solara 只有 PWA，无离线缓存；选支持 Subsonic 生态的方案。
• 如果你要商用或嵌入经营场景 → Solara 的 CC BY-NC-SA 直接排除，选 GPL/MIT 类许可方案。

八、参考链接

• 上游仓库：https://github.com/akudamatata/Solara（stars/forks/tags 取证于 GitHub API，查询日期 2026-10-25）
• 版本发布页：https://github.com/akudamatata/Solara/tags（v2.1.6 发布于 2026-09-11）
• 官方镜像：https://ghcr.io/akudamatata/solara（ghcr.io/akudamatata/solara:2.1.6）
• 默认上游 API（GD音乐台）：https://music.gdstudio.xyz/
• 第三方镜像风险样本（勿用）：https://hub.docker.com/r/aexus/solara-music
• 站内同专栏：部署篇《Solara 2.1.6 Docker Compose 部署指南》、配置篇《Solara 2.1.6 配置参数详解》、运维篇《Solara 日常运维手册》
• 站内对照方案：《Navidrome 0.64.2 Docker Compose 部署指南》、《Navidrome 0.64.2 配置参数详解》