Ubuntu 24.04 安装 Supysonic 0.7.9 指南

在 Ubuntu 24.04 从零安装 Supysonic 0.7.9：PyPI venv 与 GitHub 源码双方案、gunicorn+systemd 双服务单元托管、曲库注册、API 验证与排障 FAQ，全部命令实测。

SupysonicSupysonic2026/10/30

目标：在 Ubuntu 24.04 服务器上从零安装并托管 Supysonic 0.7.9（Subsonic 兼容音乐流媒体服务器），采用 Python venv + gunicorn + systemd 的生产形态，覆盖 PyPI 在线安装与 GitHub 源码安装两种方案、曲库注册、API 验证与常见排障。全流程已在 Ubuntu 24.04 服务器实测通过。

一、环境信息

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

  • 操作系统：Ubuntu 24.04（x86_64）
  • Supysonic：0.7.9（PyPI 包名 Supysonic）
  • Python：3.12.3（Ubuntu 24.04 系统自带）
  • WSGI 服务器：gunicorn 26.2.0（随 pip 安装）
  • 转码器：ffmpeg 7:6.1.1-3ubuntu5（Ubuntu 24.04 官方仓库版本）
  • 数据库：SQLite（生产可换 MySQL/PostgreSQL）
  • 安装目录：/opt/supysonic/venv
  • 配置文件：/etc/supysonic（INI 格式单文件）
  • 数据目录：/var/lib/supysonic/（数据库）、/var/cache/supysonic/（缓存）、/var/log/supysonic/（日志）、/var/run/supysonic/（daemon socket）
  • 服务端口：5722
  • 运行账户：专用系统用户 supysonic（无登录 shell）

⚠️ 网络说明：本环境 pip 访问 PyPI 官方源（pypi.org）直连可用；git 访问 github.com 直连失败（Failed to connect to github.com port 443 ... Couldn't connect to server），方案 B 中已改用代理 192.168.1.72:7897 完成 clone（代理不可用时替换为自己的可用代理即可）。

二、前置条件

安装开始前需确认系统满足以下条件，逐条执行并核对回显。

2.1 确认系统与 Python 版本

cat /etc/os-release | grep PRETTY   # 确认发行版

实测回显：

PRETTY_NAME="Ubuntu 24.04.3 LTS"

python3 -V   # 确认 Python 版本（Supysonic 要求 3.10+）

Python 3.12.3

2.2 安装系统依赖

venv 支持、转码器是两个必备项；方案 B 还需要 git：

apt-get update
apt-get install -y --no-install-recommends python3.12-venv ffmpeg git

实测回显（本环境依赖已装好，表现为 already newest；全新机器会正常列出安装包）：

python3.12-venv set to manually installed.
ffmpeg is already the newest version (7:6.1.1-3ubuntu5).
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

验证 ffmpeg 可用（转码依赖）：

ffmpeg -version | head -1

ffmpeg version 6.1.1-3ubuntu5 Copyright (c) 2000-2023 the FFmpeg developers

三、版本选型说明

Supysonic 通过 PyPI 与 GitHub 两条渠道分发，选型时核对版本号与发布日期（官方 Releases 实查日期 2026-10-30）：

版本发布日期说明
0.7.92024-12-15当前最新稳定版，本文安装对象
0.7.82024-05-20上一版
0.7.72024-05-19—
0.7.62023-07-14—

关键差异与如何选型：0.7.9 是当前唯一在维护线的最新版，PyPI 上的 Supysonic 包即为 0.7.9（pip show supysonic 实测 Version: 0.7.9），直接安装即可，无需刻意选旧版。Supysonic 无别的发行渠道（无官方 deb/rpm/Docker 镜像），pip/源码安装是官方推荐形态。

获取最新版本号的命令（避免硬编码过期版本）：

pip index versions Supysonic 2>/dev/null || pip install Supysonic== 2>&1 | grep -o 'from versions: [^)]*'

四、方案 A：PyPI venv 在线安装（主推）

本方案从 PyPI 安装官方发布包到独立 venv，用 gunicorn 承载 WSGI 服务并以 systemd 托管，是生产推荐形态。

4.1 创建运行账户与目录规划

Supysonic 不需要 root 运行；创建专用系统账户（无登录 shell）：

useradd -r -s /usr/sbin/nologin supysonic   # 创建系统用户（成功无输出）
id supysonic                                 # 确认账户已创建

实测回显：

uid=995(supysonic) gid=995(supysonic) groups=995(supysonic)

创建数据、缓存、日志、运行时四类目录并归属 supysonic：

mkdir -p /opt/supysonic /var/lib/supysonic /var/cache/supysonic /var/log/supysonic /var/run/supysonic
chown -R supysonic:supysonic /var/lib/supysonic /var/cache/supysonic /var/log/supysonic /var/run/supysonic

💡 说明：/var/lib/supysonic 放 SQLite 数据库（有状态数据）；/var/cache/supysonic 放封面缩略图与转码产物（可清空再生）；/var/run/supysonic 放 daemon 的 Unix socket。目录规划与配置文件中的路径一一对应，改动时需同步。

4.2 创建 venv 并 pip 安装

python3 -m venv /opt/supysonic/venv   # 创建虚拟环境（成功无输出）
/opt/supysonic/venv/bin/pip install Supysonic gunicorn

实测回显（输出节选，实测首尾）：

Collecting Supysonic
  Downloading Supysonic-0.7.9-py3-none-any.whl.metadata (4.1 kB)
Collecting gunicorn
  Downloading gunicorn-26.2.0-py3-none-any.whl.metadata (4.5 kB)
...
Installing collected packages: filetype, zipstream-ng, watchdog, urllib3, Pillow, peewee, mutagen, markupsafe, itsdangerous, idna, gunicorn, click, charset_normalizer, certifi, blinker, werkzeug, requests, mediafile, jinja2, flask, Supysonic
Successfully installed Pillow-13.0.0 Supysonic-0.7.9 blinker-1.9.0 certifi-2026.10.23 charset_normalizer-3.5.2 click-8.5.0 filetype-1.2.0 flask-3.1.3 gunicorn-26.2.0 idna-3.20 itsdangerous-2.2.0 jinja2-3.1.6 markupsafe-3.0.4 mediafile-0.17.0 mutagen-1.48.1 peewee-4.5.3 requests-2.34.2 urllib3-2.8.0 watchdog-6.0.0 werkzeug-3.1.9 zipstream-ng-1.9.3

验证安装结果与三个可执行入口：

/opt/supysonic/venv/bin/pip show supysonic | head -3

Name: Supysonic
Version: 0.7.9
Summary: Python implementation of the Subsonic server API

ls /opt/supysonic/venv/bin/ | grep supysonic

supysonic-cli
supysonic-daemon
supysonic-server

三个入口的分工：supysonic-cli 管理用户与曲库、supysonic-server 对外提供 API 服务、supysonic-daemon 后台扫描/监视与 Jukebox。

4.3 编写配置文件

Supysonic 按固定顺序查找配置：/etc/supysonic → ~/.supysonic → ~/.config/supysonic/supysonic.conf → 当前目录 supysonic.conf，多文件命中时值合并（来源：官方文档 setup/configuration 页，查询日期 2026-10-30）。服务器部署写第一个 /etc/supysonic 即可。

cat > /etc/supysonic <<'EOF'
[base]
database_uri = sqlite:////var/lib/supysonic/supysonic.db

[webapp]
cache_dir = /var/cache/supysonic
log_file = /var/log/supysonic/supysonic.log
log_level = INFO

[daemon]
socket = /var/run/supysonic/supysonic.sock

[transcoding]
transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt -
EOF

⚠️ 注意：Supysonic 不配置 database_uri 时，数据库默认落在 /tmp/supysonic/supysonic.db——临时目录重启即丢，生产部署必须显式配置（本例为 /var/lib/supysonic/supysonic.db）。全部参数的含义与取值见《Supysonic 0.7.9 配置参数详解》。

确保配置中引用的目录归属正确后，验证配置能被程序读取（首次以 CLI 执行任意命令，能建库即配置生效）：

runuser -u supysonic -- /opt/supysonic/venv/bin/supysonic-cli user list

实测回显（首次执行时自动初始化空库，列表为空表头）：

Name		Admin	Jukebox	Email
----		-----	-------	-----

💡 说明：SQLite 库文件在首次访问时自动创建并初始化表结构，无需手工建库；若后续换 MySQL/PostgreSQL，同样通过 database_uri 指向即可，官方在源码 schema/ 目录附带建表脚本（仅外部数据库需要）。

4.4 systemd 托管（两个服务单元）

Supysonic 运行期包含两个独立进程：对外的 supysonic-server（API 服务）与后台的 supysonic-daemon（曲库监视/Jukebox）。分别建单元文件。

Web 服务单元 /etc/systemd/system/supysonic.service：

cat > /etc/systemd/system/supysonic.service <<'EOF'
[Unit]
Description=Supysonic Subsonic-compatible media server
After=network.target

[Service]
Type=simple
User=supysonic
Group=supysonic
ExecStart=/opt/supysonic/venv/bin/supysonic-server -S gunicorn --processes 2 --threads 4 -h 0.0.0.0 -p 5722
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

💡 说明：-S gunicorn 选择 WSGI 服务器（可选 gunicorn/waitress/gevent，实测 supysonic-server --help 帮助原文："Specify which WSGI server to use. Pick the first available if none is set"）；--processes 2 --threads 4 为并发配置，小规格服务器按需缩减；-h 0.0.0.0 -p 5722 监听地址与端口（默认即 5722）。

后台守护单元 /etc/systemd/system/supysonic-daemon.service：

cat > /etc/systemd/system/supysonic-daemon.service <<'EOF'
[Unit]
Description=Supysonic daemon (library watcher and background scanner)
After=network.target

[Service]
Type=simple
User=supysonic
Group=supysonic
ExecStart=/opt/supysonic/venv/bin/supysonic-daemon
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

加载并启动（每条命令只操作一个单元）：

systemctl daemon-reload
systemctl enable supysonic
systemctl enable supysonic-daemon
systemctl start supysonic
systemctl start supysonic-daemon

enable 实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/supysonic.service → /etc/systemd/system/supysonic.service.
Created symlink /etc/systemd/system/multi-user.target.wants/supysonic-daemon.service → /etc/systemd/system/supysonic-daemon.service.

4.5 验证服务

systemctl is-active supysonic
systemctl is-active supysonic-daemon

active
active

进程与监听确认：

ps -ef | grep [s]upysonic-server

supyson+    5248       1  1 01:31 ?        00:00:00 /opt/supysonic/venv/bin/python3 /opt/supysonic/venv/bin/supysonic-server -S gunicorn --processes 2 --threads 4 -h 0.0.0.0 -p 5722
supyson+    5257    5248  1 01:31 ?        00:00:00 /opt/supysonic/venv/bin/python3 /opt/supysonic/venv/bin/supysonic-server -S gunicorn --processes 2 --threads 4 -h 0.0.0.0 -p 5722
supyson+    5258    5248  0 01:31 ?        00:00:00 /opt/supysonic/venv/bin/python3 /opt/supysonic/venv/bin/supysonic-server -S gunicorn --processes 2 --threads 4 -h 0.0.0.0 -p 5722

（supyson+ 为 ps 对超长用户名的截断显示；gunicorn 2 进程模式下共 3 个进程——1 个主进程 + 2 个 worker，PID 因环境而异。）

API 存活验证（curl 通过 HTTP 状态码判断）：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5722/rest/ping.view

200

💡 说明：不带认证参数的 ping.view 会返回 200 + Subsonic 错误 JSON（error code=10），Supysonic 默认对 API 失败也回 HTTP 200（use_http_error_status 默认 off），因此存活探测看 HTTP 码、功能验证需带认证参数，见 4.6。

4.6 创建管理员用户、注册曲库并走通 API

创建演示管理员（用户名 admin、密码 q1w2e3r4）：

/opt/supysonic/venv/bin/supysonic-cli user add admin -p q1w2e3r4 -e admin@example.com
/opt/supysonic/venv/bin/supysonic-cli user setroles -A admin

实测回显：

Granted 'admin' admin rights

/opt/supysonic/venv/bin/supysonic-cli user list

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

准备曲库目录并注册（示例曲库 /var/music，需 supysonic 用户可读）：

mkdir -p /var/music
cp /path/to/your/music/*.mp3 /var/music/   # 放入你的音频文件
chown -R supysonic:supysonic /var/music
/opt/supysonic/venv/bin/supysonic-cli folder add Music /var/music

实测回显：

Folder 'Music' added

/opt/supysonic/venv/bin/supysonic-cli folder scan Music

实测回显（daemon 正常运行时为异步扫描，CLI 无输出；daemon 未运行时前台扫描如下，输出节选）：

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

⚠️ 注意：daemon 停止时 folder scan 会自动降级为前台扫描（不报错），但文件变更的自动监视将失效，生产环境应保持 supysonic-daemon 常开。

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" 且艺术家列表非空即安装完成。浏览器访问 http://<服务器IP>:5722/ 会 302 到管理登录页 /user/login；日常听歌建议使用 Subsonic 客户端 App 连接本服务。

五、方案 B：GitHub 源码安装

适合需要跟踪最新开发代码或修改源码定制的场景；源码树内附注释版配置样例 config.sample，参考价值高。

5.1 克隆源码仓库

cd /root
git clone --depth 1 https://github.com/spl0k/supysonic.git supysonic-src

⚠️ 网络说明：本环境直连 github.com 失败（fatal: unable to access 'https://github.com/spl0k/supysonic.git/': Failed to connect to github.com port 443 after 21061 ms: Couldn't connect to server），实测走代理可用的命令为：

git -c http.proxy=http://192.168.1.72:7897 clone --depth 1 https://github.com/spl0k/supysonic.git supysonic-src

克隆成功的实测回显（源码树顶层内容）：

Cloning into 'supysonic-src'...

ls /root/supysonic-src

LICENSE
PACKAGING.md
README.md
codecov.yml
config.sample
docs
pyproject.toml
supysonic
tests

5.2 从源码安装到 venv

python3 -m venv /opt/supysonic/venv
/opt/supysonic/venv/bin/pip install /root/supysonic-src

安装成功后核对版本（源码安装时版本号同样解析为 0.7.9，与 PyPI 包一致）：

Name: Supysonic
Version: 0.7.9
Summary: Python implementation of the Subsonic server API

后续配置与 systemd 托管步骤与方案 A 的 4.3/4.4/4.5 节完全一致，此处不再重复；升级代码时执行 git pull 后重跑 pip install /root/supysonic-src 并 systemctl restart supysonic supysonic-daemon（restart 分两条命令逐单元执行亦可）。

六、多方案对比与选择建议

维度方案 A：PyPI venv方案 B：GitHub 源码
版本0.7.9 稳定版master 最新（含未发布改动）
是否需联网需访问 pypi.org需访问 github.com（本环境需代理）
安装方式pip 安装 wheelgit clone + pip install .
配置样例无（按本文档配置）附带 config.sample 注释版
systemd 服务名supysonic / supysonic-daemon同左
升级pip install -U Supysonicgit pull + pip install .
适用场景绝大多数生产部署定制开发/跟踪新特性

选择建议：生产与日常自用一律选方案 A——版本明确、回滚简单（pip install Supysonic==0.7.8 即可降级）；只有需要修改源码或提前使用未发布修复时才选方案 B。

七、配置说明

两种方案共用的配置要点（完整参数逐一详解见《Supysonic 0.7.9 配置参数详解》）：

  1. 配置文件：/etc/supysonic，INI 结构；查找顺序 /etc/supysonic → ~/.supysonic → ~/.config/supysonic/supysonic.conf → ./supysonic.conf，多文件合并。
  2. 必备三处：[base] database_uri（数据库，默认 /tmp 必须改）、[webapp] cache_dir（缓存目录，默认 /tmp 建议改）、[daemon] socket（CLI/daemon 通信 socket，默认 /tmp 建议改）。
  3. 转码：[transcoding] 段的 transcoder 模板（本文用 ffmpeg 通用模板），无该配置时高码率/异格式串流将不可用。
  4. 目录权限：database_uri、cache_dir、log_file、socket 涉及的路径都必须可被运行账户 supysonic 读写，否则服务启动或扫描时报权限错误。
  5. 配置生效方式：修改配置后需重启服务进程（systemctl restart supysonic，daemon 配置改动则 systemctl restart supysonic-daemon）。

八、常见问题（FAQ）

Q1：supysonic-cli 报 Error: This path is already registered，但目录明明是新的？

Supysonic 的曲库路径校验按字符串前缀判断。实测：已注册 /var/music 后再注册 /var/music-extra（两者是不同目录）也会报该错误，因为 /var/music 是 /var/music-extra 的字符串前缀。解决：曲库路径避免与其他曲库路径构成前缀关系（换个父目录，如 /srv/library）。

Q2：folder scan 没有任何输出？

daemon 在运行时扫描是异步的，CLI 收到请求即返回（无输出）。确认扫描结果可用 API 查询（如 getArtists）或稍候重试；想看前台扫描过程可临时 systemctl stop supysonic-daemon 后再执行 folder scan。

Q3：日志出现 No way to transcode from mp3 to ogg？

该日志表示当前转码配置无法输出目标格式。[transcoding] 段未配置或模板不支持目标格式时会这样提示（实测出现在早期仅配置部分转码器的阶段）。配置通用 ffmpeg 模板 transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - 后重启服务，format=ogg 请求即可正常输出（实测日志变为 Transcoding track ... Dest: ogg at 128kbps）。

Q4：客户端提示网络错误/认证失败信息不明确？

Supysonic 默认对 API 失败一律回 HTTP 200 + Subsonic 错误 JSON（use_http_error_status = off），个别客户端对非 2xx 响应只显示"网络错误"。可在 [webapp] 配置 use_http_error_status = on 让失败请求返回对应 HTTP 状态码（401/403/404），便于反代/fail2ban 识别；但部分客户端会因此把失败当作连接问题，需按客户端实测取舍。

Q5：服务重启后数据丢了？

数据库落在 /tmp/supysonic/supysonic.db（database_uri 未配置时的默认值），临时目录内容重启不保。把 [base] database_uri 指向持久目录（如 sqlite:////var/lib/supysonic/supysonic.db）并重启服务。

九、卸载与清理

停用并移除服务单元（逐单元执行）：

systemctl stop supysonic
systemctl stop supysonic-daemon
systemctl disable supysonic
systemctl disable supysonic-daemon
rm /etc/systemd/system/supysonic.service /etc/systemd/system/supysonic-daemon.service
systemctl daemon-reload

删除程序、数据与运行账户（数据含音乐数据库，确认无需保留再删）：

rm -rf /opt/supysonic /etc/supysonic /var/lib/supysonic /var/cache/supysonic /var/log/supysonic /var/run/supysonic
userdel supysonic

实测回显（账户删除）：

userdel: supysonic mail spool (/var/mail/supysonic) not found

（提示无邮件池属正常，账户已删除。）

十、参考链接

  1. 官方安装文档：https://supysonic.readthedocs.io/en/latest/setup/index.html
  2. 配置参数文档：https://supysonic.readthedocs.io/en/latest/setup/configuration.html （查询日期 2026-10-30）
  3. GitHub 仓库：https://github.com/spl0k/supysonic
  4. PyPI 包页面：https://pypi.org/project/Supysonic/
  5. 本系列配套文档：《Supysonic 介绍与选型指南》《Supysonic 0.7.9 配置参数详解》《Supysonic 0.7.9 常用 CLI 命令与工具详解》