monibuca/plugin/crontab

M7S Crontab 插件说明文档

1. 插件概述

Crontab 插件是 M7S 流媒体服务器的一个扩展组件，主要用于实现基于时间计划的自动录制功能。该插件允许用户创建定时录制计划，根据预设的时间表自动开始和停止流媒体的录制，支持灵活的周期性录制设置。

2. 核心功能

• 定时录制计划管理：创建、更新、删除和查询录制计划
• 流路径关联：将录制计划与特定的流路径关联
• 时间表设置：通过 168 位的二进制字符串（7天×24小时）定义每周的录制时间段
• 自动录制控制：根据时间计划自动开始和停止录制
• 状态监控：查询当前正在执行和计划中的录制任务状态

3. 文件结构与功能

3.1 主要文件

3.1.1 index.go

插件的入口文件，定义了 CrontabPlugin 结构体和初始化方法。

• 主要结构：
  • CrontabPlugin：插件的主结构体，包含插件基础功能、API服务器实现和数据集合
• 主要功能：
  • OnInit()：插件初始化函数，负责数据库迁移、加载已有录制计划并创建相应的定时任务

3.1.2 crontab.go

定义了定时任务的核心逻辑和执行流程。

• 主要结构：
  • TimeSlot：表示一个时间段，包含开始和结束时间
  • Crontab：定时任务调度器，负责根据计划执行录制操作
• 主要功能：
  • Start()：初始化定时任务
  • Run()：阻塞运行定时任务，循环检查并执行录制操作
  • Dispose()：停止定时任务
  • getNextTimeSlot()：计算下一个需要执行的时间段
  • startRecording()：开始录制流
  • stopRecording()：停止录制流

3.1.3 api.go

实现了插件的 API 接口，提供了与前端交互的功能。

• 主要功能：
  • 录制计划管理：List(), Add(), Update(), Remove()
  • 录制计划流关联管理：ListRecordPlanStreams(), AddRecordPlanStream(), UpdateRecordPlanStream(), RemoveRecordPlanStream()
  • 计划解析：ParsePlanTime()
  • 状态查询：GetCrontabStatus()
• 辅助功能：
  • 时间计算：getWeekdayName(), getWeekdayIndex(), getNextDateForWeekday()
  • 时间段计算：calculateTimeSlots(), getNextTimeSlotFromNow()

3.2 子目录文件

3.2.1 pkg 目录

包含数据模型定义和数据库操作相关功能。

• recordplan.go：

  • 定义 RecordPlan 结构体，表示录制计划的数据模型
  • 包含计划ID、名称、时间表和启用状态等字段

• recordplanstream.go：

  • 定义 RecordPlanStream 结构体，表示录制计划与流路径的关联
  • 提供数据库查询的辅助函数，如按流路径模糊查询、按创建时间排序等

3.2.2 pb 目录

包含 Protocol Buffers 定义和生成的代码，用于 API 接口和数据传输。

• crontab.proto：

  • 定义了插件的 API 服务接口
  • 定义了各种请求和响应消息结构
  • 包含 HTTP 路由映射配置

• crontab.pb.go, crontab.pb.gw.go, crontab_grpc.pb.go：

  • 由 Protocol Buffers 编译器自动生成的 Go 代码
  • 实现了消息序列化/反序列化和 gRPC 服务接口

4. 工作流程

4.1 插件初始化流程

1. 插件启动时，OnInit() 方法被调用
2. 执行数据库迁移，确保必要的表结构存在
3. 从数据库加载所有录制计划和关联的流信息
4. 对于已启用的计划，创建并启动相应的定时任务

4.2 录制计划执行流程

1. 定时任务启动后，进入 Run() 方法的循环
2. 通过 getNextTimeSlot() 计算下一个需要执行的时间段
3. 设置定时器等待到达开始时间
4. 到达开始时间后，调用 startRecording() 开始录制
5. 设置定时器等待到达结束时间
6. 到达结束时间后，调用 stopRecording() 停止录制
7. 循环继续，计算下一个时间段

4.3 API 交互流程

1. 前端通过 HTTP/gRPC 接口与插件交互
2. 可以创建、更新、删除录制计划和流关联
3. 可以查询当前正在执行和计划中的录制任务状态
4. 可以解析计划字符串，获取时间段信息

5. 关键概念

5.1 录制计划 (RecordPlan)

录制计划定义了何时进行录制的时间表。每个计划包含：

• ID：唯一标识符
• 名称：计划名称
• 时间表：168位的二进制字符串，表示一周中每个小时是否进行录制
• 启用状态：是否启用该计划

5.2 录制计划流 (RecordPlanStream)

将录制计划与特定的流路径关联，定义了录制的具体参数：

• 计划ID：关联的录制计划ID
• 流路径：要录制的流的路径
• 分片设置：录制文件的分片参数
• 文件路径：录制文件的保存路径
• 启用状态：是否启用该关联

5.3 时间表格式

时间表使用 168 位的二进制字符串表示一周中的每个小时是否进行录制：

• 每天 24 小时，一周 7 天，共 168 小时
• 字符串中的每一位对应一个小时，'1' 表示录制，'0' 表示不录制
• 字符串按周日到周六的顺序排列，每天 24 位

例如：

• 全为 '0'：一周中不进行任何录制
• 前 24 位为 '1'，其余为 '0'：仅在周日全天录制
• 每天的第 9 位到第 17 位为 '1'：每天上午 9 点到下午 5 点录制

6. 使用场景

1. 定期节目录制：适用于每周固定时间播出的节目自动录制
2. 工作时间监控：仅在工作时间段自动录制监控视频
3. 带宽管理：在网络带宽充足的时间段进行录制，避开高峰期
4. 存储优化：只录制有价值的时间段，节省存储空间

7. API 接口说明

7.1 录制计划管理

• 列表查询：GET /plan/api/list
• 添加计划：POST /plan/api/add
• 更新计划：POST /plan/api/update/{id}
• 删除计划：POST /plan/api/remove/{id}

7.2 录制计划流管理

• 列表查询：GET /planstream/api/list
• 添加关联：POST /planstream/api/add
• 更新关联：POST /planstream/api/update
• 删除关联：POST /planstream/api/remove/{planId}/{streamPath}

7.3 其他接口

• 解析计划：GET /plan/api/parse/{plan}
• 状态查询：GET /crontab/api/status

8. 总结

Crontab 插件为 M7S 流媒体服务器提供了强大的定时录制功能，通过灵活的时间表设置和流路径关联，实现了自动化的录制控制。该插件适用于需要定期录制特定时间段流媒体内容的场景，能有效节省人力和存储资源。