AzuraCast 常用 CLI 命令详解

目标：系统梳理 AzuraCast 0.24.0 的两大命令行工具——核心命令行工具 azuracast-cli 与安装管理脚本 docker.sh，逐条给出子命令、参数与真实回显，覆盖备份恢复、电台运维、账号管理、系统设置、媒体处理与升级回滚六大运维场景。本文全部命令与回显已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
AzuraCast：0.24.0（stable 频道，2026-10-25 发布；版本实查自 GitHub Releases，查询日期 2026-10-27）
安装目录：/var/azuracast（官方推荐基目录，两大工具都存放于此）
实测电台：Quzuo FM（shortcode quzuo_fm，Icecast 前端 + Liquidsoap 后端，串流端口 8000）
演示账号：admin@quzuo.net（Super Administrator，密码 q1w2e3r4）
站内时区：Asia/Shanghai（回显中时间字段以此显示）

二、工具概览

AzuraCast 官方安装完成后，在安装目录提供两个入口：

工具	路径	定位	典型场景
`azuracast-cli`	`/var/azuracast/azuracast-cli`	应用级命令行（Symfony Console）	备份恢复、账号、设置、媒体、同步任务
`docker.sh`	`/var/azuracast/docker.sh`	安装与生命周期管理脚本	安装、升级、回滚、启停、改端口

两者分工明确：docker.sh 管「这台安装本身」（装、升、滚、启停），azuracast-cli 管「系统里的数据与业务」（账号、电台、媒体、统计）。

cd /var/azuracast
./azuracast-cli list

实测回显（0.24.0 全量子命令清单，内部调试类命令略）：

AzuraCast Command Line Tools (Production) 0.24.0

Usage:
  command [options] [arguments]

Available commands:
  completion                              Dump the shell completion script
  help                                    Display help for a command
  list                                    List commands
 azuracast
  azuracast:account:list                  List all accounts in the system.
  azuracast:account:login-token           Create a unique login token URL for the specified account.
  azuracast:account:reset-password        Reset the password of the specified account.
  azuracast:account:set-administrator     Set the account specified as a global administrator.
  azuracast:acme:get-certificate          [acme:cert] Get a new or updated ACME (LetsEncrypt) certificate.
  azuracast:acme:reload                   [acme:reload] Reload certificate-using services (in case of manual HTTPS cert update).
  azuracast:backup                        Back up the AzuraCast database and statistics (and optionally media).
  azuracast:cache:clear                   [cache:clear] Clear all application caches.
  azuracast:debug:optimize-tables         Optimize all tables in the database.
  azuracast:internal:ip                   Get the external IP address for this instance.
  azuracast:internal:on-ssl-renewal       Reload broadcast frontends when an SSL certificate changes.
  azuracast:internal:uptime-wait          Wait for a service to become available, or exit if it times out.
  azuracast:media:clear-computed-autocue  Clear computed AutoCue values.
  azuracast:media:clear-extra             Clear all extra metadata from the specified media.
  azuracast:media:reprocess               Manually reload all media metadata from file.
  azuracast:playlist:export               Export a station's playlist/s as a portable JSON configuration dump
  azuracast:playlist:import               Import playlists into a station from a JSON configuration dump
  azuracast:queue:clear                   [queue:clear] Clear the contents of the message queue.
  azuracast:queue:process                 [queue:process] Process the message queue.
  azuracast:radio:restart                 Restart all radio stations, or a single one if specified.
  azuracast:restore                       Restore a backup previously generated by AzuraCast.
  azuracast:settings:list                 List all settings in the AzuraCast settings database.
  azuracast:settings:set                  Set the value of a setting in the AzuraCast settings database.
  azuracast:setup                         Run all general AzuraCast setup steps.
  azuracast:setup:fixtures                Install fixtures for demo / local development.
  azuracast:setup:migrate                 Migrate the database to the latest revision.
  azuracast:setup:rollback                Roll back the database to the state associated with a certain stable release.
  azuracast:station-queues:clear          Clear all unplayed station queues.
  azuracast:sync:nowplaying               Task to run the Now Playing worker task.
  azuracast:sync:nowplaying:station       Task to run the Now Playing worker task for a specific station.
  azuracast:sync:run                      Task to run the minute's synchronized tasks.
  azuracast:sync:task                     Task to run a specific scheduled task.

解读：命令按前缀分组——azuracast:account:* 账号、azuracast:settings:* 设置、azuracast:media:* 媒体、azuracast:sync:* 定时同步任务、azuracast:setup:* 数据库结构迁移。migrations:* 与 orm:* 为框架层命令，日常运维用不到，本文不展开。

三、前置条件

已按部署实战完成安装（见《AzuraCast Docker Compose 部署实战》第三章），/var/azuracast 目录存在且服务在运行。
以 root 或 sudo 用户执行；azuracast-cli 需要与安装同用户权限运行。
确认服务健康（CLI 依赖应用与数据库在线）：

cd /var/azuracast && docker compose ps --format '{{.Name}} {{.Status}}'

实测回显：

azuracast-0.24.0-web Up 4 hours

四、核心命令详解

4.1 备份：azuracast:backup

备份数据库、统计与（可选）媒体库为 zip 包。参数与选项（help azuracast:backup 实测）：

Usage:
  azuracast:backup [options] [--] <path>

Arguments:
  path

Options:
      --storage-location-id[=STORAGE-LOCATION-ID]
      --exclude-media

path 是备份文件路径前缀（工具自动追加 .zip）；--exclude-media 只备数据库与统计；--storage-location-id 指定备用存储位置 ID。

实测（全量备份，包含 4 首测试曲目）：

./azuracast-cli azuracast:backup /var/azuracast/backups/station-full

实测回显：

AzuraCast Backup
================

Please wait while a backup is generated...

Backing up MariaDB...
---------------------


Creating backup archive...
--------------------------

  adding: var/azuracast/storage/uploads/ (stored 0%)
  adding: var/azuracast/stations/quzuo_fm/media/ (stored 0%)
  adding: var/azuracast/stations/quzuo_fm/media/tone_a.mp3 (stored 0%)
  adding: var/azuracast/stations/quzuo_fm/media/tone_b.mp3 (stored 0%)
  adding: var/azuracast/stations/quzuo_fm/media/tone_c.mp3 (stored 0%)
  adding: var/azuracast/stations/quzuo_fm/media/tone_d.mp3 (stored 0%)
  adding: var/azuracast/stations/quzuo_fm/recordings/ (stored 0%)
  adding: var/azuracast/stations/quzuo_fm/podcasts/ (stored 0%)
  adding: tmp/azuracast_backup_mariadb/db.sql (deflated 87%)

Cleaning up temporary files...
------------------------------


 [OK] Backup complete in 0.10 seconds.

验证产物（自动加 .zip 后缀）：

ls -lah /var/azuracast/backups/

实测回显：

total 2.5M
drwxr-xr-x 2 azuracast azuracast 4.0K Oct 27 06:29 .
drwx------ 1 azuracast azuracast 4.0K Oct 25 14:24 ..
-rw-r--r-- 1 azuracast azuracast 2.5M Oct 27 06:29 station-full.zip

⚠️ 真实踩坑：path 不能写成挂载目录本身。实测执行 ./azuracast-cli azuracast:backup /var/azuracast/backups（正好是备份卷的挂载点）报错：
In Filesystem.php line 194:
  Failed to remove directory "/var/azuracast/backups": rmdir(/var/azuracast/b
  ackups): Device or resource busy
备份流程在收尾清理临时目录时把挂载点当普通目录删除导致失败。解决：给路径多加一层子前缀（如上例的 /var/azuracast/backups/station-full）。建议的定时备份组合：夜间 --exclude-media 快备 + 每周全量备。

4.2 恢复：azuracast:restore

恢复由 4.1 生成的备份包。参数（help azuracast:restore 实测）：

Usage:
  azuracast:restore [options] [--] [<path>]

Arguments:
  path

Options:
      --restore
      --release

path 指向备份 zip（可省略，交互选择）；--release 用于声明备份来自哪个旧稳定版本（跨版本恢复时先对齐结构）；--restore 强制进入恢复流程。恢复会停掉播出、清空数据库并导入、解压媒体。跨版本恢复后务必执行一次结构迁移再重启电台：

./azuracast-cli azuracast:restore /var/azuracast/backups/station-full.zip
./azuracast-cli azuracast:setup:migrate
./azuracast-cli azuracast:radio:restart

4.3 电台重启与队列清理：azuracast:radio:restart / azuracast:station-queues:clear

修改电台配置或流参数后让播出进程生效。实测重启单台：

./azuracast-cli azuracast:radio:restart quzuo_fm

实测回显：

 0/1 [░░░░░░░░░░░░░░░░░░░░░░░░░░░░]   0%
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 [OK] All stations restarted.

进度条按电台数计数；不带参数则重启全部电台。重启后约数秒内 Icecast 挂载重建，听众会经历一次短暂重连。相关命令 azuracast:station-queues:clear 清空所有电台未播完的自动播出队列（改完播放列表权重想立即生效时用，无需重启电台）。

4.4 查看实例外部 IP：azuracast:internal:ip

排障（如防火墙放行清单核对、公告听流地址）时获取实例公网出口：

./azuracast-cli azuracast:internal:ip

实测回显：

182.54.113.29

4.5 账号管理：azuracast:account:*

四个子命令：list（列出账号）、reset-password（重置密码）、login-token（生成一次性登录/重置链接）、set-administrator（把某账号提升为全局管理员）。

列出账号：

./azuracast-cli azuracast:account:list

实测回显：

AzuraCast User Accounts
=======================

 ----------------- ------ --------------------- -------------------
  E-mail Address    Name   Roles                 Created
 ----------------- ------ --------------------- -------------------
  admin@quzuo.net          Super Administrator   2026-10-27 2:58am
 ----------------- ------ --------------------- -------------------

重置密码（忘了管理员密码时的救命命令，非交互，直接打印临时密码）：

./azuracast-cli azuracast:account:reset-password admin@quzuo.net

实测回显：


Reset Account Password
======================

 The account password has been reset. The new temporary password is:

     2tJ7Z2cKcyZH3tT

 Log in using this temporary password and set a new password using the web interface.

⚠️ 注意：临时密码只显示这一次，且要求本人登录后在 Web 界面立即改掉；把命令输出贴到工单/聊天前先涂抹该值。

生成一次性登录链接（给运维代登或免密下发，默认 30 分钟有效）：

./azuracast-cli azuracast:account:login-token admin@quzuo.net

参数（help 实测）：-t/--type 默认 reset_password（可改为登录类型），-e/--expires 有效分钟数默认 30。

4.6 系统设置读写：azuracast:settings:list / set

读取系统级设置表（对应 Web 界面「Administration → System Settings」）：

./azuracast-cli azuracast:settings:list

实测回显（节选，全文 63 行）：

AzuraCast Settings
==================

 ---------------------------------------------- --------------------------------------
  Setting Key                                    Setting Value
 ---------------------------------------------- --------------------------------------
  app_unique_identifier                          1f1d1b16-638b-61de-a9ad-cdd57a30c365
  base_url
  instance_name                                  Quzuo 实测站点
  prefer_browser_url                             1
  use_radio_proxy                                1
  history_keep_days                              60
  always_use_ssl
  api_access_control
  enable_liquidsoap_editing                      1
  enable_all_webhooks                            1
  analytics
  check_for_updates                              1
  public_theme
  hide_album_art

解读：空值=未设置（走默认行为）；history_keep_days 60 表示播放历史保留 60 天；use_radio_proxy 1 启用网关层听流代理（即 /listen/... 地址）。写操作用 azuracast:settings:set <key> <value>（参数形态取自 help 实测），等价于在 Web 界面修改系统设置，改完无需重启；不确定键名含义时先在 Web 界面找到对应开关再回来批量操作。

4.7 媒体重处理：azuracast:media:reprocess

让系统重新读取媒体文件元数据（时长、码率、封面、CUE）。上传曲目但时长显示不对、或手工改了文件需要刷新时使用：

./azuracast-cli azuracast:media:reprocess quzuo_fm

实测回显：


Manually Reprocess Media
========================

Reprocessing media for station: Quzuo FM
Marked 4 record(s) for reprocessing.

命令只做「标记」，实际分析由队列后台异步完成。带第二参数可只处理某文件或目录。同族的 azuracast:media:clear-extra 清除全部附加元数据、azuracast:media:clear-computed-autocue 清除 AutoCue 计算值（用了 AutoCue 自动增益但想重算时）。

4.8 队列与同步任务：azuracast:queue:* / azuracast:sync:*

azuracast:queue:process：处理消息队列。注意实测该命令会常驻运行持续消费队列（前台执行不退出），它由系统调度器托管，日常无需手工执行；如需手工跑一次请放后台并限时（如 timeout 60），否则会一直占用终端。
azuracast:queue:clear：清空消息队列内容（队列积压异常时排障用）。
azuracast:sync:run：执行每分钟的同步任务集（Now Playing 刷新、统计聚合等）。实测执行后静默退出（exit 0，无输出），属正常现象——它把工作派发进队列即返回。
azuracast:sync:nowplaying / azuracast:sync:nowplaying:station <shortcode>：立即刷新「正在播放」数据（外部展示页数据不同步时排障用）。
azuracast:sync:task <task> [--force]：手动触发某个定时任务（如 check_updates），--force 跳过系统状态检查强制执行。

4.9 缓存清理与表优化：azuracast:cache:clear / azuracast:debug:optimize-tables

界面改动后数据不刷新、或升级后表现异常，先清缓存：

./azuracast-cli azuracast:cache:clear

实测回显：


 [OK] Local cache flushed.

数据库长期运行后可优化表（低峰期执行）：

./azuracast-cli azuracast:debug:optimize-tables

4.10 数据库结构迁移：azuracast:setup:migrate / rollback

升级或恢复备份后把数据库结构对齐到当前程序版本：

./azuracast-cli azuracast:setup:migrate

azuracast:setup:rollback 与 azuracast:setup:rollback <版本> 配合 docker.sh 的版本回滚使用：先回滚程序版本，再回滚数据库结构。这两个命令涉及不可逆的结构变更，执行前必须已有 4.1 的备份。

五、docker.sh 安装管理命令详解

/var/azuracast/docker.sh 是官方安装与生命周期脚本（首次安装时由官方文档三命令下载），子命令一览：

子命令	作用	实测/来源
`install`	全新安装（自动装 Docker/Compose、生成配置、拉镜像、启动）	官方文档（查询日期 2026-10-27）
`install-docker` / `install-docker-compose`	单独安装/修复 Docker 或 Compose 组件	官方文档排障节
`update`	升级到当前频道最新版	官方更新文档
`rollback`	交互回滚到指定 stable 版本	脚本内置（实测脚本存在该子命令）
`setup-release`	切换更新频道（stable / rolling / 指定版本快照）	脚本内置
`change-ports`	修改对外端口映射	脚本内置
`up` / `down` / `restart`	启动 / 停止（60 秒优雅超时）/ 重启全套服务	脚本内置

常用组合示例：

cd /var/azuracast

# 无人值守安装（官方文档 Unattended Installation 原样命令）
mkdir -p /var/azuracast && cd /var/azuracast
curl -fsSL https://raw.githubusercontent.com/AzuraCast/AzuraCast/main/docker.sh > docker.sh
chmod a+x docker.sh
yes 'Y' | ./docker.sh setup-release
yes '' | ./docker.sh install

# 日常运维
./docker.sh restart      # 重启全套服务（升级配置后）
./docker.sh update       # 升级到最新 stable
./docker.sh rollback     # 升级出问题时回滚

⚠️ 注意：rollback 回滚程序版本后，数据库结构可能仍停留在新版，需按 4.10 执行 azuracast:setup:rollback <目标版本> 同步回退数据库，两步缺一不可。这也是为什么每次升级前先备份。

六、注意事项

执行身份：全部命令以 root/sudo 在安装目录执行；docker.sh 必须在 /var/azuracast 目录内运行（脚本开头强制切目录）。
破坏性命令：restore、setup:rollback、station-queues:clear 不可逆或影响播出，执行前先备份并确认电台空闲时段。
常驻命令：queue:process 会常驻不退出，交给系统调度器托管，不要在交互终端裸跑。
版本一致性：CLI 输出的版本头（AzuraCast Command Line Tools (Production) 0.24.0）应与 Web 界面「System Settings」中显示版本一致；不一致说明升级中断，重跑 ./docker.sh update 收尾。
临时密码安全：reset-password 输出的一次性密码与 login-token 生成的链接等同凭据，即用即弃，不落聊天记录。

七、常见问题（FAQ）

Q1：执行任何 azuracast-cli 命令都报数据库连接错误？

先看服务状态：cd /var/azuracast && docker compose ps 确认 web 服务为 Up；再核对 azuracast.env 中 MYSQL_PASSWORD 是否最近改过——该值只在数据库卷首次初始化时写入，后改不同步（需在数据库内 ALTER USER 同步），对不上就会全线报连接失败。修正口令后 ./docker.sh restart。

Q2：备份命令报 Device or resource busy？

path 写到了挂载点本身（详见 4.1 踩坑实录）。把备份路径改成挂载点下的子路径即可，例如 /var/azuracast/backups/station-full。

Q3：媒体重处理后时长还是不对？

media:reprocess 只做标记，实际分析走异步队列。等待数分钟后用 Web 界面确认；若队列积压，检查消息队列服务是否健康（azuracast:queue:clear 清积压后让系统自动重派发）。

Q4：sync:run 执行完没有任何输出，是失败了吗？

不是。实测该命令派发任务后静默返回（exit 0）。要确认任务真的在跑，看 Web 界面「正在播放」是否随曲目切换更新，或改跑 azuracast:sync:nowplaying:station quzuo_fm 观察即时效果。

Q5：忘记管理员密码又不想等邮件重置？

直接 ./azuracast-cli azuracast:account:reset-password <邮箱>，命令会打印临时密码（见 4.5 实测回显），用它登录 Web 后立刻改成正式密码。

八、参考链接

官方命令行接口文档：https://www.azuracast.com/docs/administration/cli/
官方备份与恢复文档：https://www.azuracast.com/docs/administration/backup/
官方 Docker 安装文档（docker.sh 安装命令来源）：https://www.azuracast.com/docs/getting-started/installation/docker
GitHub 仓库：https://github.com/AzuraCast/AzuraCast
版本发布页（0.24.0）：https://github.com/AzuraCast/AzuraCast/releases/tag/0.24.0