MiguDelay 架构 00：项目架构总览

MiguDelay（DDLive）项目架构系列文档：项目架构总览。内容基于 2026-08-04 对指定重构分支的源码扫描结果整理。

发表于 2026/08/05

作者 李正博

6 分钟阅读

系列导航：系列总览 · 下一篇：MiguDelay 架构 01：应用启动与关闭

本文是 MiguDelay（DDLive）架构系列的总入口。系列共 28 篇：本页提供全局对象图、任务主链与阅读索引，其余页面按运行时、任务生命周期、媒体执行链、播放功能域、协同外围和工程质量拆分。

扫描基线

项目：MiguDelay（DDLive）

分支：refactor/video-frame-provider

HEAD：d28ec061406e4e3df93e3d1a92478d71a9ad4908

工作树：clean

扫描日期：2026-08-04

说明：内容以当前 HEAD 源码为准；仓库旧架构文档只作为检索线索。

1. 系统定位

MiguDelay（产品名 DDLive）是基于 Qt/QML 与 FFmpeg 的直播延时、垫片切换、收录、推流和多路监看应用。当前分支采用渐进式迁移架构：

应用与协议入口层：App.cpp、QML、ViewModel、MQTT Handler、ApplicationIngress。
播放应用服务层：PlaybackRuntime 组装的 Admission、Session、Orchestrator、OutputMode、Aux、Preview、主备、监看音频、机审、截图、流重配置。
兼容边界层：Gateway、Adapter、Binding，把 typed command/event/value 接回旧 TaskHandle、AppConfig、MQTT、QML Item 和媒体回调。
媒体执行层：RecvNetworkFlowFFmpeg、Output、OutputWithLocalFileReader、编码器、复用器、文件 Reader、YUV 转换和音频设备线程。

理解系统时必须区分：新层决定业务规则和权威状态，旧层继续执行真实媒体 I/O。

2. 页面树

01 运行时与基础

02 任务生命周期

03 媒体执行链

04 播放功能域

05 协同与外围

06 工程质量

3. 总体对象图

flowchart TD
    UI["QML and ViewModels"] --> RT["PlaybackRuntime"]
    MQTT["MQTT and MessageHandle"] --> ING["ApplicationIngress"]
    ING --> RT
    RT --> DOM["Domain Services"]
    DOM --> BIND["Bindings and Adapters"]
    BIND --> GW["TaskHandleGateway"]
    GW --> TH["Legacy TaskHandle"]
    TH --> RECV["RecvNetworkFlowFFmpeg"]
    TH --> OUT["Output and File Output"]
    OUT --> ENC["Encoders"]
    ENC --> MUX["Muxers"]
    OUT --> PRE["Preview Router and Surfaces"]
    MUX --> FILE["Record Files"]
    MUX --> NET["RTMP or SRT Output"]

4. 任务主链

sequenceDiagram
    participant U as QML or MQTT
    participant A as TaskAdmissionService
    participant O as TaskOrchestrator
    participant G as TaskHandleGateway
    participant T as TaskHandle
    participant M as Media Pipeline
    participant P as PreviewFrameRouter

    U->>A: request start
    A->>O: StartTaskCommand
    O->>G: startReceive
    G->>T: StartRecvInfo
    T->>M: detect and start stream
    M-->>T: receive ready
    T-->>G: task result
    G-->>O: TaskGatewayResult
    O->>G: startRecord
    O->>O: mark Running
    M-->>P: first delayed video
    P-->>O: firstOutputFrame
    O->>G: startPush

5. 权威状态归属

真值	唯一写入者	主要读者
任务 phase、identity、generation、stop barrier	`TaskSession`	`TaskOrchestrator`、Task ViewModel
pending start、公开垫片等待	`TaskAdmissionService`	Task ViewModel、MQTT reply
当前输出模式	`OutputModeService` 写 `OutputModeStateView`	Output、Aux、Preview、ViewModel
Aux 播单	`AuxPlaylistStore`	`AuxPlaybackService`、PresentationSource
Aux Reader、节目、进度	`AuxPlaybackService`	ViewModel、Output frame source
Preview Surface 注册	`PreviewSurfaceRegistry`	Router、Monitor、Snapshot
输入/延时 readiness	`FrameAvailabilityTracker`	OutputMode Binding/ViewModel
主备 phase、peer、heartbeat	`MasterBackupService`	ViewModel、Replication Binding
监看音频控制/readiness	`MonitorAudioService`	ViewModel、Player Adapter
机审会话	`MachineAuditService`	Binding、ErrorModel
截图批次	`ShieldSnapshotService`	Source、Publisher

6. 线程模型

应用控制线程：修改所有领域真值，创建和关闭 QObject。
MQTT/协议线程：解析并复制 payload，经 ApplicationIngress queued 回控制线程。
TaskHandle 工作线程：执行收流、录制、推流和停止任务。
媒体线程：网络解码、Output tick、编码、复用、Reader、YUV、音频设备。
QtConcurrent 工作线程：流探测、流重配置、Aux 预热、Player 初始化等阻塞操作。
QML/渲染线程：创建和销毁 YuvVideoItem，渲染及 grabToImage。

异步结果写状态前必须校验 generation、ticket、requestId、phase 或 immutable context。

7. 当前分支结论

当前架构已从“大 Provider 直接持有状态”迁移为“组合根 + 领域服务 + typed Port + legacy Binding”。
底层媒体链仍集中在 TaskHandle、Output 和 callback 类型系统。
当前 StreamReconfigurationService 没有 cancelAndDrain Port；真实合同是 cancellation token、同目标 mutex 串行和 shutdown() 全量等待。
最新提交 d28ec061 修复 Aux 页面磁盘饼图高频刷新导致的动画重置，并增加校验测试，不改变任务状态机。