LibreTime 4.5.0 配置参数详解

目标：逐项讲清 LibreTime 4.5.0 全局配置文件 config.yml 的参数树、默认值、取值影响与生效方式，并给出经实测验证的参数修改闭环（改 Icecast 输出码率 256→128kbps 后流参数实时变化）与生产配置模板。已在 Ubuntu 22.04 服务器 4.5.0 官方 Docker 编排环境实测，全部回显为真实输出。

一、环境信息

操作系统：Ubuntu 22.04 x86_64（4C/8G）
LibreTime：4.5.0（官方 Docker 编排，10 组件全栈，部署过程见《LibreTime 4.5.0 Docker Compose 部署指南》）
配置文件：宿主侧 /opt/libretime/config.yml，以只读方式挂载到全部 7 个 LibreTime 组件的 /etc/libretime/config.yml
官方参数模板：镜像内自带完整注释模板 config.template.yml（4.5.0 版本约 10KB，覆盖全部参数与默认值）
时区：Asia/Shanghai（配置文件设置，实测生效）
实测时间：2026-10-29

二、前置条件

LibreTime 4.5.0 全栈已按部署指南拉起并可登录 Web 界面。
理解 config.yml 的共享机制：所有组件读同一份文件，改任何参数后需重启受影响组件。
部署目录里有官方模板可对照：

ls -la /opt/libretime/config.template.yml /opt/libretime/config.yml

实测回显：

-rw-r--r-- 1 root root 10043 Oct 29 01:09 /opt/libretime/config.template.yml
-rw-r--r-- 1 root root 10170 Oct 29 01:16 /opt/libretime/config.yml

说明：模板文件 10043 字节为 4.5.0 官方原样模板；本文实测 config.yml 在其基础上精简为实际启用的参数集（10170 字节包含部署时的注释差异）。

三、参数查看与修改方式

3.1 查看当前生效配置

配置文件是唯一权威来源，直接查看（宿主侧与容器内内容一致）：

docker exec libretime-450-stack-api-1 cat /etc/libretime/config.yml | head -15

实测回显（节选）：

general:
  # The public url.
  # > this field is REQUIRED
  public_url: http://127.0.0.1:8142
  # The internal API authentication key.
  # > this field is REQUIRED
  api_key: 867b550987df8c6ff65140584d9cd6e93a18e386e8ed69b5e4c00dc858e01b73
  # The Django API secret key.
  # > this field is REQUIRED
  secret_key: 94c3f2ca50b0465155b0c689ce24a0b4e4ec16cffbe0f2bc87e06842a3059a80

部分运行时参数也可经 REST API 读取（preferences 域，21 项）：

curl -s -u 'admin:q1w2e3r4' 'http://127.0.0.1:8142/api/v2/preferences' \
  | python3 -c "import sys,json; d=json.load(sys.stdin); [print(k,'=',v) for k,v in list(d.items())[:5]]"

实测回显（节选）：

allow_2way_sync = 1
bonus_cue_points = 0
can_advertise = 0
cell_msg_data_rate = 0
default_crossfade_duration = 0

3.2 修改参数的标准闭环

修改 → 重启受影响组件 → 实测验证，三步缺一不可。以把主输出码率从 256 改为 128 kbps为例，完整实测：

第一步：编辑宿主侧 /opt/libretime/config.yml，把主输出的 audio.bitrate 由 256 改为 128：

    icecast:
      - <<: *default_icecast_output
        enabled: true
        mount: main
        audio:
          format: ogg
          bitrate: 128

第二步：重启受影响组件（liquidsoap 负责编码、playout 负责调度，两个都重启）：

docker compose -p libretime-450-stack restart liquidsoap playout

实测回显：

 Container libretime-450-stack-playout-1  Started
 Container libretime-450-stack-liquidsoap-1  Started

第三步：排一条到点即播的曲目（排期接口实测，10:40:00Z 开播）：

instance id: 2
schedule id: 2 2026-10-29T10:40:00Z

第四步：到点后核对 Icecast 挂载点参数与流采样，验证 128kbps 已生效：

curl -s -u 'admin:q1w2e3r4' 'http://127.0.0.1:8138/admin/stats.xml' \
  | python3 -c "
import sys, xml.etree.ElementTree as ET
t = ET.fromstring(sys.stdin.read())
s = t.find('.//source')
print('ice-bitrate:', s.findtext('ice-bitrate'), '| audio_bitrate:', s.findtext('audio_bitrate'), '| samplerate:', s.findtext('audio_samplerate'))
"
curl -s -o /tmp/s128.bin --max-time 4 'http://127.0.0.1:8138/main' -w 'stream: HTTP %{http_code}, %{size_download}B\n'
file /tmp/s128.bin

实测回显：

ice-bitrate: 128 | audio_bitrate: 128000 | samplerate: 44100
stream: HTTP 200, 105324B
/tmp/s128.bin: Ogg data, Vorbis audio, stereo, 44100 Hz, ~128000 bps, created by: Xiph.Org libVorbis I

修改前同一挂载点为 ice-bitrate: 256 | audio_bitrate: 256000、流采样 ~256000 bps——参数改动即时反映到流输出，闭环验证完成。

⚠️ 注意：改码率不影响 icecast 端口上的老听众连接的兼容性（挂载点会短暂消失后以新参数重现），播放器需重连。生产改参数应选低峰时段。

四、参数总览

config.yml 的参数树共 9 个顶层段（4.5.0 模板全量）：

段	参数数量级	核心职责
general	8 项	站点地址、密钥、时区、认证适配器、预取窗口
storage	1 项	媒体库根路径
database	5 项	PostgreSQL 连接
rabbitmq	5 项	消息队列连接
email	10 项	SMTP 发信（找回密码/通知）
playout	9 项	播出引擎连接与录制参数
liquidsoap	6 项	液态广播引擎监听与 TLS
stream.inputs	2 组 8 项	main/show 两个直播输入口
stream.outputs	3 组	icecast（≤3 路）/ shoutcast（1 路）/ system（1 路）

必填参数仅 3 个：general.public_url、general.api_key、general.secret_key；其余全部有默认值。参数间有联动关系的三组：database/rabbitmq 连接参数 ↔ compose 的 .env；stream.outputs.*.source_password ↔ .env 的 ICECAST_SOURCE_PASSWORD；storage.path ↔ nginx 对媒体文件的代理路径。

五、核心参数分类详解

5.1 general：站点与密钥

general:
  public_url: http://127.0.0.1:8142
  api_key: 867b550987df8c6ff65140584d9cd6e93a18e386e8ed69b5e4c00dc858e01b73
  secret_key: 94c3f2ca50b0465155b0c689ce24a0b4e4ec16cffbe0f2bc87e06842a3059a80
  allowed_cors_origins: []
  timezone: Asia/Shanghai
  cache_ahead_hours: 1
  auth: local

逐项说明：

public_url（必填）：听众/DJ 访问的对外地址。影响：Web 界面展示的直播输入 URL、生成的对外链接。本文实测值 http://127.0.0.1:8142 为单机演示；生产写 http://<域名或IP>:8142 或反代后的 HTTPS 地址。
api_key（必填）：内部 API 认证密钥，用 openssl rand -hex 32 生成。同时是 legacy 上传接口 /rest/media 的 Basic 认证用户名（密码留空），泄露等于开放了上传面。
secret_key（必填）：Django 会话签名密钥，同样 openssl rand -hex 32 生成；更换后所有已登录会话失效。
allowed_cors_origins（默认 []）：允许跨域访问 API 的来源列表；public_url 的 origin 自动包含。前端独立部署时才需要加。
timezone（默认 UTC）：排期显示与调度时区，IANA 名。实测设 Asia/Shanghai 后 Web 日历按北京时间展示；底层排期仍以 UTC 存储（实测 schedule 接口返回 2026-10-29T10:26:00Z 形态）。
cache_ahead_hours（默认 1）：playout 提前预取多少小时的排期音频到缓存卷。越大越抗 API 短暂故障，代价是磁盘占用与排期变更延迟生效窗口。
auth（默认 local）：legacy 界面的认证适配器，可换成 LibreTime_Auth_Adaptor_FreeIpa 类对接企业目录。

5.2 storage：媒体库路径

storage:
  path: /srv/libretime

媒体库根路径（容器内）。上传的文件按 imported/<file_id>/<原文件名> 落在 path 下（实测 file id=1 的 filepath 为 imported/1/test-track.mp3）。改路径需同步改 nginx 对媒体文件的代理配置（官方注释明确提示），无特殊必要不动它。

5.3 database：PostgreSQL 连接

database:
  host: postgres
  port: 5432
  name: libretime
  user: libretime
  password: q1w2e3r4

逐项说明：host 在 Docker 部署写服务名 postgres（专用网络 DNS 解析）；裸机部署写 localhost 或 DB 服务器地址。password 必须与 compose .env 的 POSTGRES_PASSWORD 一致——后者只在数据卷首次初始化时建库用，此处的值是组件连接用的，两边不一致会出现迁移成功但组件连库失败的怪象。改库口令的正确顺序：先 ALTER USER 改库内口令，再同步改 .env 与 config.yml，最后重启 api/legacy/analyzer。

5.4 rabbitmq：消息队列连接

rabbitmq:
  host: rabbitmq
  port: 5672
  vhost: /libretime
  user: libretime
  password: q1w2e3r4

五项与 database 同构：host 写服务名、口令与 .env 的 RABBITMQ_DEFAULT_PASS 一致。analyzer/worker/playout 与 legacy 之间的媒体分析任务、播报通知都走这条总线。实测 analyzer 启动日志可见连接建立：

2026-10-29 10:08:27,888 | INFO | pika.adapters.blocking_connection:_create_connection:1264 - Created channel=1
2026-10-29 10:08:27,889 | INFO | libretime_analyzer.message_listener:connect_to_messaging_server:78 -  Listening for messages...

5.5 email：SMTP 发信

email:
  from_address: no-reply@libretime.org
  host: localhost
  port: 25
  encryption:        # ssl/tls、starttls 或留空
  user: ""
  password: ""
  timeout:           # 秒
  cert_file:
  key_file:

用于找回密码等系统邮件。默认连 localhost:25 明文 SMTP，无独立邮件服务时功能不可用但不影响主流程。接企业邮箱时设 encryption: starttls + 端口 587，或 ssl/tls + 465，user/password 填发信账号（口令建议经环境变量注入而非明文写入）。

5.6 playout：播出引擎连接与录制

playout:
  liquidsoap_host: liquidsoap
  liquidsoap_port: 1234
  record_file_format: ogg
  record_bitrate: 256
  record_samplerate: 44100
  record_channels: 2
  record_sample_size: 16

逐项说明：liquidsoap_host/port 是 playout 连 Liquidsoap server 协议的地址，Docker 部署写服务名 liquidsoap。record_* 五项控制节目录制（Show 勾选录制后自动录音）的产出规格：格式 ogg/mp2 之一、码率 256、44.1kHz、双声道、16bit。录制文件同样落在 storage 卷。

5.7 liquidsoap：引擎监听

liquidsoap:
  server_listen_address: 0.0.0.0
  server_listen_port: 1234
  harbor_listen_address: ["0.0.0.0"]
  harbor_ssl_certificate:
  harbor_ssl_private_key:
  harbor_ssl_password:

server_listen_address 默认 127.0.0.1——Docker 部署必须改 0.0.0.0，否则跨组件连不上 server 协议（本文实测配置已改）。harbor_* 四项控制直播输入口的 TLS：给 main/show 挂证书后 DJ 可用 HTTPS 推流；证书路径为容器内路径，需另行挂载证书文件。

5.8 stream.inputs：直播输入口

stream:
  inputs:
    main:
      public_url:
      mount: main
      port: 8001
      secure: false
    show:
      public_url:
      mount: show
      port: 8002
      secure: false

两个直播输入口：main 为主直播（ anyone with 源口令可推流接管主频道），show 为节目级直播（仅指定节目时段生效）。port 是容器内监听端口（compose 映射 8139→8001、8140→8002）；mount 是源客户端连接时用的挂载名；public_url 留空时由 general.public_url 的主机名 + 端口自动生成；secure: true 启用 harbor TLS。实测 DJ 推流口令即 icecast source_password（同一套 harbor 认证）。

5.9 stream.outputs：流输出（icecast/shoutcast/system）

  outputs:
    .default_icecast_output: &default_icecast_output
      host: icecast
      port: 8000
      source_password: q1w2e3r4
      admin_password: q1w2e3r4
      name: LibreTime!
      description: LibreTime Radio!
      website: https://libretime.org
      genre: various
    icecast:
      - <<: *default_icecast_output
        enabled: true
        mount: main
        audio:
          format: ogg
          bitrate: 128

逐项说明：

.default_icecast_output 是 YAML 锚点（以 . 开头不会被当作输出解析），公共参数一处定义多处复用；最多 3 路 icecast 输出，第二路实测模板里挂 main-low 128kbps（enabled: false）。
每路输出必填 mount（挂载点名）与 audio.format/audio.bitrate；格式支持 aac/mp3/ogg/opus，码率限 32/48/64/96/128/160/192/224/256/320 十档（实测模板注释明示）。
enable_metadata（ogg 专用，默认 false）：往流里嵌歌名/艺人元数据；模板注释警告个别播放器对带元数据的 ogg 流每首歌后断连，开启前先测客户端兼容性。
mobile: false：标记该路是否面向移动端（界面展示用）。
admin_password 不填则该路的听众统计（listener-counts 域）不采集。
shoutcast 组（≤1 路）：结构与 icecast 类似，格式限 aac/mp3。
system 组（≤1 路）：把输出直写本机声卡（kind: alsa/ao/oss/portaudio/pulseaudio），容器内无声卡设备，仅裸机部署可用。

💡 技术拓展：流媒体分发协议不止 Icecast 一家——

协议/软件特点适用场景
Icecast 开源流服务器事实标准，ogg/mp3/aac/opus，web 状态页网络电台主输出，LibreTime 默认搭配
Shoutcast Icecast 的商业化前身，mp3/aac 兼容老播放器/老平台
HLS 苹果系切片协议，延迟秒级但穿透性强移动端/网页大规模分发（需另配切片网关）
RTMP 直播推流常用面向直播平台转发场景

LibreTime 4.5.0 内建输出为 Icecast（3 路）+ Shoutcast（1 路）+ 系统声卡；HLS/RTMP 需要在 LibreTime 之外另架网关拉取 Icecast 流转封装。本文采用默认 Icecast 主输出。

协议/软件	特点	适用场景
Icecast	开源流服务器事实标准，ogg/mp3/aac/opus，web 状态页	网络电台主输出，LibreTime 默认搭配
Shoutcast	Icecast 的商业化前身，mp3/aac	兼容老播放器/老平台
HLS	苹果系切片协议，延迟秒级但穿透性强	移动端/网页大规模分发（需另配切片网关）
RTMP	直播推流常用	面向直播平台转发场景

六、生产配置模板

适用场景：8GB 内存 / 100GB SSD / 日播 12-18 小时的中小网络电台，单机全栈，听众分发前置 CDN 或 Nginx 缓存。在最小必配基础上补齐生产项：

general:
  public_url: https://radio.example.com     # 对外 HTTPS 域名（反代终结 TLS 后回源 8142）
  api_key: <openssl rand -hex 32 生成>       # 部署时生成，勿用示例值
  secret_key: <openssl rand -hex 32 生成>   # 部署时生成，勿用示例值
  timezone: Asia/Shanghai
  cache_ahead_hours: 3                       # 抗 API 抖动，播前 3 小时预取
  allowed_cors_origins: []                   # 有独立前端再按需加

storage:
  path: /srv/libretime

database:
  host: postgres
  port: 5432
  name: libretime
  user: libretime
  password: <与 .env 的 POSTGRES_PASSWORD 一致>

rabbitmq:
  host: rabbitmq
  port: 5672
  vhost: /libretime
  user: libretime
  password: <与 .env 的 RABBITMQ_DEFAULT_PASS 一致>

playout:
  liquidsoap_host: liquidsoap
  liquidsoap_port: 1234
  record_file_format: ogg
  record_bitrate: 256
  record_samplerate: 44100
  record_channels: 2
  record_sample_size: 16

liquidsoap:
  server_listen_address: 0.0.0.0            # 容器部署必改
  server_listen_port: 1234

stream:
  inputs:
    main:
      mount: main
      port: 8001
      secure: false
    show:
      mount: show
      port: 8002
      secure: false
  outputs:
    .default_icecast_output: &default_icecast_output
      host: icecast
      port: 8000
      source_password: <与 .env 的 ICECAST_SOURCE_PASSWORD 一致>
      admin_password: <与 .env 的 ICECAST_ADMIN_PASSWORD 一致>
      name: My Radio
      description: My Radio live stream
      website: https://radio.example.com
      genre: various
    icecast:
      - <<: *default_icecast_output
        enabled: true
        mount: main
        audio:
          format: ogg
          bitrate: 256
      - <<: *default_icecast_output
        enabled: true
        mount: main-low
        audio:
          format: aac
          bitrate: 64

模板要点：双路输出（主频道 Ogg 256k 高音质 + main-low AAC 64k 低码率供移动网络）；cache_ahead_hours 提到 3；口令三处与 .env 严格一致。资源参考：该规模下全栈稳态内存占用约 1.5-2GB（postgres/rabbitmq/liquidsoap 为大头），8GB 内存有充足余量；媒体库按 3 分钟 128kbps 曲目约 2.8MB 估算，1 万首约 28GB，100GB SSD 足够。

七、常见问题

Q1：改了 config.yml 不生效？ 配置以只读方式挂载，组件在启动时读取——必须重启受影响组件（本文 3.2 节实测：改码率后重启 liquidsoap 与 playout，新流参数才出现）。全栈重启用 docker compose -p libretime-450-stack restart。

Q2：组件连不上数据库/消息队列？ 三处口令一致性排查：.env（首次初始化生效）、config.yml（组件连接用）、数据库/队列内部实际值。命名卷已初始化后再改 .env 不会改库内口令，需 ALTER USER 同步。

Q3：直播输入口推流被拒？ 按顺序核对：推流地址端口（宿主 8139/8140 对应容器 8001/8002）、挂载名（main/show）、源口令（= icecast source_password，与推流客户端密码一致）、liquidsoap.server_listen_address 是否为 0.0.0.0（默认 127.0.0.1 会导致跨组件不可达）。

Q4：时区设了但排期时间还是 UTC？ general.timezone 影响界面显示与调度换算；REST API 返回的排期时间恒为 UTC ISO8601（实测 2026-10-29T10:26:00Z），对接 API 时自行换算（北京时间 +8）。

Q5：输出码率改成 256 以外的值报错？ audio.bitrate 只接受 32/48/64/96/128/160/192/224/256/320 十档（模板注释明示），format 只接受 aac/mp3/ogg/opus；越界值会导致 liquidsoap 配置生成失败而退出，改回合法档位再重启。

八、参考链接

官方配置参考：https://libretime.org/docs/admin-manual/setup/configuration/
4.5.0 参数模板（仓库内）：https://github.com/libretime/libretime/blob/main/packages/config/config.template.yml
Liquidsoap 文档（引擎行为）：https://www.liquidsoap.info/doc.html
Icecast 文档（挂载点与统计）：https://icecast.org/docs/
《LibreTime 4.5.0 介绍与选型指南》《LibreTime 4.5.0 Docker Compose 部署指南》《LibreTime 4.5.0 REST API 使用详解》