Supysonic 介绍与选型指南

目标：介绍 Supysonic（Python 实现的 Subsonic 服务端 API 音乐流媒体服务器）的定位、架构、功能与同类选型对比，帮助读者判断它是否适合自建音乐库场景。文中安装、命令与 API 响应均已在 Ubuntu 24.04 + Supysonic 0.7.9 环境实测通过。

一、环境信息

本文所有命令与回显均在以下环境实测采集（实测日期 2026-10-30）：

• 操作系统：Ubuntu 24.04（x86_64，Linux 6.x 内核）
• Supysonic：0.7.9（pip 安装，包名 Supysonic）
• Python：3.12.3（系统自带）
• WSGI 服务器：gunicorn 26.2.0（pip 随装）
• 转码器：ffmpeg 6.1.1-3ubuntu5
• 数据库：SQLite（/var/lib/supysonic/supysonic.db），同时支持 MySQL/PostgreSQL
• 服务端口：5722（supysonic-server 默认端口）
• 安装方式：Python venv 虚拟环境 + pip，systemd 托管（安装全流程见《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》）

二、软件概述

Supysonic 是一个用 Python 编写的 Subsonic 服务端 API 实现（官方描述："Supysonic is a Python implementation of the Subsonic server API"，来源：GitHub 仓库 spl0k/supysonic README，查询日期 2026-10-30）。它把一个存放音频文件的目录变成可供 Subsonic 客户端访问的流媒体音乐库：手机/桌面上的 Subsonic 客户端（如 Substreamer、play:Sub、DSub、Feishin、Symfonium 等）通过标准 Subsonic REST API 连上来，即可浏览艺术家/专辑、在线串流播放、离线缓存、管理播放列表。

💡 技术拓展：「Subsonic 兼容服务器」是一类遵循同一套 REST API 规范（subsonic.org 定义的 Subsonic API）的自建流媒体服务器的统称。Subsonic 原版（Java，部分闭源收费）之后社区出现了大量兼容实现，常见选项对比：

实现	语言	特点	适用场景
Supysonic	Python	轻量、纯 API 优先、可 pip 安装	想用 Python 生态、小规模个人库
Navidrome	Go	单二进制、功能最全、社区最活跃	主流首选，功能与生态最好
gonic	Go	极简、低资源、侧重与 Subsonic 客户端搭配	资源紧张的小设备
Sonic	Go	兼容 Subsonic API 的较新实现	已停止维护，不建议新部署
Airsonic 系列（Airsonic/Airsonic-Advanced）	Java	Subsonic 直系分支、带完整 Web 界面	需要 Web 端播放界面

本文主角 Supysonic 是其中 Python 阵营的代表：部署简单（pip 即装）、配置精炼（单个 INI 文件），适合把音乐库服务当作"一个后台服务"来运维的用户。

基本信息（以下数据均于 2026-10-30 通过 GitHub API 实查仓库 spl0k/supysonic）：

解读：Supysonic 是一个"小而稳"的项目——体量不大（290 Stars），但维护历史长达 13 年、代码持续更新；版本节奏偏慢（0.7.6→0.7.7 间隔约 10 个月，0.7.8→0.7.9 间隔约 7 个月），以稳定修复为主。

三、核心架构

Supysonic 由四个部分组成，各部分职责清晰（来源：官方文档 https://supysonic.readthedocs.io/en/latest/ ，结合本环境实测）：

1. 数据库（元数据核心）：所有艺术家/专辑/曲目/用户/播放列表元数据存于关系数据库。通过 database_uri 配置，支持 sqlite、mysql、postgres 三类驱动；不配置时默认落到 /tmp/supysonic/supysonic.db（生产必须显式改掉，见《Supysonic 0.7.9 配置参数详解》）。
2. Web 服务器（supysonic-server）：Flask 应用，对外暴露 Subsonic REST API（路径 /rest/...）与一个轻量管理界面（路径 /user/...）。生产部署用 gunicorn/waitress/gevent 之一承载 WSGI（实测 supysonic-server --help 三者可选），默认监听 5722 端口。
3. 后台守护进程（supysonic-daemon）：负责两件事——监视曲库目录变更（基于 watchdog 的 inotify 监听，文件变化后默认延迟 5 秒触发增量扫描）与 Jukebox 模式（本机音响输出）。通过 Unix socket（/var/run/supysonic/supysonic.sock）与 CLI/Web 通信。
4. 转码管道：播放时按需把源文件转成客户端请求的格式/码率，命令行模板在 [transcoding] 段配置（默认模板为 ffmpeg，占位符 %srcpath/%outrate/%outfmt 等）。

数据流一句话概括：客户端请求 → gunicorn（supysonic-server）→ 查数据库元数据 → 直接串流原文件，或经转码管道输出 → 缓存目录留存转码产物。曲库文件变更路径则由 daemon 监听并自动入库。

以下为实测确认的进程形态（ps 输出，gunicorn 2 进程 + 4 线程模式）：

/opt/supysonic/venv/bin/python3 /opt/supysonic/venv/bin/supysonic-server -S gunicorn --processes 2 --threads 4 -h 0.0.0.0 -p 5722

四、功能特性

以下特性清单来自官方 README（来源：GitHub spl0k/supysonic README，查询日期 2026-10-30），并在本环境对带 * 的项做了实测验证：

• 按目录或标签浏览曲库 *
• 多格式音频串流（mp3/ogg/flac 等，实测 mp3 原样串流）*
• 转码（实测 stream.view?maxBitRate=64 将 128kbps 的 mp3 转为 64kbps，输出经 ffprobe 确认 bit_rate=64000）*
• 用户或随机播放列表（实测 createPlaylist/getPlaylists 正常）*
• 封面图（无内嵌封面时自动生成占位图，实测 getCoverArt 返回 image/jpeg）*
• 收藏（starred）与评分
• Last.fm / ListenBrainz scrobbling（播放记录上报，需在配置中启用并绑定账号）
• Jukebox 模式（服务器本机扬声器播放，需 daemon + jukebox_command）
• 网络电台
• 聊天（Subsonic API 的 chat 端点）

实测的 API 首包（认证成功）：

{"subsonic-response":{"status":"ok","version":"1.12.0"}}

认证失败时返回结构化错误（实测错误密码）：

{"subsonic-response":{"error":{"code":40,"message":"Wrong username or password."},"status":"failed","version":"1.12.0"}}

关于 Web 界面的重要说明：Supysonic 自带的管理界面非常轻量（仅用户/资料/播放列表等管理页，实测访问 / 会 302 跳转到 /user/login），没有内置的网页版音乐播放器。听歌必须使用第三方 Subsonic 客户端 App；想找"打开浏览器就能听"的体验应选 Navidrome 或 Airsonic 系。

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

以下 8 步在本环境从零实测跑通，10 分钟内可完成。更完整的安装（venv 隔离、systemd 托管、目录规划）见《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》。

5.1 安装并准备曲库

pip install supysonic gunicorn   # pip 安装（建议在 venv 中执行）

准备一个含音频文件的目录作为曲库（示例为已备好的 /srv/library，内含 2 位艺术家的 5 首曲目）。

5.2 创建管理员用户

supysonic-cli user add admin -p q1w2e3r4 -e admin@example.com   # 创建用户 admin（成功无输出）
supysonic-cli user setroles -A admin                            # 授予管理员权限

实测回显：

Granted 'admin' admin rights

supysonic-cli user list   # 确认用户已创建

Name		Admin	Jukebox	Email
----		-----	-------	-----
admin           *		admin@example.com

5.3 注册曲库并扫描

supysonic-cli folder add Demo /srv/library   # 注册曲库（成功输出如下）

Folder 'Demo' added

supysonic-cli folder scan Demo   # 扫描入库（daemon 未运行时前台扫描）

Couldn't connect to the daemon, scanning in foreground
Scanning 'Demo': 1 files scanned
Scanning done
Added: 0 artists, 0 albums, 5 tracks
Deleted: 0 artists, 0 albums, 0 tracks

💡 说明：若 daemon 已运行，folder scan 会改为异步执行且命令行无输出；上例为 daemon 未运行时的前台扫描形态。首次全量扫描的数字取决于曲库文件数。

5.4 启动服务并验证 API

supysonic-server -S gunicorn --processes 2 --threads 4 -h 0.0.0.0 -p 5722   # 启动服务

另开终端用 curl 验证 Subsonic API（u 用户名、p 密码、v 客户端协议版本、c 客户端名，四个参数为 Subsonic API 认证约定）：

curl -s 'http://127.0.0.1:5722/rest/ping.view?u=admin&p=q1w2e3r4&v=1.16.1&c=cli-test&f=json'

{"subsonic-response":{"status":"ok","version":"1.12.0"}}

curl -s 'http://127.0.0.1:5722/rest/getArtists.view?u=admin&p=q1w2e3r4&v=1.16.1&c=cli-test&f=json'

{"subsonic-response":{"artists":{"ignoredArticles":"El La Le Las Les Los The","index":[{"artist":[{"albumCount":1,"id":"33c4f3d2-c36b-447e-a5bf-f37772e8cdb4","name":"Artist One"},{"albumCount":1,"id":"d0975255-0150-41bf-96d8-3d7df0627999","name":"Artist Two"}],"name":"A"}]},"status":"ok","version":"1.12.0"}}

status: "ok" 且 getArtists 能列出艺术家，即部署成功。此时用任意 Subsonic 客户端填入服务器地址 http://<服务器IP>:5722 与 admin 账号即可开始听歌。

六、适用场景与限制

6.1 适用场景

• 个人/家庭音乐库自托管：曲库在几百到几万首量级，1 核 512MB 的小服务器即可流畅运行（本环境 daemon 进程实测常驻内存约 19MB，gunicorn 2 进程共约 60MB）。
• 已有 Subsonic 客户端生态：手机上用 Symfonium/DSub、桌面用 Feishin/Supersonic 等客户端连私有库。
• Python 技术栈团队：希望用 pip 管理依赖、便于二次开发或定制（AGPL-3.0 许可，改代码需开源）。
• 需要 Last.fm/ListenBrainz 打谱：听歌记录自动上报。

6.2 限制与注意

• Subsonic API 版本锁定 1.12.0（实测响应一致；新版客户端依赖的 1.13+ 端点如 getInternetRadioStations 之外的特性可能不完整），选客户端时注意兼容性。
• 无内置播放器网页：管理界面不提供网页听歌，浏览器直接听需搭配第三方 Web 客户端。
• 无官方 Docker 支持：官方以 pip 源码包分发，容器化需自行封装（本系列采用 systemd 直装方案）。
• SQLite 默认库路径在 /tmp：不配置 database_uri 时数据落在 /tmp/supysonic/，重启可能丢失，生产必须显式配置（本环境配置为 sqlite:////var/lib/supysonic/supysonic.db）。
• 扫描依赖手动或 daemon 触发：没有 daemon 时文件变化不会自动入库。

七、同类选型对比

四个主流 Subsonic 兼容服务器横向对比。以下社区数据均于 2026-10-30 通过 GitHub API 实查各仓库：

各专栏系列文档入口（点击可查看对应平台的部署、配置与命令详解）：

• Navidrome：《Navidrome 0.64.2 介绍与选型指南》、《Navidrome 0.64.2 Docker Compose 部署指南》
• gonic：《gonic 介绍与选型指南》、《gonic Docker Compose 部署实战》
• Sonic：《Sonic 介绍与选型指南》

选型建议：

• 默认选 Navidrome：社区最活跃（24k Stars）、更新最快、自带网页播放器，绝大多数自建场景的最优解；
• 选 Supysonic：偏好 Python 生态/pip 管理、想要独立的关系型数据库（多用户或日后迁移 MySQL）、或喜欢"极简服务 + 专业客户端"的组合；资源占用与 Navidrome 相当，功能面窄一些但配置一目了然；
• 选 gonic：追求极致轻量与简单，接受手工编辑 TOML 配置；
• 不选 Sonic：仓库自 2024-05 起无代码提交，已停止维护。

本系列选择 Supysonic 的动机：以 systemd 原生服务形态落地（无 Docker 依赖）、用 INI 单文件管理全部配置、数据库可平滑换 MySQL/PostgreSQL，适合作为"Python 系轻量自托管"的参照实现。

八、参考链接

1. GitHub 仓库：https://github.com/spl0k/supysonic （元数据查询日期 2026-10-30）
2. 官方文档：https://supysonic.readthedocs.io/
3. Subsonic API 定义：http://www.subsonic.org/
4. PyPI 包页面：https://pypi.org/project/Supysonic/
5. 本系列配套文档：《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》《Supysonic 0.7.9 配置参数详解》《Supysonic 0.7.9 常用 CLI 命令与工具详解》