更新日志

v0.2.1

这个版本的重点不在单一大功能，而在于整体录制链路的正确性、会话生命周期一致性、可观测性增强、平台兼容性修复（Douyu / Huya）、Docker GPU 支持，以及前端稳定性与体验打磨。同时也包含了一轮较大规模的依赖与 CI 维护更新。

重点更新

1. 分段原因（Split Reason）正式打通到全链路

本次更新把录制分段原因从底层处理逻辑一直贯穿到了上层展示。

现在，分段原因会在以下层级中保持一致：

• FLV pipeline
• HLS pipeline
• pipeline-common 公共层
• 后端事件与下载管理器事件
• API 返回结构
• 数据库存储
• WebSocket / protobuf 消息
• 前端会话详情页与录制片段展示

这意味着你现在可以更明确地知道一段视频为什么会在某个时间点被切开，例如：

• 视频编码变化
• 音频编码变化
• 分辨率变化
• 时长限制触发
• 文件大小限制触发
• HLS discontinuity
• 流结构变化
• 上游 header 重置或流重启

这一改动不是单纯增加一个展示字段，而是一次跨后端、数据库、协议层与前端展示层的语义升级。

2. 会话生命周期与禁用/退避逻辑更严格、更一致

本次更新修复了 disabled streamer、临时禁用、错误退避、session 关闭之间的一些边界行为。

主要变化包括：

• 临时禁用状态下，disabled_until 现在会成为真正的权威约束
• 新的 live 事件不会再错误绕过临时禁用窗口
• set_live 不会错误重置 backoff / error 状态
• 在 SegmentStarted 时，仅清理 last_error，不再顺带清空 backoff 相关状态
• 当 disabled 的 streamer 被确认已经离线时，会主动关闭其活跃 session
• cancellation 现在被视为一次成功完成路径，而不是失败状态

这些更新会让监控与录制状态更稳定，减少状态抖动、误恢复、session 长时间悬挂等问题。

3. Docker 支持 NVIDIA GPU 硬件加速转码

新增了通过 compose override 文件为 Docker 环境配置 NVIDIA GPU 硬件加速转码的支持。

4. 新增 NVIDIA NVENC 编码器支持

转封装管道现在支持 H.264、HEVC 和 AV1 NVENC 硬件编码。当选择 CUDA 硬件加速时，前端会自动展示 NVENC 编解码器选项，并正确切换质量控制参数（CQ 代替 CRF）、缩放滤镜（scale_cuda 代替 scale）和兼容的预设列表。同时通过数据库迁移内置了 7 个 NVENC 任务预设和 2 个 GPU 管线预设。

5. HLS 流韧性与熔断器隔离增强

HLS 流在遇到临时性分片错误（网络超时、CDN body 解码失败等）时不再终止整个流。熔断器现在按 streamer 粒度隔离，一个主播的 CDN 问题不会影响同引擎下其他主播的下载。半开状态的成功/失败阈值现在也可以配置。

6. 下载器可配置优雅停止超时

下载器的 graceful stop 超时时间现在可以通过配置自定义。

7. 下载中断恢复能力增强

当下载过程中已经有较大进度时，遇到暂时性错误会自动恢复，而不是直接放弃整个 session。

8. Douyu 兼容性更新

Douyu 相关改动是这段时间内最需要关注的兼容性变化之一。

本次更新：

• 适配了新的 Douyu API 请求要求
• 更新了 ver 参数处理
• 修正了请求编码行为
• 对新的错误码做了处理，包括重试与区域限制相关逻辑
• 移除了旧的 Douyu HS CDN support

如果你依赖旧的 Douyu HS CDN 配置路径，升级后建议重点检查相关录制流程。

9. Huya 平台适配更新

更新了 Huya 平台提取器以适配最新的 API 变化。

10. 弹幕统计能力增强并接入界面

本次更新补齐了弹幕统计的采集、暴露与展示：

• 后端开始采集 danmu statistics
• API 层对相关数据进行了暴露
• 前端会话页面新增了统计展示与图表能力

对于需要分析直播活跃度、弹幕节奏或回看质量的用户，这会是一个很实用的增强。

11. 前端稳定性与体验提升

前端这轮更新主要聚焦于“更稳”和“更统一”：

• 修复 FOUC（页面初始闪烁 / 未样式化内容）问题
• 回退并修正 theme provider 相关问题
• 统一 dashboard 各页面的 skeleton loading 与动画切换体验
• 抽离并统一动画定义
• 改进 session 页面播放体验
• 改进 SSR / Tauri 环境下的媒体 URL 行为
• 修复订阅对话框在缩放显示时的溢出问题
• 修复录制时间线分段起始时间和误判中断的问题
• 修复日志 URL 构建错误

这些改动虽然不一定体现为新的功能入口，但会直接提升实际使用时的流畅度和可靠性。

12. 通知质量提升

通知相关更新主要集中在易读性与兼容性：

• 下载通知现在会优先展示 streamer display name，而不是 UUID
• 修复 Telegram HTML payload 转义问题
• 清理 Web Push 中与 AES128GCM 相关的旧头部处理逻辑

对于依赖通知来追踪下载状态、录制状态的用户，这些修复会让通知内容更直观，也更不容易出错。

升级前建议重点关注

以下几项属于建议在升级时明确检查的内容：

Douyu HS CDN 已移除

如果你之前使用了 Douyu HS CDN 相关配置，需要在升级后重新确认配置和录制流程是否符合预期。

Split reason 数据模型发生变化

分段原因现已成为后端、数据库、API 和前端都会消费的一部分。如果你有外部脚本、二次开发、数据分析逻辑依赖旧的 session/segment 语义，建议一并检查。

包含数据库迁移

本次 split reason 相关改动附带新的数据库 migration。部署升级时应确保迁移正常执行。

Session 分段时间戳语义发生变化

Session 分段现在会明确区分三种时间：created_at 表示分段开始录制时间， completed_at 表示分段结束录制时间，persisted_at 表示该记录写入 SQLite 的时间。 对于生命周期时间戳引入之前的历史数据，created_at / completed_at 可能为 null， 此时应使用 persisted_at 表示写入时间语义。

HLS 配置被清理和重组

Mesio HLS 配置在后端模型与前端表单/schema 两侧都做了整理。若你高度依赖 HLS 细节配置，升级后建议逐项复查。

Cancellation 语义改变

如果你有脚本、告警或外部系统依赖“取消 = 失败”的旧逻辑，需要按新的完成语义重新确认行为。

Disabled streamer 的 session 收尾行为变化

现在当 disabled streamer 被确认离线时，活跃 session 会被关闭。如果你之前依赖旧行为进行人工判断或外部调度，也建议一并确认。

其他改进

录制、处理链与性能

• 压缩处理器改进了进度反馈、取消能力和 buffered I/O
• writer callback 路径减少了不必要的 canonicalization 开销
• pipeline 与 worker pool 的日志输出做了批处理
• mesio FLV downloader 的 cancellation token 传播更合理
• AMF0 解码新增更宽容的 lossy decoding 支持
• 优雅停止超时时间可配置化
• 下载过程中遇到暂时性错误时可基于已有进度自动恢复
• HLS 流韧性增强：临时性分片错误（网络/超时）不再终止整个流
• 熔断器改为按 streamer 粒度隔离，半开状态阈值可配置
• pipeline 的取消与删除语义分离
• 十六进制编码优化为单次预分配 String

转码

• 新增 NVIDIA NVENC 编码器支持（H.264、HEVC、AV1），包含 CUDA 缩放滤镜、CQ 质量控制和内置预设

工程与维护

• 前端工具链迁移到 Vite 8 和 SWC
• Node.js 从 22 升级到 24 LTS
• 前端依赖、Rust 依赖、文档依赖进行了一轮集中更新
• GitHub Actions 中与 artifact 相关的 action 版本已更新
• 对 frontend-only PR 跳过 Rust CI，减少不必要的 CI 开销
• 仓库通过 .gitattributes 统一了文本文件 LF 行尾策略

总结

如果把这次更新概括成一句话，那就是：

这是一次围绕“录制行为更正确、状态更一致、信息更可见、平台兼容更稳、前端体验更顺”的综合更新。

对于普通用户来说，最直观的变化会体现在：

• 前端加载与主题体验更稳定
• 会话状态与收尾行为更符合预期
• 通知内容更清晰
• session 详情页能看到更完整的分段原因与弹幕统计

对于自托管用户或做集成的用户来说，最值得重点检查的是：

• Douyu 相关配置与录制行为
• split reason 与 migration 带来的数据模型变化
• HLS 配置整理后的兼容性
• cancellation / disabled / session 生命周期语义变化