AzuraCast Docker Compose 部署实战

AzuraCast 0.24.0 官方 Docker 脚本与手工 Compose 双形态部署实战：安装向导、建台、上传曲目、Icecast 拉流验证、端口规划、备份恢复与真实排障实录，Ubuntu 22.04 全量实测。

AzuraCastAzuraCast网络电台DockerDocker Compose流媒体音乐2026/10/27

AzuraCast Docker Compose 部署实战

目标：在一台 Ubuntu 22.04 服务器上，从零完成 AzuraCast 0.24.0 网络电台套件的安装、初始化向导、电台创建、曲目上传与对外串流验证，并沉淀备份与日常运维命令。本文全部命令与回显已在 Ubuntu 22.04（x86_64，Docker 29.9.2 + Compose v5.6.1）真实环境实测通过。

一、环境信息

本文实测所用的服务器环境与软件版本如下，读者可对照检查自己的环境：

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • Docker：29.9.2（docker --version 实测）
  • Docker Compose：v5.6.1（docker compose version 实测）
  • AzuraCast：0.24.0（官方 stable 频道最新稳定版，2026-10-25 发布；版本实查自 GitHub Releases，查询日期 2026-10-27）
  • 部署形态：官方 Docker 发行（单套件集成全部组件），安装基目录 /var/azuracast
  • 实测网络说明：宿主机 80/443 端口已被既有服务占用，本文将 Web 端口映射改为宿主 8142（HTTP）/8143（HTTPS），串流端口段 8000–8496 按默认逐一映射。若你的服务器 80/443 空闲，可沿用官方默认值，两者仅端口不同。
  • 下载渠道说明：官方镜像仓库 ghcr.io/azuracast/azuracast 在国内直连拉取缓慢时，Docker 守护进程已配置 HTTP 代理（192.168.1.62:7897）自动加速；官方安装脚本 docker.sh 通过 GitHub 原始内容地址下载，当时实测可直连获取。

AzuraCast 的官方安装方式只有一种——官方 Docker 安装脚本（docker.sh）。它内部使用 Docker Compose 拉起全套服务，因此「官方脚本安装」与「手工 Compose 编排」本质是同一套 Compose 形态的两种入口。本文先走官方脚本主线，再给出手工 Compose 方案用于自定义端口/内网隔离等场景。

💡 技术拓展：网络电台的「串流引擎」不止一种。AzuraCast 内置了两个引擎并允许在电台级别选择——

引擎角色特点
Icecast 2前端（面向听众）开源、mp3/ogg/aac 等多格式、广泛兼容，AzuraCast 默认
SHOUTcast 2前端（面向听众）Nullsoft 系老牌协议，兼容部分老播放器，需在 Web 界面同意其许可后安装
Liquidsoap后端（编码推流）函数式音频编排语言，负责自动播出、交叉淡化、直播接入，AzuraCast 默认

本文使用默认组合：Icecast 2 前端 + Liquidsoap 后端。

二、前置条件

安装前逐项确认，缺一不可：

  1. 64 位 x86_64（amd64）或 ARM64 服务器，最低配置 2 核 CPU / 2GB 内存 / 20GB 磁盘；官方推荐 4 核 / 4GB 内存 / 40GB 磁盘，可支撑 5–10 个电台（来源：官方 Requirements 页，查询日期 2026-10-27）。
  2. Linux 发行版首选 Ubuntu 22.04 LTS；已知不兼容 OpenVZ/LXC 虚拟化主机与 CentOS（其转向 Podman，与官方脚本不兼容）。
  3. 具备 root 或 sudo 权限，且已安装 curl、git、sudo 三个基础包：
sudo apt update && sudo apt install -y curl git sudo
  1. 服务器未安装过 Docker/Compose 也可以——官方脚本会自动安装。已安装则版本不低于官方脚本要求即可（本文实测 29.9.2 可用）。
  2. 放行防火墙端口：Web 端口（默认 80/443）、SFTP 端口 2022（可选功能）、电台串流端口段 8000–8499（多电台时按需逐段放行）。
# 实测：确认本机端口占用情况，规划映射
ss -ltn | awk '{print $4}' | grep -oE '[0-9]+$' | sort -n | uniq | head -20

实测回显（节选）：

22
53
631
8000
8005
...

⚠️ 注意：若 80/443 已被 Nginx 等服务占用，不要停掉既有服务，参照第七章「端口规划与自定义映射」把 AzuraCast 的 Web 端口改到空闲端口（本文实测使用 8142/8143）。

三、官方脚本安装（主线方案）

3.1 方案说明

官方 Docker 安装脚本 docker.sh 是一个自举脚本：首次执行 install 子命令时，它会安装（或校验）Docker 与 Docker Compose、生成 azuracast.env 与 docker-compose.yml、拉取镜像并启动全套服务。这是官方唯一推荐的安装方式，支持 x86_64 与 ARM64。

3.2 下载脚本并执行安装

# 官方标准安装三步（来源：官方文档 Install AzuraCast with Docker，查询日期 2026-10-27）
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
./docker.sh install

安装器会依次打印：检测系统架构 → 安装 Docker（如缺失）→ 安装 Docker Compose（如缺失）→ 询问安装渠道（Stable / Rolling）→ 生成 azuracast.env 与 docker-compose.yml → 拉取镜像 → 启动服务。实测环境拉取镜像阶段耗时最长（镜像约 1–2 GB），其余步骤均在数分钟内完成。

⚠️ 网络说明：raw.githubusercontent.com 与 ghcr.io 在部分网络环境直连缓慢。实测环境 Docker 守护进程已配置代理 192.168.1.62:7897，镜像拉取可自动加速；脚本下载如遇超时，可为 curl 追加代理：curl -x http://192.168.1.62:7897 -fsSL <URL> > docker.sh。

3.3 无人值守安装（可选）

自动化场景（cloud-init、装机脚本）可跳过全部交互：

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
# 固定使用 stable 频道（默认是 rolling 频道，生产建议 stable）
yes 'Y' | ./docker.sh setup-release
# 全部询问默认回答，开始安装
yes '' | ./docker.sh install

说明：setup-release 用于把更新频道固定为 stable；不执行该步则安装器默认选择 rolling（滚动更新）频道。频道后续可随时用 ./docker.sh setup-release 切换。

3.4 验证服务状态

安装完成后确认全部服务已拉起：

cd /var/azuracast
docker compose ps

实测回显（端口列表很长，此处节选首尾）：

NAME                   IMAGE                                COMMAND                  SERVICE   CREATED       STATUS       PORTS
azuracast-0.24.0-web   ghcr.io/azuracast/azuracast:0.24.0   "tini -- /usr/local/…"   web       4 hours ago   Up 4 hours   0.0.0.0:2022->2022/tcp, ... 0.0.0.0:8142->80/tcp, 0.0.0.0:8143->443/tcp

再验证 Web 服务可访问（本文宿主端口为 8142，官方默认 80）：

curl -sI http://127.0.0.1:8142/ | head -8

实测回显：

HTTP/1.1 302 Found
Server: nginx
Date: Tue, 27 Oct 2026 06:23:12 GMT
Content-Type: text/html; charset=utf-8
Connection: keep-alive
X-Powered-By: PHP/8.5.12
Location: /setup

返回 302 且 Location: /setup 即安装成功——系统尚未初始化，正在等待你完成安装向导。

四、初始化向导与建台实测

4.1 创建超级管理员账号

浏览器打开 http://<服务器IP>:8142/（官方默认端口环境为 http://<服务器IP>/），自动跳转到安装向导。向导共两步：

  1. 系统设置：填写站点 Base URL（本文填 https://www.quzuo.net）、实例名称（本文填 Quzuo 实测站点）、时区（Asia/Shanghai）。
  2. 创建超级管理员：填写邮箱、姓名、密码。本文使用演示账号：邮箱 admin@quzuo.net、用户名 admin、密码 q1w2e3r4。

⚠️ 注意：该账号是系统唯一的超级管理员，生产环境务必使用强密码；q1w2e3r4 仅为本文演示口令。

提交后进入登录页，用上述账号登录即可看到管理面板。实测可通过命令行确认账号已生效（登录后创建 API Key，后续脚本化管理都用它）：

# 在 Web 界面：右上角头像 → API Keys → Create New Key
# 生成的 Key 形如 "ID:Token" 两段式

4.2 创建第一个电台

登录后进入「Stations」→「Create New Station」：

  • Name：Quzuo FM（系统自动生成 Shortcode：quzuo_fm，电台所有 URL 都基于它）
  • Description：AzuraCast 测试电台站
  • Genre：Test
  • Timezone：Asia/Shanghai

保存后系统自动完成三件事：分配串流端口（本台为前端 8000、DJ 直播端口 8005、Liquidsoap Telnet 端口 8004，均落在 AUTO_ASSIGN_PORT_MIN/MAX 区间内）、生成 Liquidsoap 与 Icecast 配置、启动播出进程。用 API 确认电台已就绪：

curl -s -H 'X-API-Key: 6176e5175e01d9c5:c05cfa6cfe007454dcea470d8fd329be' 'http://127.0.0.1:8142/api/stations'

实测回显（节选）：

[{"id":1,"name":"Quzuo FM","shortcode":"quzuo_fm","description":"AzuraCast 测试电台站","frontend":"icecast","backend":"liquidsoap","timezone":"Asia/Shanghai","listen_url":"http://127.0.0.1/listen/quzuo_fm/radio.mp3",...}]

4.3 上传曲目并开播

电台创建后媒体库为空，系统自动以「离线占位流」播出。上传曲目有三种方式：Web 界面拖拽、SFTP（端口 2022）、API。本文用 API 上传一首本地测试曲目：

curl -s -X POST -H 'X-API-Key: 6176e5175e01d9c5:c05cfa6cfe007454dcea470d8fd329be' \
  -F 'file=@/root/tone_a.mp3' \
  'http://127.0.0.1:8142/api/station/quzuo_fm/files/upload'

上传成功后系统异步分析音频（时长/码率/CUE），几秒后将其加入「Default Playlist（默认播放列表）」，自动播出队列随即取用。验证当前正在播出：

curl -s -H 'X-API-Key: 6176e5175e01d9c5:c05cfa6cfe007454dcea470d8fd329be' 'http://127.0.0.1:8142/api/stations' | python3 -m json.tool | grep -A2 '"now_playing"'

实测回显（节选）：

"now_playing": {
    "sh_id": 268435457,
    "played_at": 1793080000,
    "duration": 20,
    "playlist": "Default Playlist",
    "stream": "Quzuo FM",
    "title": "Quzuo Request Song D",

4.4 拉流验证（Icecast 直连）

电台串流端口（本台 8000）对宿主机直接暴露了 Icecast 挂载点。Icecast 内部挂载名是 /radio.mp3（对外展示地址 /listen/quzuo_fm/radio.mp3 是 Web 网关层的别名，见第八章排障实录）。直接拉流 20 秒验证音频真实可播：

curl -s --max-time 20 -o /tmp/listen-probe.mp3 -w 'HTTP %{http_code}, %{size_download} bytes, %{speed_download} B/s, type: %{content_type}\n' http://127.0.0.1:8000/radio.mp3

实测回显：

HTTP 200, 543826 bytes, 27190 B/s, type: audio/mpeg

用 ffprobe 校验流参数（192 kbps CBR mp3，与电台前端设置一致）：

ffprobe -v error -show_entries format=format_name,bit_rate -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 /tmp/listen-probe.mp3

实测回显：

format_name=mp3
bit_rate=192000
codec_name=mp3
sample_rate=44100
channels=2

至此「安装 → 初始化 → 建台 → 上传 → 对外串流」全链路闭环。外部听众访问地址为 http://<服务器IP>:8000/radio.mp3（直连 Icecast）或 http://<服务器IP>:8142/listen/quzuo_fm/radio.mp3（经 Web 网关）。

五、数据持久化说明

官方 Compose 文件把全部状态数据落在命名卷上，升级、重启均不丢数据：

卷名容器内路径内容
db_data/var/lib/mysqlMariaDB 数据库（歌曲历史、统计、账号、电台配置）
station_data/var/azuracast/stations各电台媒体库、录音、播客、Liquidsoap/Icecast 配置
www_uploads/var/azuracast/storage/uploadsWeb 上传的临时资源、自定义 JS/CSS
backups/var/azuracast/backups备份产物默认输出目录
sftpgo_data/var/azuracast/storage/sftpgoSFTP 服务器（SFTPGo）账号数据
geolite_install/var/azuracast/storage/geoip听众地理定位数据库（DBIP）
shoutcast2_install/var/azuracast/storage/shoutcast2SHOUTcast 2 按需安装目录
stereo_tool_install / rsas_install/var/azuracast/storage/...Stereo Tool / RSAS 音频处理组件按需安装目录
acme/var/azuracast/storage/acmeLet's Encrypt 证书数据

关键解读：媒体文件不在数据库里而在 station_data 卷中，因此「仅备份数据库」不能恢复媒体库；做整机备份时务必包含 db_data 与 station_data 两卷（或直接用第十章的 azuracast:backup 全量备份命令，它会同时打包两者）。

六、环境变量表

安装脚本在 /var/azuracast/azuracast.env 生成系统级环境变量（官方模板默认值，全部实测确认）：

变量默认值说明
APPLICATION_ENVproduction运行环境标识；仅开发调试时改 development
COMPOSER_PLUGIN_MODEfalse是否启用 Composer 插件扩展机制
AUTO_ASSIGN_PORT_MIN8000新电台串流端口自动分配区间下限
AUTO_ASSIGN_PORT_MAX8499自动分配区间上限；与 Compose 端口映射段保持一致
SHOW_DETAILED_ERRORSfalse页面是否显示详细堆栈；生产保持 false
MYSQL_PASSWORDazur4c457应用连接 MariaDB 的口令；官方公开默认值，生产必须修改
MYSQL_RANDOM_ROOT_PASSWORDyes数据库 root 口令随机化（在数据库初始化时生成）

修改方式：编辑 /var/azuracast/azuracast.env 后执行 docker compose up -d 重建生效（幂等，数据不丢）。例如生产修改数据库口令：

# 1. 编辑 env 文件，将 MYSQL_PASSWORD 改为新值
sudo vim /var/azuracast/azuracast.env
# 2. 重建服务生效（若数据库卷已初始化过，需同步在数据库内执行 ALTER USER，见第十一章 FAQ）
cd /var/azuracast && docker compose up -d

⚠️ 注意：MYSQL_PASSWORD 只在 MariaDB 数据卷首次初始化时写入。已初始化的环境里改该值需两步：改 env 文件 + 进入数据库执行 ALTER USER 'azuracast'@'%' IDENTIFIED BY '<新口令>'，否则应用将无法连接数据库。

七、端口规划与自定义映射

7.1 默认端口清单

端口用途必需性
80 / 443Web 管理界面 + 公开播放页 + 网关层听流地址必需
2022SFTP 媒体管理（SFTPGo）可选
8000–8499电台串流端口自动分配池：每台占用 3 个（前端 / DJ 直播 / Liquidsoap Telnet）必需（按电台数）
9000容器内部健康检查端口，无需对外映射内部

端口分配规律：第 1 个电台占 8000/8004/8005（前端/Telnet/DJ），第 2 个占 8010/8014/8015，间隔 10 递增——官方 Compose 按 5 端口粒度逐段映射到 8496，即最多预置约 100 个电台的端口池。

7.2 实测环境的端口调整

本文实测服务器 80/443 已被占用，因此把 Web 端口改为 8142/8143，compose 文件中相应两行写为：

    ports:
      - '8142:80'
      - '8143:443'
      - '2022:2022'
      - '8000:8000'
      # ...8005 至 8496 的电台端口池按官方模板逐段映射，实测文件全量见 7.3
      - '8495:8495'
      - '8496:8496'

电台串流端口（8000）保持默认映射，因此 4.4 节的听流地址不变。若服务器上 8000 段也被占用，可整体调整 AUTO_ASSIGN_PORT_MIN/MAX 并同步修改 compose 端口池，再重启电台（Web 界面电台列表 → Restart Broadcasting，或命令行 azuracast-cli azuracast:radio:restart）。

💡 技术拓展：把内部端口映射到宿主不同端口（8142:80）与「修改服务监听端口」是两回事。前者只改对外入口，AzuraCast 内部各组件（80/8000/2022）之间互访不变，是端口冲突时的首选；后者需要同时改应用配置与映射，容易遗漏联动项，除非有明确需求否则不推荐。

7.3 手工 Compose 部署方案（备选）

不使用官方脚本、需要把部署纳入自有配置管理（Git/Ansible）时，可用手工 Compose。在安装目录放置两份文件——系统环境文件 azuracast.env（内容与第六章表格一致）与项目环境文件 .env（声明镜像版本，便于一键升级）：

# /var/azuracast/.env
AZURACAST_VERSION=0.24.0

编排文件 docker-compose.yml（实测全量，单服务全栈形态）：

name: azuracast-0.24.0-stack

services:
  web:
    container_name: azuracast-0.24.0-web
    image: "ghcr.io/azuracast/azuracast:${AZURACAST_VERSION}"
    ports:
      - '8142:80'
      - '8143:443'
      - '2022:2022'
      - '8000:8000'
      - '8005:8005'
      - '8006:8006'
      - '8010:8010'
      - '8015:8015'
      - '8016:8016'
      - '8020:8020'
      - '8025:8025'
      - '8026:8026'
      - '8030:8030'
      - '8035:8035'
      - '8036:8036'
      - '8040:8040'
      - '8045:8045'
      - '8046:8046'
      - '8050:8050'
      - '8055:8055'
      - '8056:8056'
      - '8060:8060'
      - '8065:8065'
      - '8066:8066'
      - '8070:8070'
      - '8075:8075'
      - '8076:8076'
      - '8080:8080'
      - '8085:8085'
      - '8086:8086'
      - '8090:8090'
      - '8095:8095'
      - '8096:8096'
      - '8100:8100'
      - '8105:8105'
      - '8106:8106'
      - '8110:8110'
      - '8115:8115'
      - '8116:8116'
      - '8120:8120'
      - '8125:8125'
      - '8126:8126'
      - '8135:8135'
      - '8136:8136'
      - '8145:8145'
      - '8146:8146'
      - '8155:8155'
      - '8156:8156'
      - '8160:8160'
      - '8165:8165'
      - '8166:8166'
      - '8170:8170'
      - '8175:8175'
      - '8176:8176'
      - '8180:8180'
      - '8185:8185'
      - '8186:8186'
      - '8190:8190'
      - '8195:8195'
      - '8196:8196'
      - '8200:8200'
      - '8205:8205'
      - '8206:8206'
      - '8210:8210'
      - '8215:8215'
      - '8216:8216'
      - '8220:8220'
      - '8225:8225'
      - '8226:8226'
      - '8230:8230'
      - '8235:8235'
      - '8236:8236'
      - '8240:8240'
      - '8245:8245'
      - '8246:8246'
      - '8250:8250'
      - '8255:8255'
      - '8256:8256'
      - '8260:8260'
      - '8265:8265'
      - '8266:8266'
      - '8270:8270'
      - '8275:8275'
      - '8276:8276'
      - '8280:8280'
      - '8285:8285'
      - '8286:8286'
      - '8290:8290'
      - '8295:8295'
      - '8296:8296'
      - '8300:8300'
      - '8305:8305'
      - '8306:8306'
      - '8310:8310'
      - '8315:8315'
      - '8316:8316'
      - '8320:8320'
      - '8325:8325'
      - '8326:8326'
      - '8330:8330'
      - '8335:8335'
      - '8336:8336'
      - '8340:8340'
      - '8345:8345'
      - '8346:8346'
      - '8350:8350'
      - '8355:8355'
      - '8356:8356'
      - '8360:8360'
      - '8365:8365'
      - '8366:8366'
      - '8370:8370'
      - '8375:8375'
      - '8376:8376'
      - '8380:8380'
      - '8385:8385'
      - '8386:8386'
      - '8390:8390'
      - '8395:8395'
      - '8396:8396'
      - '8400:8400'
      - '8405:8405'
      - '8406:8406'
      - '8410:8410'
      - '8415:8415'
      - '8416:8416'
      - '8420:8420'
      - '8425:8425'
      - '8426:8426'
      - '8430:8430'
      - '8435:8435'
      - '8436:8436'
      - '8440:8440'
      - '8445:8445'
      - '8446:8446'
      - '8450:8450'
      - '8455:8455'
      - '8456:8456'
      - '8460:8460'
      - '8465:8465'
      - '8466:8466'
      - '8470:8470'
      - '8475:8475'
      - '8476:8476'
      - '8480:8480'
      - '8485:8485'
      - '8486:8486'
      - '8490:8490'
      - '8495:8495'
      - '8496:8496'
    env_file:
      - azuracast.env
      - .env
    volumes:
      - station_data:/var/azuracast/stations
      - backups:/var/azuracast/backups
      - db_data:/var/lib/mysql
      - www_uploads:/var/azuracast/storage/uploads
      - shoutcast2_install:/var/azuracast/storage/shoutcast2
      - stereo_tool_install:/var/azuracast/storage/stereo_tool
      - rsas_install:/var/azuracast/storage/rsas
      - geolite_install:/var/azuracast/storage/geoip
      - sftpgo_data:/var/azuracast/storage/sftpgo
      - acme:/var/azuracast/storage/acme
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    logging:
      options:
        max-size: "1m"
        max-file: "5"
    networks:
      - azuracast-0.24.0-net

networks:
  azuracast-0.24.0-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.70.0/24

volumes:
  db_data: { }
  acme: { }
  shoutcast2_install: { }
  stereo_tool_install: { }
  rsas_install: { }
  geolite_install: { }
  sftpgo_data: { }
  station_data: { }
  www_uploads: { }
  backups: { }

配置解读：name: 固定 Compose 项目名，避免多套件共存时项目名冲突；env_file 叠加系统 env 与版本 env 两层；nofile 65536 抬高文件句柄上限（听众并发连接多时必需）；logging 限制日志体积防止写满磁盘；自定义 bridge 网络固定子网，便于与服务器上其他部署共存时做网段规划。

启动并验证：

cd /var/azuracast
docker compose up -d
docker compose up -d   # 幂等性验证：重复执行无副作用

实测回显：

 Container azuracast-0.24.0-web Running

7.4 两种入口对比

维度官方脚本（./docker.sh install）手工 Compose
Docker/Compose 安装自动安装需自行预装
compose 文件与 env自动生成、随版本更新维护手工维护
版本升级./docker.sh update 一条命令改 .env 版本号 + docker compose up -d
适用场景标准单机安装（绝大多数用户）自定义网段/端口编排、配置统一纳管

选择建议：生产单机直接用官方脚本；只有当安装需要融入自己的基础设施即代码体系、或端口/网段需要精细规划时才走手工 Compose。

八、常见问题（FAQ）

Q1：curl http://127.0.0.1:8000/listen/quzuo_fm/radio.mp3 返回 404「The file you requested could not be found」，但 Icecast 状态页明明显示挂载在播？

这是本文实测踩到的真实坑。AzuraCast 对 Icecast 挂载名与对外听流地址做了分层：Icecast 进程内部挂载名是 /radio.mp3（stations/quzuo_fm/config/icecast.xml 中的 <mount-name>），而 /listen/quzuo_fm/radio.mp3 是 Web 网关（Nginx 层）提供的对外别名。两者都能听流，但直连串流端口时必须用内部挂载名：

# 直连 Icecast（串流端口 8000）→ 用挂载名 /radio.mp3
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/radio.mp3

实测回显：

200

另外注意：若电台刚被重启（azuracast:radio:restart 或修改电台配置），Icecast 需数秒重建挂载，期间直连老挂载会短暂 404，等自动播出恢复即可。

Q2：宿主机 80/443 已被占用，安装器报端口绑定失败？

不要卸载既有服务。先完成安装（安装本身不校验 80），再把 compose 文件中 '80:80'、'443:443' 两行改为空闲端口（本文 '8142:80'、'8143:443'），docker compose up -d 重建。电台串流端口同理。验证：curl -sI http://127.0.0.1:8142/ 返回 302 即恢复。

Q3：修改 MYSQL_PASSWORD 后应用报数据库连接失败？

该变量只在数据卷首次初始化时生效。已初始化的环境需两步：改 env 文件后，还需在数据库内同步修改应用账号口令（ALTER USER 'azuracast'@'%' IDENTIFIED BY '<新口令>'），再 docker compose up -d。顺序反了会导致应用起不来。

Q4：拉取 ghcr.io/azuracast/azuracast 镜像极慢或超时？

国内网络对 ghcr.io 限速常见。为 Docker 守护进程配置 HTTP 代理（/etc/systemd/system/docker.service.d/http-proxy.conf 中 HTTPS_PROXY=http://192.168.1.62:7897 后 systemctl daemon-reload && systemctl restart docker），或使用支持该镜像的国内镜像加速器。实测环境配置代理后拉取正常。

Q5：电台串流端口从 8000 改不回默认值？

端口是电台属性，在 Web 界面电台设置「Frontend（Icecast）」页修改 port 字段，保存后执行 azuracast-cli azuracast:radio:restart <电台名> 重启播出进程。确认 compose 已映射对应宿主端口，否则外部无法访问。

九、升级与回滚

官方脚本形态下升级一条命令（稳定频道下升级到 stable 最新版）：

cd /var/azuracast
./docker.sh update

回滚到指定稳定版（实测脚本内置子命令）：

# 交互式选择目标 stable 版本
./docker.sh rollback

手工 Compose 形态下升级=改 .env 中 AZURACAST_VERSION 后 docker compose up -d；回滚同理改回旧版本号。两种形态的数据都在命名卷中，版本切换不丢数据；升级前建议先执行一次全量备份（第十章）。

十、备份与恢复

10.1 全量备份

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: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

原因是备份流程清理临时目录时试图删除挂载点。给 path 追加一层子路径（如 /var/azuracast/backups/station-full）即可。加 --exclude-media 可只备数据库与统计（速度快，适合高频定时备份），媒体库另用文件系统级备份覆盖 station_data 卷。

10.2 恢复

azuracast-cli azuracast:restore /var/azuracast/backups/station-full.zip

恢复命令会停播出、清库、导入 SQL 并解压媒体。若备份来自旧版本 AzuraCast，加 --release 指定来源稳定版本、加 --restore 强制恢复流程。恢复完成后执行 azuracast-cli azuracast:setup:migrate 把数据库结构对齐到当前版本，再重启电台。

十一、卸载与清理

# 1. 停止并删除服务（数据卷保留）
cd /var/azuracast && docker compose down --timeout 60

# 2. 连同全部数据卷删除（彻底清除，媒体/数据库全部丢失，先确认已有备份）
docker compose down -v

# 3. 删除安装目录
sudo rm -rf /var/azuracast

若用官方脚本安装且需要连 Docker 一起清，请先确认服务器上没有其他 Docker 业务后再卸载 Docker 本体。

十二、参考链接