Supysonic 0.7.9 配置参数详解

目标：逐段逐项讲清 Supysonic 0.7.9 全部配置参数（INI 格式）的含义、默认值与实测行为，覆盖数据库、曲库扫描、Web 服务、后台守护、转码与 scrobbling 六大板块，并给出可直接落地的生产配置模板。参数行为已在 Ubuntu 24.04 + Supysonic 0.7.9 环境实测验证。

一、环境信息

本文参数行为均在以下环境实测采集（实测日期 2026-10-30）：

• 操作系统：Ubuntu 24.04（x86_64）
• Supysonic：0.7.9（pip 安装于 /opt/supysonic/venv）
• Python：3.12.3；gunicorn 26.2.0；ffmpeg 6.1.1
• 配置文件：/etc/supysonic（单文件 INI）
• 数据库：SQLite /var/lib/supysonic/supysonic.db
• 服务形态：systemd 托管 supysonic（API 服务，gunicorn 2 进程 4 线程）与 supysonic-daemon（后台守护）两个服务单元，安装过程见《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》
• 实测曲库：/var/music（2 位艺术家、5 首曲目）

二、前置条件

• 已按《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》完成安装与服务启动（systemctl is-active supysonic 返回 active）；
• 对配置文件有 root 写权限（/etc/supysonic 归属 root 即可，服务进程按运行账户 supysonic 读取）；
• 配置中引用的目录（数据库、缓存、日志、socket）均已创建且归属 supysonic。

三、参数查看与修改方式

Supysonic 没有查看当前生效配置的 CLI 命令或管理页面，配置仅从文件读取，行为验证靠"改配置 → 重启服务 → 对比行为"。

配置文件的查找与合并顺序（来源：官方文档 setup/configuration 页，查询日期 2026-10-30），依次为：

1. /etc/supysonic
2. ~/.supysonic（服务运行账户的 home，即 /var/lib/supysonic/.supysonic）
3. ~/.config/supysonic/supysonic.conf
4. 工作目录下的 supysonic.conf

多个文件同时命中时值合并生效，越靠后的文件越优先。服务器部署建议只用第 1 个，避免多处配置互相干扰。

文件语法：Windows INI 风格，[section] 段头 + KEY = VALUE（或 KEY: VALUE）；; 开头为注释行。

修改生效流程（实测验证过两次，见 5.2 节 mount_api 案例）：

nano /etc/supysonic                  # 编辑配置
systemctl restart supysonic          # [base]/[webapp]/[transcoding]/[lastfm] 改动重启此单元
systemctl restart supysonic-daemon   # [daemon] 改动重启此单元

确认配置生效的实测手段：在 [webapp] 加一行 mount_api = off 后重启 supysonic，再访问 API 应返回 404（实测回显见 5.2 节）；改回并重启后恢复 200。日志级别同理——本文环境 log_level = INFO 生效时，转码事件会记入 /var/log/supysonic/supysonic.log（实测日志行见 5.6 节）。

四、参数总览

全部配置段与参数一览（默认值来源：官方文档 setup/configuration 页 + 源码 config.sample；带 ✅ 的项有本环境实测行为佐证）：

关键差异解读：[base] 决定数据存在哪、[webapp] 决定对外服务行为、[daemon] 决定后台扫描与 Jukebox、[transcoding] 决定播放时的格式转换——四个段各自独立生效，改哪个段就重启对应进程（[webapp]/[base]/[transcoding] 归 supysonic 服务，[daemon] 归 supysonic-daemon 服务）。

五、核心参数分类详解

5.1 [base] 段：数据库与扫描

5.1.1 database_uri（最重要参数）

数据库连接 URI，语法（官方文档原文格式）：

driver://username:password@host:port/database

支持三类驱动（本环境实测 SQLite 生效，MySQL/PostgreSQL 语法引自官方文档，查询日期 2026-10-30）：

[base]
; SQLite：绝对路径在 Unix 下实际是 4 个斜杠（scheme:// + /绝对路径）
database_uri = sqlite:////var/lib/supysonic/supysonic.db
; SQLite 相对路径（3 个斜杠 + 相对文件名）
;database_uri = sqlite:///relative-file.db
; MySQL（需额外安装 MySQLdb 或 pymysql）
;database_uri = mysql://supysonic:supysonic@localhost/supysonic
; PostgreSQL（需额外安装 psycopg2）
;database_uri = postgres://supysonic:supysonic@localhost/supysonic

逐项说明：

• SQLite 绝对路径：sqlite: + // + /var/lib/...，视觉上 4 个斜杠，官方特别提醒这一点；
• 连接参数：需要附加参数时以查询串挂在 URI 后（如 ?param1=value1&param2=value2）；
• MySQL 字符集：官方注明 URI 未指定字符集时强制默认 utf8mb4（不论 MySQL 服务端设置）；
• 默认值陷阱：不配置时落在 sqlite:////tmp/supysonic/supysonic.db，临时目录重启即丢，生产必须显式配置（本环境配置 /var/lib/supysonic/supysonic.db，实测库文件随首访问自动初始化，无需手工建库；换外部数据库时源码 schema/ 目录附有建表脚本）。

实测确认当前生效值的方式（SQLite 文件真实存在且持续增长）：

ls -l /var/lib/supysonic/supysonic.db

-rw-r--r-- 1 supysonic supysonic 241664 Oct 30 01:16 /var/lib/supysonic/supysonic.db

💡 技术拓展：Supysonic 的数据库后端不止 SQLite 一种，三者对比——

后端	原理/特点	适用场景
SQLite	单文件嵌入式库，零运维	个人/家庭单机部署（默认推荐）
MySQL/MariaDB	独立数据库服务，C/S 架构	多实例共享元数据、已有 MySQL 运维体系
PostgreSQL	独立数据库服务，功能更强	已有 PG 体系或数据量极大的场景

本环境为单机小库，实际采用 SQLite；架构上仅元数据入库，音频文件本体始终在文件系统，换库只需迁移元数据。

5.1.2 scanner_extensions

空格分隔的扩展名白名单，扫描器只处理列表内扩展名的文件。默认空 = 尝试读取目录下所有文件。曲库混杂视频/图片等非音频文件时有用：

scanner_extensions = mp3 ogg flac

5.1.3 follow_symlinks

yes 时扫描器跟随符号链接。默认 no。官方明确警告：开启前确认文件系统可信，程序不处理断链与循环链接。本环境保持默认 no。

5.2 [webapp] 段：Web 服务与缓存

5.2.1 cache_dir / cache_size / transcode_cache_size（缓存三件套）

cache_dir = /var/cache/supysonic
cache_size = 512
transcode_cache_size = 1024

• cache_dir：生成的封面缩略图、转码产物等落盘目录，默认 /tmp/supysonic（临时目录，生产应改为持久目录，本环境实测为 /var/cache/supysonic，目录下实测生成 cache/ 与 transcodes/ 两个子目录）；
• cache_size：主缓存（除转码外）上限，单位 MB，默认 512；
• transcode_cache_size：转码缓存上限，单位 MB，默认 1024（1GB）。缓存超限后按淘汰机制清理。

实测目录结构：

ls /var/cache/supysonic

cache
transcodes

5.2.2 log_file / log_level / log_rotate（日志三件套）

log_file = /var/log/supysonic/supysonic.log
log_level = INFO
log_rotate = yes

• log_file：Web 服务事件日志（轮转文件），留空则不记录；本环境实测已启用并记录转码事件；
• log_level：阈值，可选 DEBUG / INFO / WARNING / ERROR / CRITICAL，默认 WARNING；本环境取 INFO（转码等事件可观测）；
• log_rotate：默认每天零点自动轮转；用外部 logrotate 时设为 no。

5.2.3 mount_api / mount_webui（挂载开关）

两个开关分别控制 Subsonic REST API（/rest/...）与管理界面（/user/...）是否挂载，默认均为 on。

mount_api = off 的实测效果（改配置 → systemctl restart supysonic → curl）：

curl -s -w ' HTTP=%{http_code}\n' 'http://127.0.0.1:5722/rest/ping.view?u=admin&p=q1w2e3r4&v=1.16.1&c=cli-test&f=json'

<!doctype html>
<html lang=en>
<title>404 Not Found</title>
<h1>Not Found</h1>
<p>The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.</p>
 HTTP=404

同一时刻管理界面不受影响（302 跳登录页正常），改回 on 重启后 API 恢复 200（实测）。官方注明 mount_api 主要为测试用途，生产保持 on；mount_webui 关闭后用户将无法在管理界面设置个人偏好转码格式。

5.2.4 use_http_error_status（实测与文档存在差异）

官方文档说明：on 时 API 失败返回对应 HTTP 状态码（401 密码错误、403 禁止、404 资源不存在），off 时一律 200，默认 off。

本环境实测（0.7.9）：置为 on 并重启后行为未变化——错误密码请求仍返回 HTTP=200 + XML 错误体：

<subsonic-response status="failed" version="1.12.0" xmlns="http://subsonic.org/restapi"><error code="40" message="Wrong username or password." /></subsonic-response>
HTTP=200

结论：该参数在 0.7.9 的实测表现与官方文档描述不一致（可能未实现或有版本差异），依赖 HTTP 状态码做 fail2ban/监控时需先按上例实测验证，不要假设其生效。

5.2.5 index_ignored_prefixes

艺术家名索引时忽略的前缀词，空格分隔，默认 El La Le Las Les Los The（官方示例：The Rolling Stones 会归入字母 R 下）。匹配不区分大小写。中文曲库可保持默认。

5.2.6 scrobblers / lyrics_providers / cover_art_providers（可插拔提供源）

三个空格分隔的列表参数，分别控制 scrobbling 服务、歌词源、封面源的加载与优先顺序：

不 listed 的不加载；listed 但缺配置的也不加载并写警告日志。自定义提供源以 Python 模块路径列入（需持有 SCROBBLER/PROVIDER 属性），扩展机制见官方文档 extending 章节。

5.3 [daemon] 段：后台守护

5.3.1 socket

daemon 的 Unix socket 路径，CLI（folder scan 等）与 Web 管理页通过它与 daemon 通信；默认 /tmp/supysonic/supysonic.sock，本环境实测为 /var/run/supysonic/supysonic.sock。官方注明不支持 IP 地址。实测 socket 文件（daemon 运行中）：

ls -la /var/run/supysonic/

total 0
drwxr-xr-x  2 supysonic supysonic  60 Oct 30 01:16 .
drwxr-xr-x 12 root      root      340 Oct 30 00:53 ..
srwxr-xr-x  1 supysonic supysonic   0 Oct 30 01:16 supysonic.sock

folder scan 的两种形态差异由此参数决定：daemon 可达时走 socket 异步扫描（CLI 无输出）；不可达时 CLI 自动降级前台扫描（实测回显 Couldn't connect to the daemon, scanning in foreground）。

5.3.2 run_watcher / wait_delay

• run_watcher：是否启动文件监视器（inotify），默认 yes；曲库文件增删改后自动增量扫描依赖它；
• wait_delay：检测到变更后延迟多少秒触发扫描，默认 5 秒——防止同一文件短时间多次变更触发多次扫描。

实测（daemon 运行中）：向曲库新增文件后执行 folder scan，约 3 秒后新曲目即可通过 API search3 查到，无需人工全量重扫。

5.3.3 jukebox_command

Jukebox 模式（本机音响输出）播放单个文件的命令模板，官方样例 mplayer -ss %offset %path（%offset 起始偏移、%path 文件路径）。需与 supysonic-cli user setroles -J 授予的 jukebox 权限配合；本环境未启用，保持默认空。

5.3.4 log_file / log_level / log_rotate

daemon 侧日志三件套，语义同 [webapp]（阈值默认 WARNING、默认每日轮转）；log_file 留空时日志写 stderr（systemd 环境下进 journal）。

5.4 [lastfm] 段：Last.fm scrobbling

[lastfm]
;api_url = https://ws.audioscrobbler.com/2.0/
;api_key =
;secret =

• api_url：Last.fm API 根地址，默认官方地址，仅测试时指向兼容服务才改；
• api_key / secret：在 https://www.last.fm/api 申请的一对密钥；两项都配置后 [webapp] scrobblers 中的 lastfm 才会真正加载。

工作方式：密钥配置后，各用户还需在管理界面个人资料页绑定自己的 Last.fm 账号，之后播放记录（scrobble）与 now playing 自动上报。本环境未申请密钥，保持默认（未加载、不发送）。

5.5 [listenbrainz] 段：ListenBrainz scrobbling

[listenbrainz]
;api_url = https://api.listenbrainz.org

仅 api_url 一个参数，默认官方实例；ListenBrainz 是开源可自托管的打谱服务，api_url 可指向自建实例。用户令牌不在此配置——各用户在管理界面个人资料页填自己的 ListenBrainz user token。

5.6 [transcoding] 段：转码管道

转码命令模板按"源格式_目标格式"定向优先、通用模板兜底。本环境实测配置（单一通用模板）：

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

占位符含义：

官方 config.sample 中的全套样例（定向模板 + 解码/编码器组合，注明"未经充分测试"，供参考）：

[transcoding]
transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath -
transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt -
decoder_mp3 = mpg123 --quiet -w - %srcpath
decoder_ogg = oggdec -Q -o - %srcpath
decoder_flac = flac -d -c -s %srcpath
encoder_mp3 = lame --quiet -b %outrate - -
encoder_ogg = oggenc2 -q -M %outrate -

实测验证（模板 -ab %outratek -f %outfmt，ffmpeg 6.1.1）：

请求 64kbps mp3（stream.view?...&maxBitRate=64）——转码真实发生，输出 240457 字节（原文件 481201 字节），ffprobe 确认 bit_rate=64000；

请求 ogg（format=ogg）——%outfmt=ogg 生效，输出 OggS 流，服务日志记录（实测日志行）：

2026-10-30 01:17:15,591 [INFO] Transcoding track f47bef15-e0c8-44c2-8cef-5e43a8f726ca for user bbf174d6-34ba-4519-9879-7a82633974d5. Source: mp3 at 128kbps. Dest: ogg at 128kbps

💡 技术拓展：转码模板的实现方式不止 ffmpeg 一条命令，业界常见三种形态对比——

形态	原理	特点
单体转码器（transcoder）	一条命令完成解码+转码	配置最简单，本文实测采用（ffmpeg）
decoder+encoder 管道	解码、编码两条命令以管道串联	工具链可自由组合（lame/oggenc2 等）
定向模板 transcoder_<a>_<b>	按格式对精确匹配	可为特定格式对选最优工具，命中优先于通用模板

Supysonic 三种都支持，实际采用通用 ffmpeg 模板，理由是一条命令覆盖全部格式对、维护成本最低。

5.7 [mimetypes] 段：MIME 手工映射

个别系统无法猜测某扩展名的 MIME 类型时手工映射，默认无需配置：

[mimetypes]
;mp3 = audio/mpeg
;ogg = audio/vorbis

键为扩展名、值为标准 MIME 串，仅"罕见格式识别失败"的场合才需要。

六、生产配置模板

适用场景：1–2 核、2GB 内存、NVMe/SSD 的小型家用/团队服务器，曲库 1–10 万首，单实例部署。直接落到 /etc/supysonic：

[base]
database_uri = sqlite:////var/lib/supysonic/supysonic.db

[webapp]
cache_dir = /var/cache/supysonic
cache_size = 512
transcode_cache_size = 1024
log_file = /var/log/supysonic/supysonic.log
log_level = INFO
mount_api = on
mount_webui = on

[daemon]
socket = /var/run/supysonic/supysonic.sock
run_watcher = yes
wait_delay = 5

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

逐项说明：

• database_uri：SQLite 落持久目录，单机场景零运维；曲库超 10 万首或多实例共享时换 mysql://；
• cache_dir/cache_size/transcode_cache_size：缓存从 /tmp 挪到持久目录；512MB + 1GB 的默认上限适合 2GB 内存机器（缓存落盘不占内存），磁盘紧张可将 transcode_cache_size 减半；
• log_level = INFO：转码、扫描事件可观测，排障后可升回 WARNING 减少写盘；
• mount_api/mount_webui：保持默认开启（客户端用 API、管理员用管理页）；
• run_watcher = yes + wait_delay = 5：曲库文件变化自动增量入库；
• transcoder：通用 ffmpeg 模板，覆盖 mp3/ogg/flac 等全部格式对（需系统已装 ffmpeg）。

配套 systemd 单元与并发参数（--processes 2 --threads 4）见《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》第四部分。

七、常见问题（FAQ）

Q1：改了配置怎么确认生效？

没有查看命令，用行为对比法：mount_api = off 重启后 API 返回 404（实测）；log_level = INFO 生效后转码事件写入日志文件（实测）。每次改完对应段的配置重启对应服务（supysonic 或 supysonic-daemon）再验证。

Q2：use_http_error_status = on 为什么不生效？

官方文档称 on 时失败请求返回 401/403/404 等 HTTP 状态码，但 0.7.9 实测置 on 重启后错误密码仍返回 HTTP 200 + Subsonic 错误 JSON/XML（见 5.2.4 节实测回显）。若依赖该行为，请以实测为准，或升级版本后复测。

Q3：数据库可以换 MySQL 吗，需要建表吗？

可以，database_uri 换成 mysql://用户:密码@主机/库名 即可（需装 pymysql 或 MySQLdb）。首次连接同样会自动初始化表结构；官方也在源码 schema/ 目录附带建表脚本备用。注意 MySQL 下未指定字符集时强制默认 utf8mb4。

Q4：API 传错 ID 报 badly formed hexadecimal UUID string？

Supysonic 的对象 ID 是 UUID，传入格式非法的 id 时返回 error code=0 的 ValueError 信息（实测回显：<error code="0" message="ValueError: badly formed hexadecimal UUID string" />）。先通过 getArtists/getAlbum 等列表端点取回合法 id 再操作即可。

Q5：缓存目录能直接清空吗？

可以。cache_dir 下只有再生成的缓存产物（实测为 cache/、transcodes/ 两个子目录），清空后按请求重建；数据库与音频文件不在其中，清理不影响元数据与曲库。

八、参考链接

1. 官方配置文档：https://supysonic.readthedocs.io/en/latest/setup/configuration.html （查询日期 2026-10-30，默认值与参数行为的主要来源）
2. 转码配置：https://supysonic.readthedocs.io/en/latest/setup/transcoding.html
3. 源码配置样例：https://github.com/spl0k/supysonic/blob/master/config.sample
4. 本系列配套文档：《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》《Supysonic 0.7.9 常用 CLI 命令与工具详解》《Supysonic 介绍与选型指南》