LibreTime 4.5.0 介绍与选型指南

目标：一文讲清开源电台自动化排播系统 LibreTime 的定位、架构、功能与选型方法，帮助需要在自托管环境搭一套「上传音频 → 排节目单 → 24/7 自动播出流」广播自动化平台的读者快速判断它是否合适。已基于 Ubuntu 22.04 x86_64 服务器与 LibreTime 4.5.0（官方 Docker 编排、10 组件全栈）部署实测，含 Web 登录、媒体上传、节目排期、Liquidsoap 自动播出与 Icecast 流输出的全链路验证。

一、环境信息

本文结论均在以下真实环境验证通过，读者按相同版本对照可复现：

• 操作系统：Ubuntu 22.04（x86_64，内核 5.15+，4C/8G 虚拟机）
• LibreTime 版本：4.5.0（官方 ghcr.io/libretime/libretime-*:4.5.0 镜像集，上游当前最新稳定版）
• 部署形态：Docker Compose 全栈（10 个组件：nginx / legacy / api / playout / liquidsoap / analyzer / worker / icecast / postgres 15 / rabbitmq 3.13）
• Web 界面端口：8142（HTTP），Icecast 流端口：8138，Liquidsoap 输入端口：8139（主）/ 8140（秀）
• API 版本：REST API v2（实测 /api/v2/version 返回 {"api_version":"2.0.0"}）
• 浏览器验收：Chromium 130（Web 界面与登录页抓取比对）
• 查询日期：2026-10-29（上游版本与社区数据均以此日实查为准）

二、软件概述

2.1 它是什么

LibreTime 是一套开源电台广播自动化平台（Radio Broadcast & Automation Platform，官方 OpenAPI 规范里的自我定位）。它解决的核心问题是：一个网络电台/校园电台/社区电台每天要播十几个小时甚至 24 小时的节目，不可能靠人在调音台前排每一首歌。LibreTime 把这件事变成三步：

1. 媒体库管理：把音频文件（mp3/ogg 等）上传进系统，自动分析时长、码率、声道等元数据；
2. 节目排期：在日历式 Web 界面上创建节目（Show）、排期次（Instance）、把曲目/播放列表/外部流拖进时间段（Schedule）；
3. 自动播出：排播引擎按时间线自动切换音源，把混合后的节目流推给流媒体服务器，听众从流地址收听。

它源自 Sourcefabric 的 Airtime 项目的社区延续，2017 年起由 LibreTime 社区独立维护，使用 Apache-2.0 许可证，全栈自托管、无 SaaS 依赖。

2.2 版本沿革（实查上游 Releases）

2026-10-29 查询 GitHub libretime/libretime Releases（https://api.github.com/repos/libretime/libretime/releases），近期版本节奏如下：

⚠️ 关键结论：截至 2026-10-29，上游最新稳定版就是 4.5.0——本文实测部署的版本即当前最新版，无「部署即落后」问题。版本节奏从 4.x 起大约每年 2~3 个 minor 版本，属于小步稳定迭代。

2.3 技术栈构成

LibreTime 4.x 不是单体程序，而是一组分工明确的组件。实测部署的 10 个组件与职责：

💡 技术拓展：「排播引擎」是电台自动化平台的心脏，业界常见实现对比——

引擎	原理/特点	适用场景
Liquidsoap	脚本化音频流语言，源（source）组合与定时切换，社区成熟	需要 24/7 自动播出 + 直播插入混音的场景，LibreTime/Airtime 系标配
自研队列播放器	程序内定时器 + 解码队列，简单直接	功能单一的低成本播放器
电视台级播出系统	主备切换器 + 帧精度控制	广电级播出，成本高

LibreTime 实际采用 Liquidsoap：它把「定时排期 → 音源切换 → 推流」都建模为脚本化的 source 图，排期变化时 LibreTime 通过 Liquidsoap 的 server 协议热切换音源，无需重启播放进程（实测日志可见 Switch to map_metadata:schedule with transition 的平滑切换）。

三、核心架构

3.1 数据流全景

实测部署后，一次「上传 → 排期 → 播出」的完整数据流如下（均为实测观察到的行为）：

DJ 上传音频（Web 界面 / REST API）
   │  POST /rest/media（Basic 认证，api_key）
   ▼
legacy 保存文件 → 写入 PostgreSQL cc_files → 发 RabbitMQ 分析任务
   │
   ▼
analyzer 消费任务 → 分析时长/码率 → 更新 cc_files（import_status 0=完成）
   │
   ▼
DJ 在 Web 日历建节目（Show）→ 排期次（Instance）→ 排曲目（Schedule）
   │
   ▼
playout 按 cache_ahead_hours 预拉排期 → 缓存音频 → 通过 Liquidsoap server 协议下发
   │
   ▼
liquidsoap 按时间线切换音源 → 编码 Ogg 256kbps → 推给 icecast
   │
   ▼
icecast 对外暴露挂载点（/main）→ 听众播放器拉流收听
   │
   ▼
播出记录写回 playout-history（实测 POST 播出后 schedule.played=true）

3.2 关键设计点（实测验证）

• 单一 PostgreSQL 权威数据源：媒体库（cc_files）、节目（cc_show/cc_show_instances）、排期（cc_schedule）、用户（cc_subjs）全在一张库中。实测迁移完成后共 41 张表。
• 消息解耦的媒体处理：上传接口只落盘入库，元数据分析经 RabbitMQ 异步完成，实测 4.3MB mp3 从上传到 import_status=0（时长 00:03:00.035918、码率 192000 解析完毕）约 15 秒。
• 排期与播出解耦：playout 只读排期表并预缓存，播出指令走 Liquidsoap server 协议（实测端口 1234，容器网络内）。排期在播出前修改不影响已缓存内容，播出后 schedule.played 置 true、playout-history 落一条记录，形成闭环审计。
• 统一入口：Web 界面、REST API、媒体文件下载全部经 nginx 8080（对外映射 8142），Web 会话与 API Basic 认证并存（详见 REST API 使用详解篇）。

3.3 部署形态

LibreTime 4.x 官方支持两种部署形态：

1. Docker Compose 全栈（本文实测）：官方 ghcr.io/libretime/libretime-* 镜像，一个 compose 文件拉起 10 组件，升级回滚只需换镜像 tag。生产推荐。
2. 裸机/发行版安装：官方提供 deb/rpm 包，各组件手工装配（Apache/Nginx + PHP + Python + Liquidsoap + Icecast + PostgreSQL + RabbitMQ），适合深度定制，但装配面广、升级繁琐。

四、功能特性（实测清单）

以下特性均在 4.5.0 实测环境验证过存在与可用：

• Web 管理界面：登录页 /login（实测 admin 账号登录返回 200 与工作台页面），日历式排期视图、媒体库列表、节目管理、偏好设置。
• 媒体库管理：REST 上传（实测 POST /rest/media 返回 201 并自动建 file 记录）、自动元数据分析（时长/码率/采样率）、文件下载（/api/v2/files/{id}/download）。
• 节目与排期：Show（节目模板）→ Instance（期次）→ Schedule（曲目级排期）三级模型，REST 全支持（实测创建 show=1 → instance=1 → schedule=1 全链路）。
• 自动播出：排期到点自动开播（实测 10:26:57Z liquidsoap 日志 Cueing in... + Switch to map_metadata:schedule with transition），播出记录回写（实测 schedule.played=true、playout-history 新增记录）。
• 直播输入：内置两个 Harbor 直播输入口（main/show，实测映射端口 8139/8140），DJ 用任意 Icecast 源客户端（如 butt、Mixxx）推流即可插播直播，直播结束自动回落排期。
• 多路流输出：Icecast 输出最多 3 路 + Shoutcast 1 路 + 系统声卡输出，各自独立编码参数（实测主输出 Ogg Vorbis 256kbps 44.1kHz 立体声，HTTP 200 拉流 4 秒 92686 字节）。
• 流状态统计：Icecast 管理端点实时统计挂载点码率/采样率/听众数（实测 admin 端点 stats.xml 正常返回）。
• 播客：Station Podcast（电台官方播客）与导入外部播客，集内集目可复用媒体库资产。
• Webstream 排期：把外部网络流（如远端电台流地址）作为排期项插入时间线。
• REST API v2：74 个路径、38 个资源域（files/shows/schedule/playlists/webstreams/users/preferences 等），OpenAPI 3.0 规范随项目发布，Basic/会话双认证。
• 多用户与角色：内置 admin/program manager/host/guest 角色，登录失败计数与锁定记录（login-attempts API 域）。

五、快速开始（最小可用示例）

本节给出「5 分钟跑起来」的最小路径（完整部署步骤、参数解释见《LibreTime 4.5.0 Docker Compose 部署指南》，此处只求最快见效）。

5.1 拉起全栈

在准备好的部署目录（含 docker-compose.yml、config.yml、.env）执行：

docker compose -p libretime-450-stack up -d   # 拉起 10 组件全栈

实测回显（节选）：

 Container libretime-450-stack-postgres-1 Healthy
 Container libretime-450-stack-api-1       Started
 Container libretime-450-stack-nginx-1     Started

核对 10 个组件全部运行：

docker ps --filter 'name=libretime-450-stack' --format '{{.Names}}\t{{.Status}}' | sort

实测回显：

libretime-450-stack-analyzer-1     Up 42 seconds
libretime-450-stack-api-1          Up 41 seconds (healthy)
libretime-450-stack-icecast-1      Up 42 seconds
libretime-450-stack-legacy-1       Up 41 seconds
libretime-450-stack-liquidsoap-1   Up 40 seconds
libretime-450-stack-nginx-1        Up 40 seconds
libretime-450-stack-playout-1      Up 41 seconds
libretime-450-stack-postgres-1     Up 42 seconds (healthy)
libretime-450-stack-rabbitmq-1     Up 41 seconds (healthy)
libretime-450-stack-worker-1       Up 41 seconds

5.2 初始化数据库（首次部署必做）

4.5.0 官方编排不会自动建库表，首次启动需手动执行一次迁移，否则 Web 界面报 500、数据库报 relation "cc_subjs" does not exist（实测踩坑，详见部署指南常见问题）：

docker exec libretime-450-stack-api-1 libretime-api migrate --noinput

实测回显（节选）：

  Applying legacy.0044_add_track_types_analyzer_options... OK
  Applying legacy.0045_add_sessions_table... OK
  Applying legacy.0046_add_override_intro_outro_playlists... OK
  Applying sessions.0001_initial... OK

5.3 登录与验证

默认管理员为 admin，初始密码 admin（生产必须立刻改掉）。浏览器打开 http://<服务器IP>:8142/login 登录；命令行验证 API：

curl -s -u 'admin:q1w2e3r4' 'http://127.0.0.1:8142/api/v2/info'

实测回显：

{"station_name":"LibreTime"}

5.4 上传一首歌并排出播出

curl -s -u '<API_KEY>:' -X POST 'http://127.0.0.1:8142/rest/media' -F 'file=@test-track.mp3;type=audio/mpeg'

实测回显（节选）：

POST /rest/media: 201
file id: 1 | import_status: 1 | md5: a30d22e4f630a36fc54d53f8963eabc1

等分析完成后建排期（show → instance → schedule 三连，实测回显）：

show id: 1
instance id: 1 | starts: 2026-10-29T10:26:00Z
schedule id: 1 | starts: 2026-10-29T10:26:00Z

到点后验证自动播出与流输出：

curl -s -o /tmp/s.bin --max-time 4 'http://127.0.0.1:8138/main' -w 'stream: HTTP %{http_code}, %{size_download}B\n'
file /tmp/s.bin

实测回显：

stream: HTTP 200, 92686B, application/ogg
/tmp/s.bin: Ogg data, Vorbis audio, stereo, 44100 Hz, ~256000 bps, created by: Xiph.Org libVorbis I

至此「上传 → 排期 → 自动播出 → 听众拉流」全链路跑通。Liquidsoap 侧同步日志（实测）：

2026/10/29 10:26:57 [s3:3] Prepared "/app/scheduler/1.mp3" (RID 0).
2026/10/29 10:26:57 [cue_cut_9616:3] Cueing in...
2026/10/29 10:26:57 [switch:blank+schedule:3] Switch to map_metadata:schedule with transition.

六、适用场景与限制

6.1 适合谁用

• 网络电台/校园电台/社区电台：需要定时自动播出 + DJ 直播插播的场景，是 LibreTime 的原生主场。
• 播客排播与节目自动化：把播客集目按时间线自动轮播，兼具流输出。
• 多频道小规模电台：最多 3 路 Icecast 输出 + 1 路 Shoutcast，单服务器即可支撑多码率分发。
• 需要完整 REST API 的集成方：74 路径的 v2 API 足以把排期、媒体库接入自有系统（工单系统自动排单、App 点播等）。

6.2 限制与注意

• 单站架构：一套 LibreTime 管一个电台站点，无内建多站点/多租户；多站点需多套部署。
• 无内建集群/高可用：官方架构为单实例全栈，播出节点故障需靠外部手段（备份恢复、DNS 切换）兜底。
• 听众规模取决于 Icecast：大并发听众要前置 CDN/边缘分发，LibreTime 本身不解决扇出。
• 音频格式：排期资产以 mp3/ogg 为主，输出编码支持 ogg/mp3/aac/opus 四类；不支持视频流。
• 认证遗留：legacy 密码以 MD5 形式存储（实测数据库 cc_subjs.pass 为 32 位 MD5 摘要），安全敏感部署应置于内网或前置 SSO/反向代理层，关注上游对认证层的现代化进展。
• 中文界面：Web 界面有多语言包但翻译覆盖不完整，排期术语以英文为主。

七、同类选型对比

网络电台自动化这个赛道，可选的自托管方案主要是 LibreTime、AzuraCast、RadioDJ、Airtime Pro（商业托管）四类。下表为选型主战场（数据来源为各项目官方文档与仓库，2026-10-29 查询）：

如何选：

• 需要规范化 API 深度集成（本文 D 篇场景）或采购合规要求 Apache-2.0：选 LibreTime，它的 OpenAPI 规范随项目发布、组件职责清晰，适合当「排播后端」被其他系统调用。
• 追求开箱即用的现代化界面与更大社区：选 AzuraCast，功能面更广（含请求系统、奖励站等），代价是组件栈更重。
• Windows 单机、桌面 GUI 操作：RadioDJ 顺手，但无 Web 界面与开放 API，集成能力弱。
• 完全不想运维：Airtime Pro 商业托管，但数据与自由度归零。

与自家生态的组合：LibreTime 负责排播与流输出，前端听众侧可配 Nginx/CDN 分发，数据面 PostgreSQL 与 RabbitMQ 均为业界标准件，监控可用 Prometheus + 常规 exporter 覆盖。

八、参考链接

• LibreTime 官网与文档：https://libretime.org
• 官方管理员手册（安装与配置）：https://libretime.org/docs/admin-manual/setup/
• GitHub 仓库与 Releases：https://github.com/libretime/libretime
• 官方 Docker 部署文档：https://libretime.org/docs/admin-manual/setup/docker/
• API 参考文档：https://libretime.org/docs/api/
• Liquidsoap 官方文档：https://www.liquidsoap.info/doc.html
• Icecast 官方文档：https://icecast.org/docs/
• 《LibreTime 4.5.0 Docker Compose 部署指南》 《LibreTime 4.5.0 配置参数详解》 《LibreTime 4.5.0 REST API 使用详解》