Supysonic 0.7.9 常用 CLI 命令与工具详解

目标：详解 Supysonic 0.7.9 随包提供的三个命令行工具（supysonic-cli / supysonic-server / supysonic-daemon）的全部子命令与参数，逐条附真实实测回显，覆盖用户管理、曲库管理、服务启停与后台守护的日常操作。全部命令已在 Ubuntu 24.04 + Supysonic 0.7.9 环境实测。

一、环境信息

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

操作系统：Ubuntu 24.04（x86_64）
Supysonic：0.7.9（pip 安装于 /opt/supysonic/venv，安装过程见《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》）
Python：3.12.3
配置文件：/etc/supysonic（INI 格式，daemon socket 位于 /var/run/supysonic/supysonic.sock）
数据库：SQLite /var/lib/supysonic/supysonic.db
服务：systemd 单元 supysonic（API 服务，gunicorn 2 进程 4 线程，端口 5722）与 supysonic-daemon（后台守护）
演示账户：admin（密码 q1w2e3r4，管理员）
实测曲库：Music → /var/music（2 位艺术家、5 首曲目）

二、工具概览

Supysonic 0.7.9 在 venv 的 bin/ 下提供三个可执行工具：

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

supysonic-cli
supysonic-daemon
supysonic-server

三者分工：

工具	角色	典型用法
supysonic-cli	管理工具（用户/曲库）	建用户、授权、注册曲库、触发扫描
supysonic-server	对外 API 服务进程	前台调试或由 systemd 托管
supysonic-daemon	后台守护进程	曲库变更监视、异步扫描、Jukebox

💡 说明：0.7.9 的 CLI 只有 user 与 folder 两组子命令，播放列表没有 CLI 子命令——播放列表通过 Subsonic API（createPlaylist/getPlaylists 等端点）或客户端管理，实测 supysonic-cli playlist 会报 Error: No such command 'playlist'.。

三、前置条件

工具路径：venv 安装时三个工具在 /opt/supysonic/venv/bin/；本文统一用绝对路径调用。日常使用可将其加入 PATH（ln -s /opt/supysonic/venv/bin/supysonic-* /usr/local/bin/）。
配置文件可读：三个工具启动时都按 /etc/supysonic → ~/.supysonic → ~/.config/supysonic/supysonic.conf → ./supysonic.conf 顺序读取配置（配置详解见《Supysonic 0.7.9 配置参数详解》），无配置时用默认值（数据库落 /tmp）。
运行账户：CLI 操作的是服务数据库与 daemon socket，建议以服务运行账户执行（本环境为 supysonic，无登录 shell，用 runuser -u supysonic -- <命令> 提权执行；root 直接执行亦可读写 SQLite，但 socket 归属校验可能受限）。
daemon 状态：folder scan 的行为依赖 daemon 是否在运行（可达 socket 走异步，不可达自动降级前台），操作前可确认：

systemctl is-active supysonic-daemon

active

四、supysonic-cli 详解

4.1 总览

/opt/supysonic/venv/bin/supysonic-cli --help

Usage: supysonic-cli [OPTIONS] COMMAND [ARGS]...

  Supysonic management command line interface

Options:
  --help  Show this message and exit.

Commands:
  folder  Folder management commands
  user    User management commands

只有 folder、user 两组。查看不存在的命令会得到报错（实测）：

/opt/supysonic/venv/bin/supysonic-cli library --help

Usage: supysonic-cli [OPTIONS] COMMAND [ARGS]...
Try 'supysonic-cli --help' for help.

Error: No such command 'library'.

4.2 user 组：用户管理

4.2.1 user list（列出用户）

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

（user list 无专属参数，帮助仅显示 --help。）直接执行：

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

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

列含义：Name 登录名、Admin 列 * 表示管理员、Jukebox 列 * 表示有 Jukebox 权限、Email 邮箱。全新空库时只显示表头两行（实测回显见《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》4.3 节）。

4.2.2 user add（创建用户）

/opt/supysonic/venv/bin/supysonic-cli user add --help

Usage: supysonic-cli user add [OPTIONS] NAME

  Adds a new user.

  NAME is the name (or login) of the new user.

Options:
  -p, --password TEXT  Specifies the user's password
  -e, --email TEXT     Sets the user's email address
  --help               Show this message and exit.

实测创建后删除（成功时 add 静默无输出、退出码 0）：

/opt/supysonic/venv/bin/supysonic-cli user add temp1 -p pass11111 -e t1@e.com; echo RC=$?

RC=0

重复创建同名用户报错（实测）：

Error: User 'admin' exists

⚠️ 注意：-p 明文传参会留在 shell history 中，生产环境建议建号后立即 user changepass 轮换，或直接接受演示口令（本文演示账号统一 admin/q1w2e3r4）。

4.2.3 user setroles（权限授予/回收）

/opt/supysonic/venv/bin/supysonic-cli user setroles --help

Usage: supysonic-cli user setroles [OPTIONS] NAME

  Enable/disable rights for a user.

  NAME is the login of the user to which grant or revoke rights.

Options:
  -A, --admin / -a, --noadmin     Grant or revoke admin rights
  -J, --jukebox / -j, --nojukebox
                                  Grant or revoke jukebox rights
  --help                          Show this message and exit.

两组开关都是成对正反选项：-A 授予管理员、-a 回收；-J 授予 Jukebox、-j 回收。实测授予：

/opt/supysonic/venv/bin/supysonic-cli user setroles -A admin

Granted 'admin' admin rights

4.2.4 user changepass（改密码）

/opt/supysonic/venv/bin/supysonic-cli user changepass --help

Usage: supysonic-cli user changepass [OPTIONS] NAME

  Changes a user's password.

  NAME is the login of the user to which change the password.

Options:
  -p, --password TEXT  New password
  --help               Show this message and exit.

实测：

/opt/supysonic/venv/bin/supysonic-cli user changepass temp1 -p q1w2e3r4; echo RC=$?

Successfully changed 'temp1' password
RC=0

4.2.5 user rename（重命名）

/opt/supysonic/venv/bin/supysonic-cli user rename --help

Usage: supysonic-cli user rename [OPTIONS] NAME NEWNAME

  Renames a user.

  User NAME will then be known as NEWNAME.

Options:
  --help  Show this message and exit.

实测（两个位置参数：旧名、新名）：

/opt/supysonic/venv/bin/supysonic-cli user rename temp1 temp2; echo RC=$?

User 'temp1' renamed to 'temp2'
RC=0

4.2.6 user delete（删除用户）

/opt/supysonic/venv/bin/supysonic-cli user delete --help

Usage: supysonic-cli user delete [OPTIONS] NAME

  Deletes a user.

  NAME is the name of the user to delete.

Options:
  --help  Show this message and exit.

实测：

/opt/supysonic/venv/bin/supysonic-cli user delete temp2; echo RC=$?

Deleted user 'temp2'
RC=0

4.3 folder 组：曲库管理

4.3.1 folder list（列出曲库）

/opt/supysonic/venv/bin/supysonic-cli folder list --help

Usage: supysonic-cli folder list [OPTIONS]

  Lists folders.

Options:
  --help  Show this message and exit.

直接执行：

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

Name		Path
----		----
Music           /var/music

4.3.2 folder add（注册曲库）

/opt/supysonic/venv/bin/supysonic-cli folder add --help

Usage: supysonic-cli folder add [OPTIONS] NAME PATH

  Adds a folder.

  NAME can be anything but must be unique. PATH must point to an existing
  readable directory on the filesystem.

  If the daemon is running it will start to listen for changes in this folder
  but will not scan files already present in the folder.

Options:
  --help  Show this message and exit.

实测（NAME 唯一即可，PATH 必须已存在且可读）：

mkdir -p /srv/library && /opt/supysonic/venv/bin/supysonic-cli folder add Extra /srv/library; echo RC=$?

Folder 'Extra' added
RC=0

⚠️ 注意官方提示：daemon 在跑时，add 只会让 daemon 开始监视新目录的后续变更，不会自动扫描目录中已有文件——注册后要显式执行 folder scan。

两个典型报错（实测回显）：

Error: Folder 'Music' exists                     # NAME 重复
Error: This path is already registered           # PATH 已注册，或与已注册路径构成字符串前缀关系

第二条尤其注意：已注册 /var/music 后，注册 /var/music-extra（不同目录）也会报 already registered——路径校验按字符串前缀匹配，曲库规划时避免一个曲库路径是另一个的前缀。

4.3.3 folder scan（触发扫描）

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

Usage: supysonic-cli folder scan [OPTIONS] [FOLDER]...

  Run a scan on specified folders.

  FOLDER is the name of the folder to scan. Multiple can be specified. If
  ommitted, all folders are scanned.

Options:
  -f, --force   Force scan of already known files even if they haven't changed
  --background  Scan the folder(s) in the background. Requires the daemon to
                be running.
  --foreground  Scan the folder(s) in the foreground, blocking the processus
                while the scan is running.
  --help        Show this message and exit.

要点：FOLDER 可多选（空格分隔），缺省扫全部曲库；-f/--force 强制重扫未变更的已知文件；--background 交给 daemon 异步执行（daemon 必须在跑）、--foreground 阻塞前台执行。

三种运行形态实测：

形态一：daemon 在跑（默认异步，CLI 无输出，约 3 秒后新文件可被 API 查到）

/opt/supysonic/venv/bin/supysonic-cli folder scan Music; echo RC=$?

RC=0

形态二：daemon 停止（自动降级前台，输出完整过程）

systemctl stop supysonic-daemon
/opt/supysonic/venv/bin/supysonic-cli folder scan Music

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

首次扫描全新曲库时的回显（曲库含 5 首曲目）：

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

形态三：--force 强制重扫（前台）

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

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

💡 说明：实测中 Scanning '<名>': N files scanned 的 N 统计的是"内容有变化、需要重新入库"的文件数，而非曲库文件总数——已入库且未变化的文件即使 --force 也不计入该数（ Added/Deleted 行为 0 即重扫后无增删）。

4.3.4 folder delete（删除曲库注册）

/opt/supysonic/venv/bin/supysonic-cli folder delete Extra; echo RC=$?

Deleted folder 'Extra'
RC=0

删除不存在的曲库报错（实测）：

Error: Folder 'Extra' does not exist.

⚠️ 注意：folder delete 只移除曲库注册与库中元数据，不删除磁盘上的音频文件本身。

五、supysonic-server 详解

5.1 帮助与参数

/opt/supysonic/venv/bin/supysonic-server --help

Usage: supysonic-server [OPTIONS]

  Starts the Supysonic web server

Options:
  -S, --server [gunicorn|waitress|gevent]
                                  Specify which WSGI server to use. Pick the
                                  first available if none is set
  -h, --host TEXT                 Hostname or IP address on which to listen
                                  NOTE: This argument is mutually exclusive
                                  with arguments: [socket].  [default:
                                  0.0.0.0]
  -p, --port INTEGER              TCP port on which to listen  NOTE: This
                                  argument is mutually exclusive with
                                  arguments: [socket].  [default: 5722]
  -s, --socket TEXT               Unix socket on which to bind to, Can't be
                                  used with --host and --port  NOTE: This
                                  argument is mutually exclusive with
                                  arguments: [port, host].
  --processes INTEGER             Number of processes to spawn. May not be
                                  supported by all servers
  --threads INTEGER               Number of threads used to process
                                  application logic. May not be supported by
                                  all servers
  --help                          Show this message and exit.

参数表（默认值来自帮助原文）：

参数	默认值	说明
-S/--server	自动选第一个可用	WSGI 服务器三选一：gunicorn/waitress/gevent
-h/--host	0.0.0.0	监听地址；与 `-s` 互斥
-p/--port	5722	监听端口；与 `-s` 互斥
-s/--socket	无	改绑 Unix socket（反代场景），与 -h/-p 互斥
--processes	无（按 WSGI 服务器默认）	进程数，部分服务器不支持
--threads	无（按 WSGI 服务器默认）	线程数，部分服务器不支持

5.2 前台启动与生产托管

前台调试启动（Ctrl+C 停止）：

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

生产环境由 systemd 托管（单元文件全文见《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》4.4 节），日常操作：

systemctl restart supysonic    # 改配置后重启 API 服务
systemctl is-active supysonic

active

进程实测（gunicorn 2 进程 = 1 主 + 2 worker）：

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

启动后验证（认证参数 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"}}

六、supysonic-daemon 详解

6.1 行为特点：无帮助、直接运行

supysonic-daemon 不解析 --help（实测执行 supysonic-daemon --help 5 秒内无任何输出，进程直接进入运行态，需超时终止）。它是常驻进程，只应以 systemd 托管或 & 后台运行，不要在前台裸跑长期占用会话。

6.2 systemd 托管与验证

单元文件（全文见《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》4.4 节）ExecStart 只有一行 /opt/supysonic/venv/bin/supysonic-daemon。运行态验证：

systemctl is-active supysonic-daemon

active

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

socket 文件（srwxr-xr-x 开头）存在即 daemon 就绪，CLI 的异步扫描、管理页的曲库操作都经它与 daemon 通信。

6.3 daemon 的三项职责

曲库变更监视：[daemon] run_watcher = yes（默认）时以 inotify 监听已注册曲库，文件增删改后延迟 wait_delay（默认 5 秒）自动增量扫描入库；
异步扫描执行：folder scan 走 socket 请求 daemon 在后台完成扫描；
Jukebox 输出：配合 [daemon] jukebox_command 与用户 jukebox 权限实现本机扬声器播放。

七、注意事项

CLI 与 daemon 的通信依赖 [daemon] socket 配置一致：CLI 与 daemon 都按同一配置文件解析 socket 路径，手工以不同账户/配置分别启动会导致 socket 路径不一致，folder scan 表现为"异步无输出但实际没执行"——此时先 systemctl is-active supysonic-daemon 排查。
--background 与 --foreground 显式二选一：省略时按 daemon 是否可达自动选择；--background 在 daemon 停止时会报错（需 daemon），想不依赖 daemon 就用 --foreground。
扫描计数的含义：N files scanned 统计有内容变化的文件（见 4.3.3），不为 0 不代表新增（看 Added 行），排查"扫描了但客户端没看到"先核对 Added/Deleted。
演示账号与真实账号：本文所有示例账户均为演示用途（admin/q1w2e3r4）；真实环境的用户密码属用户数据，user list 不显示密码，仅能 changepass 重置。
升级/重启顺序：升级包后先 systemctl restart supysonic 再 systemctl restart supysonic-daemon（两个单元逐条执行），使新代码在 API 服务与 daemon 两侧同时生效。

八、常见问题（FAQ）

Q1：folder scan 完全没输出，扫描执行了吗？

daemon 在跑时这是正常形态（异步执行，CLI 收到请求即返回）。验证结果：稍候 3–5 秒用 API 查询（如 getArtists），或 --foreground 显式前台执行看过程回显。

Q2：以 root 执行 CLI 会不会写坏数据库？

SQLite 以文件系统权限控制写入，root 具备写权（实测 root 执行正常）；但 daemon socket 属于 supysonic 账户，涉及 daemon 交互的命令建议统一 runuser -u supysonic -- <命令> 执行，保持权限一致性。

Q3：user add 后 user list 看不到新用户？

确认 CLI 与服务读的是同一个数据库配置（[base] database_uri）。若曾以不同账户在错误的工作目录留有 ~/.supysonic 或 ./supysonic.conf，CLI 可能连到了另一个库——清理多余配置文件后重试。

Q4：注册曲库报 This path is already registered 但目录是新的？

路径按字符串前缀校验：已注册 /var/music 时，/var/music-extra 这类以它为前缀的路径会被误判为重复（实测）。换一个无前缀关系的目录（如 /srv/library）即可。

Q5：supysonic-daemon --help 卡住不动？

该工具不实现 --help，执行后直接进入运行态。用 Ctrl+C 或 timeout 5 supysonic-daemon --help 方式终止；查看用法以本文第六节或官方 man 页为准。

九、参考链接

官方 CLI man 页：https://supysonic.readthedocs.io/en/latest/man/supysonic-cli.html
server/daemon man 页：https://supysonic.readthedocs.io/en/latest/man/supysonic-server.html 、https://supysonic.readthedocs.io/en/latest/man/supysonic-daemon.html
官方 daemon 文档：https://supysonic.readthedocs.io/en/latest/setup/daemon.html
本系列配套文档：《Ubuntu 24.04 安装 Supysonic 0.7.9 指南》《Supysonic 0.7.9 配置参数详解》《Supysonic 介绍与选型指南》