AzuraCast 配置参数详解

目标：系统梳理 AzuraCast 0.24.0 的三层配置体系——系统级环境变量（azuracast.env）、系统设置库（settings）、电台级串流参数（Icecast 前端 + Liquidsoap 后端），逐项说明含义、默认值与修改方式，并给出可直接套用的生产配置模板。全部参数均取自 0.24.0 真实环境实测（文件内容、CLI 回显与 API 配置体）。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• AzuraCast：0.24.0（stable，2026-10-25 发布；版本实查自 GitHub Releases，查询日期 2026-10-27）
• 安装目录：/var/azuracast（官方脚本安装形态）
• 系统级配置文件：/var/azuracast/azuracast.env（安装脚本生成）
• 实测电台：Quzuo FM（shortcode quzuo_fm，Icecast 192 kbps mp3，串流端口 8000，DJ 端口 8005，Telnet 端口 8004）
• 演示账号：admin@quzuo.net / q1w2e3r4（Super Administrator）

二、前置条件

• 已完成安装（见 《AzuraCast Docker Compose 部署实战》第三章），可正常登录管理界面。
• 命令行操作需要 root/sudo；本文引用的 CLI 用法在 《AzuraCast 常用 CLI 命令详解》有逐条实测回显。
• 修改系统级环境变量后需要重建服务才能生效，请安排在低峰期。

三、参数查看与修改方式

AzuraCast 的配置分布在三层，各有各的查看与修改通道：

验证修改是否落地的实测手段：

# 1) 系统环境变量：读文件确认
grep -vE '^\s*(#|$)' /var/azuracast/azuracast.env

实测回显：

APPLICATION_ENV=production
COMPOSER_PLUGIN_MODE=false
AUTO_ASSIGN_PORT_MIN=8000
AUTO_ASSIGN_PORT_MAX=8499
SHOW_DETAILED_ERRORS=false
MYSQL_PASSWORD=azur4c457
MYSQL_RANDOM_ROOT_PASSWORD=yes

# 2) 系统设置库：CLI 全量列出
cd /var/azuracast && ./azuracast-cli azuracast:settings:list | head -12

实测回显（节选）：

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

# 3) 电台级参数：API 读取（X-API-Key 换成你自己的）
curl -s -H 'X-API-Key: 6176e5175e01d9c5:c05cfa6cfe007454dcea470d8fd329be' \
  'http://127.0.0.1:8142/api/admin/station/1' | python3 -m json.tool | head -12

实测回显（节选）：

{
    "name": "Quzuo FM",
    "short_name": "quzuo_fm",
    "is_enabled": true,
    "frontend_type": "icecast",
    "frontend_config": {
        "admin_pw": "JDKR4Ae3",
        "port": 8000,
        ...
    },
    "backend_type": "liquidsoap",

⚠️ 注意：电台生成的底层配置文件（如 stations/quzuo_fm/config/icecast.xml）是系统从数据库参数渲染出来的产物。手工改这些 XML 会在下次电台重启时被覆盖；要持久修改请改 Web 设置页或 API 参数。

四、参数总览

4.1 系统环境变量（azuracast.env 全键）

4.2 系统设置库（settings 键分组）

实测环境全量键按功能分组：

• 标识与基础：app_unique_identifier（实例唯一 ID，安装时生成）、base_url（站点对外地址）、instance_name（实例名）、setup_complete_time（向导完成时间戳）、homepage_redirect_url
• 播放与展示：use_radio_proxy（网关听流代理开关）、prefer_browser_url、public_theme、hide_product_name、hide_album_art、default_album_art_url、use_external_album_art_when_processing_media、use_external_album_art_in_apis
• 历史与统计：history_keep_days（实测 60 天）、analytics、ip_source
• 权限与接口：api_access_control、enable_liquidsoap_editing、enable_all_webhooks、filter_local_user_urls、enable_static_nowplaying
• 备份自动化：backup_enabled、backup_time_code、backup_exclude_media、backup_keep_copies、backup_storage_location、backup_format、backup_last_run、backup_last_output
• 外部服务：last_fm_api_key、geolite_license_key、geolite_last_run、avatar_service、avatar_default_url
• 邮件：mail_enabled、mail_sender_name、mail_sender_email、mail_smtp_host、mail_smtp_port、mail_smtp_username、mail_smtp_password、mail_smtp_secure
• 证书：acme_email、acme_domains
• 定制注入：public_custom_css、public_custom_js、internal_custom_css
• 升级：check_for_updates、update_results、update_last_run、sync_disabled、sync_last_run

4.3 电台级参数分组

实测电台（API 配置体）全部字段分四组：基础属性（名称/shortcode/时区/开关）、前端 frontend_config（Icecast 串流参数）、后端 backend_config（Liquidsoap 播出参数）、存储与限额（媒体/录音/播客存储位置、max_bitrate/max_mounts/max_hls_streams 配额）。详细逐项见第六章。

五、系统级参数详解

5.1 应用运行环境（APPLICATION_ENV / LOG_LEVEL / SHOW_DETAILED_ERRORS）

三键共同决定「排障友好度」：APPLICATION_ENV=production 关闭开发态行为；SHOW_DETAILED_ERRORS=false 隐藏页面堆栈（防信息泄露）；LOG_LEVEL 默认 info，临时排障时可放开为 debug。实测环境三者均保持安全默认。仅在被官方支持人员要求时才把 APPLICATION_ENV 临时改为 development，用完改回。

5.2 端口分配（AUTO_ASSIGN_PORT_MIN / MAX）

新建电台时系统按「每台 3 端口（前端串流 / DJ 直播 / Liquidsoap Telnet）」在区间内顺序分配，实测第 1 台占用 8000/8004/8005。两个键与 Compose 的端口映射池（官方模板默认映射 8000–8496）必须联动：只改 env 不改端口池，新电台分配到的端口对外不可达。规划公式：可建电台数 ≈ (MAX − MIN + 1) / 10（官方按 10 端口一格递增预留）。

5.3 数据库参数（MYSQL_*）

官方注释明确警告：数据库初始化后不要再改这些值。MYSQL_PASSWORD 只在数据卷首次初始化时写入数据库；已运行环境修改需在数据库内同步 ALTER USER（见第八章 FAQ）。MYSQL_RANDOM_ROOT_PASSWORD=yes 保证数据库 root 不使用固定口令，root 凭据不落盘明文。

5.4 备份自动化（backup_* 组）

这组 settings 键对应 Web 界面「Administration → Backup & Restore」的定时备份：

推荐生产值：backup_enabled=1、backup_time_code=3（凌晨 3 点）、backup_exclude_media=1（媒体用文件级快照另行覆盖）、backup_keep_copies=7。启用后 backup_last_run 会记录上次执行时间，可用于巡检备份是否真的在跑。

5.5 对外展示与品牌（base_url / instance_name / 品牌组）

base_url 是生成对外链接（公开播放页、API 地址、播客 URL）的基准，务必填听众可达的正式地址（本文实测填 https://www.quzuo.net）；填错会导致公开页跳转与 API 返回的链接指向错误主机。hide_product_name=1 可隐藏页面上的 AzuraCast 名称做白标电台。

六、电台级参数详解（Icecast 前端 + Liquidsoap 后端）

6.1 基础属性

6.2 前端串流参数（frontend_config，Icecast）

实测配置体关键字段：

生成的 icecast.xml 侧（实测片段）：<mount-name> 为 /radio.mp3，<listenurl> 展示为 /listen/quzuo_fm/radio.mp3——这解释了「直连串流端口必须用 /radio.mp3」的分层设计。

💡 技术拓展：前端串流格式与码率不止 mp3 一种。电台「Mount Points」页可逐挂载点选择——

格式	编码器	特点	适用
MP3	内置	兼容性最广、老设备都支持；同等音质占用码率略高	默认选择、通用场景
OGG（Vorbis/Opus）	内置	同码率音质更好、开源免授权费；老客户端支持一般	主打网页播放器的新电台
AAC（aac+/HE-AAC）	需同意许可安装	低码率音质佳（32–64 kbps 可听）；部分老播放器不兼容	移动端流量敏感场景

本文实测电台使用默认 MP3 192 kbps，兼顾兼容性与音质。

6.3 后端播出参数（backend_config，Liquidsoap）

实测配置体关键字段：

调整建议：切歌有爆音→开 enable_auto_cue；直播 DJ 断流→加大 dj_buffer；想做「广播感」响度→master_me_preset 选预设并保持 -16 LUFS 目标。

6.4 电台级限额（多租户场景）

max_bitrate / max_mounts / max_hls_streams 用于限制单个电台可创建的挂载点码率与数量上限——对外提供「建站服务」时按套餐配置，自营电台保持默认 0（不限）即可。

七、生产配置模板

模板 A：单台小型电台（2 核 / 4GB 内存 / 40GB 磁盘）

# /var/azuracast/azuracast.env（生产加固版）
APPLICATION_ENV=production
LOG_LEVEL=notice
COMPOSER_PLUGIN_MODE=false
AUTO_ASSIGN_PORT_MIN=8000
AUTO_ASSIGN_PORT_MAX=8100
SHOW_DETAILED_ERRORS=false
MYSQL_PASSWORD=<安装时生成的新口令>
MYSQL_RANDOM_ROOT_PASSWORD=yes

系统设置（azuracast-cli azuracast:settings:set 或 Web 界面）：
backup_enabled=1            # 启用定时备份
backup_time_code=3          # 凌晨 3 点
backup_exclude_media=1      # 媒体走文件级快照
backup_keep_copies=7        # 滚动保留 7 份
history_keep_days=90        # 播放历史留 90 天
base_url=https://radio.example.com

电台级：单挂载点 MP3 192 kbps、max_listeners 按带宽估算（192 kbps ≈ 24 KB/s/人，100 Mbps 带宽理论上限约 500 人）、enable_auto_cue=true、dj_buffer=5。

模板 B：多电台共用实例（4 核 / 8GB 内存 / 200GB 磁盘，5–10 台）

APPLICATION_ENV=production
LOG_LEVEL=warning
AUTO_ASSIGN_PORT_MIN=8000
AUTO_ASSIGN_PORT_MAX=8499
SHOW_DETAILED_ERRORS=false
MYSQL_PASSWORD=<新口令>

电台级差异：为每台单独规划端口（系统自动分配时保持默认区间即可）；开启 master_me_preset 统一响度；record_streams_bitrate=128 落地每日自动录制；banned_user_agents 加入常见恶意采集 UA。内存按官方口径（4GB 支撑 5–10 台业余级负载）预留 20% 余量给 MariaDB 与 Liquidsoap 编码。

八、常见问题（FAQ）

Q1：改了 azuracast.env 为什么不生效？

环境变量在服务启动时注入，改完必须重建：cd /var/azuracast && docker compose up -d。仅改不重建，运行中的进程仍持有旧值。

Q2：MYSQL_PASSWORD 改完应用连不上数据库？

该值只在数据卷首次初始化时写入。已初始化环境需两步：改 env 文件后，再在数据库内执行 ALTER USER 'azuracast'@'%' IDENTIFIED BY '<新口令>' 同步应用账号口令，然后重建服务。这也是官方注释「Once the database has been installed, DO NOT CHANGE」的原因——除非能同步数据库侧，否则不要动。

Q3：电台串流端口想从 8000 换成别的？

两处联动：Web 电台设置「Frontend」页改 port，保存后执行 ./azuracast-cli azuracast:radio:restart quzuo_fm；同时确认 Compose 端口池映射了新端口，否则外部不可达。

Q4：直连 http://<IP>:8000/listen/quzuo_fm/radio.mp3 404？

分层命名问题：Icecast 内部挂载名是 /radio.mp3，/listen/quzuo_fm/radio.mp3 是网关层别名（走 80/443 的 Web 地址）。直连串流端口用 http://<IP>:8000/radio.mp3；/listen/... 形态走 Web 端口访问。

Q5：settings:list 里很多键是空的，需要逐个设置吗？

不需要。空值表示「未设置、走内置默认」，这是 AzuraCast 的设计（settings 表只存显式覆盖项）。按第七章模板设置关键项（base_url、备份组）即可，其余保持空值。

Q6：备份自动化设置了但 backup_last_run 一直为空？

定时任务由系统同步调度器驱动，检查 sync_disabled 是否被置 1、系统时间与时区是否正确；也可手工验证备份流程本身可用：./azuracast-cli azuracast:backup /var/azuracast/backups/manual-test（注意 path 不能是挂载点本身，详见 《AzuraCast 常用 CLI 命令详解》4.1 节踩坑实录）。

九、参考链接

• 官方 Docker 安装文档（azuracast.env 生成与修改方式来源）：https://www.azuracast.com/docs/getting-started/installation/docker
• 官方站点管理文档（电台/挂载点参数）：https://www.azuracast.com/docs/user-guides/stations/
• 官方备份与恢复文档：https://www.azuracast.com/docs/administration/backup/
• 官方命令行接口文档：https://www.azuracast.com/docs/administration/cli/
• GitHub 仓库（sample.env 模板来源）：https://github.com/AzuraCast/AzuraCast
• 版本发布页（0.24.0，2026-10-25）：https://github.com/AzuraCast/AzuraCast/releases/tag/0.24.0