MiguDelay 架构 21：主备绑定、心跳与业务复制

系列导航：系列总览 · 上一篇：MiguDelay 架构 20：运行中流重配置 · 下一篇：MiguDelay 架构 22：机审会话

扫描基线

• 项目：MiguDelay（DDLive）
• 分支：refactor/video-frame-provider
• HEAD：d28ec061406e4e3df93e3d1a92478d71a9ad4908
• 工作树：clean
• 扫描日期：2026-08-04
• 说明：内容以当前 HEAD 源码为准；仓库旧架构文档仅作为线索，不作为最终事实来源。

1. 两个子域

1. MasterBackupService：角色、peer、phase、heartbeat、binding generation。
2. ReplicationCommandApplier：主机 authoritative 业务变化如何在备机幂等应用。

协议 JSON 和 MQTT topic 留在 Handle、Transport、Binding 边界。

2. 核心类

类	职责
MasterBackupHandle	JSON 转 typed request/event
ApplicationIngress	queued 到控制线程
MasterBackupService	connection state owner
LegacyMasterBackupTransport	typed outbound 转 MQTT
LegacyMasterBackupBinding	AppConfig、临时垫片、接管、warning
MasterBackupViewModel	QML projection/commands
ReplicationPublisher	主机 event 转 sync JSON
ReplicationCommandApplier	备机 validation/idempotency
LegacyReplicationBinding	observed binding generation 和线程切换

3. 状态机

stateDiagram-v2
    [*] --> Idle
    Idle --> Binding: requestBind
    Binding --> Bound: bindSuccess
    Binding --> Idle: bindFailure
    Bound --> Unbinding: requestUnbind
    Unbinding --> Idle: unbindComplete
    Bound --> TimedOut: heartbeatDeadline
    Bound --> Disconnected: clientDetach
    TimedOut --> Binding: reconnect
    Disconnected --> Binding: reconnect
    Idle --> Bound: masterAcceptsPeer
    Bound --> Bound: replacePeer
    Idle --> Shutdown: shutdown
    Bound --> Shutdown: shutdown

4. 备机 bind

sequenceDiagram
    participant Q as QML
    participant V as MasterBackupViewModel
    participant F as BindContextFactory
    participant S as MasterBackupService
    participant T as LegacyTransport
    participant M as MQTT

    Q->>V: requestBind
    V->>F: capture current mode delay and gasket
    F-->>V: BindContext
    V->>S: requestBind
    S->>S: validate and increment generation
    S->>T: publish bind request
    T->>M: legacy topic and payload

5. 主机接收

MasterBackupHandle 校验 backup/source IDs、mode、delay、temporary gasket，转成 typed request，经 ApplicationIngress 到 Service。Service 比较本机 context，接受时原子替换 peer 并使 generation 递增。

6. 心跳

有效 heartbeat 必须满足 source=current peer、target=local：

• 更新 lastHeartbeat/deadline。
• 重启 Service timer。
• 发布 state snapshot。

超时进入 TimedOut，备机只发一次 MasterLost effect。显式 unbind 不发 MasterLost。

7. 临时垫片

独立 master_backup_temporary_gasket_sync 消息。只接受 current peer + local target。peer 替换会去重旧/新 path；超时或断连保留素材供接管。

8. 业务复制

sequenceDiagram
    participant D as DomainService
    participant P as ReplicationPublisher
    participant M as MQTT
    participant H as MasterBackupHandle
    participant I as ApplicationIngress
    participant A as ReplicationCommandApplier
    participant PORT as TypedDomainPorts

    D-->>P: committed authoritative event
    P->>M: master backup sync
    M-->>H: JSON command
    H->>I: typed sync command
    I->>A: command plus observed binding generation
    A->>A: validate role peer target and generation
    A->>PORT: apply operation

9. 幂等策略

• 目标状态命令：每次比较当前状态；相同即 accepted no-change，漂移后重送可重新对齐。
• 无稳定目标身份的旧操作：每 binding generation 最多 256 fingerprint window；Port 失败移除 fingerprint，允许重试。

10. 本地操作锁

备机 Bound 时 canOperateLocally=false，QML 按统一 capability 禁用任务、模式、播单和快捷键等本地入口。来自主机的 typed replication Port 不受此 UI lock 阻挡。

11. 源码证据

• src/code/module/playback/masterbackup/*
• src/code/module/netmessagehandle/masterbackup/*
• src/code/data/playback/masterbackupviewmodel.*
• tests/master_backup_service/*
• tests/replication_command_applier/*

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 20：运行中流重配置 · 下一篇：MiguDelay 架构 22：机审会话