524 lines
13 KiB
Markdown
524 lines
13 KiB
Markdown
# 赛事直播子表与多线路播放设计
|
||
|
||
## 背景
|
||
|
||
当前赛事数据只在 `la_match.live_url` 中保存单个第三方直播链接，存在几个限制：
|
||
|
||
- 无法为同一场赛事维护多条直播线路
|
||
- 无法保存同一线路解析出的多种播放流地址
|
||
- 无法区分人工维护的入口链接和程序抓取的真实播放地址
|
||
- 前台比赛详情页只能展示单个直播入口，无法切换播放流
|
||
|
||
本次改造需要把“赛事直播”从主表单字段升级为“赛事 -> 直播线路子表”，同时保留 `la_match.live_url` 作为兼容字段。
|
||
|
||
## 目标
|
||
|
||
1. 新增赛事直播子表，一场赛事可维护多条直播线路。
|
||
2. 每条线路保存 4 个播放地址：
|
||
- `play_url_flv`
|
||
- `play_url_hd_flv`
|
||
- `play_url_m3u8`
|
||
- `play_url_hd_m3u8`
|
||
3. 直播抓取逻辑放到 `docker/crawler`，按现有 Python crawler 惯例接入。
|
||
4. 后台赛事列表改成“主表 + 展开子表”的直播线路管理方式。
|
||
5. 前台比赛详情页展示多条直播线路，并允许用户自由切换播放流。
|
||
6. 保留 `la_match.live_url`，自动回填为该赛事“最早新增的一条直播线路”的 `source_url`。
|
||
|
||
## 非目标
|
||
|
||
- 本轮不改 PC 前台直播 UI。
|
||
- 本轮不增加直播抓取历史日志表。
|
||
- 本轮不抽象多站点通用抓取框架，只先支持当前已知直播站解析。
|
||
|
||
## 当前现状
|
||
|
||
### 数据层
|
||
|
||
- 赛事主表：`la_match`
|
||
- 兼容直播字段：`la_match.live_url`
|
||
- 当前没有直播子表
|
||
|
||
### 后台
|
||
|
||
- `admin/src/views/match/lists/index.vue` 编辑弹窗中直接维护 `live_url`
|
||
- `server/app/adminapi/logic/match/MatchLogic.php` 允许编辑 `live_url`
|
||
|
||
### 前台
|
||
|
||
- `server/app/api/controller/MatchController.php::detail()` 返回单个 `live_url`
|
||
- `uniapp/src/pages/match_detail/match_detail.vue` 只渲染单个直播入口卡
|
||
|
||
### 调度
|
||
|
||
- Docker crawler 任务由 `docker/crawler/main.py` 注册 action
|
||
- `docker/crawler/config/crawler_tasks.yaml` 维护 Docker 内部 cron
|
||
- `la_dev_crontab` 仍保留任务记录，用于后台展示和沿用“已迁移到 Docker”惯例
|
||
|
||
## 总体设计
|
||
|
||
### 方案选型
|
||
|
||
采用“单子表保存当前线路状态”的方案，不新增抓取历史表。
|
||
|
||
每条直播线路在子表中保留当前最新抓取结果；抓取失败时保留旧值，不清空历史可用地址。
|
||
|
||
### 设计总览
|
||
|
||
1. 新增 `la_match_live` 子表。
|
||
2. 后端新增 `MatchLive` 模型、adminapi 线路管理接口、前台详情聚合返回。
|
||
3. 后台赛事列表新增展开子表，替换原单字段 `live_url` 手工编辑。
|
||
4. `docker/crawler` 新增 `match_live_stream` Python 任务，每分钟执行一次。
|
||
5. 比赛详情页新增多线路展示和播放流切换，默认使用 `play_url_m3u8`。
|
||
|
||
## 数据模型设计
|
||
|
||
### 新增数据表
|
||
|
||
表名：`la_match_live`
|
||
|
||
建议字段：
|
||
|
||
- `id` bigint unsigned，主键
|
||
- `match_id` int unsigned，关联 `la_match.id`
|
||
- `title` varchar(255)，直播标题
|
||
- `source_url` varchar(500)，指向网址
|
||
- `play_url_flv` varchar(1000)，标清 flv
|
||
- `play_url_hd_flv` varchar(1000)，高清 flv
|
||
- `play_url_m3u8` varchar(1000)，标清 m3u8
|
||
- `play_url_hd_m3u8` varchar(1000)，高清 m3u8
|
||
- `fetch_status` tinyint unsigned，抓取状态
|
||
- `0` = pending
|
||
- `1` = success
|
||
- `2` = failed
|
||
- `fetch_error` varchar(500)，最近一次抓取错误信息
|
||
- `last_fetch_at` int unsigned，最近抓取时间
|
||
- `next_fetch_at` int unsigned，下次抓取时间
|
||
- `create_time` int unsigned
|
||
- `update_time` int unsigned
|
||
- `delete_time` int unsigned nullable
|
||
|
||
### 索引与约束
|
||
|
||
- 主键：`id`
|
||
- 唯一约束：`uk_match_source_url (match_id, source_url)`
|
||
- 普通索引：
|
||
- `idx_match_id (match_id)`
|
||
- `idx_next_fetch_at (next_fetch_at)`
|
||
- `idx_fetch_status (fetch_status)`
|
||
- `idx_match_create_time (match_id, create_time)`
|
||
|
||
### 模型约定
|
||
|
||
- 新增模型：`server/app/common/model/match/MatchLive.php`
|
||
- 继续沿用 `BaseModel`
|
||
- 使用 `create_time / update_time / delete_time` 与现有 `la_match` 保持一致
|
||
|
||
## 兼容规则
|
||
|
||
### `la_match.live_url`
|
||
|
||
保留 `la_match.live_url`，但不再允许后台人工直接维护。
|
||
|
||
自动回填规则：
|
||
|
||
- 若赛事存在直播线路，则回填“该赛事最早新增的一条直播线路”的 `source_url`
|
||
- 若赛事不存在直播线路，则将 `la_match.live_url` 置空
|
||
|
||
触发时机：
|
||
|
||
- 新增线路后
|
||
- 编辑线路 `source_url` 后
|
||
- 删除线路后
|
||
- 恢复已删除线路后（若后续有恢复能力）
|
||
|
||
### 前台兼容
|
||
|
||
`/api/match/detail` 继续返回：
|
||
|
||
- `live_url`：旧兼容字段
|
||
- `live_list`：新多线路列表
|
||
|
||
旧页面仍可只使用 `live_url`，新页面优先使用 `live_list`。
|
||
|
||
## 后台设计
|
||
|
||
### 页面交互
|
||
|
||
页面：`admin/src/views/match/lists/index.vue`
|
||
|
||
改造为：
|
||
|
||
- 赛事主表保留现有字段
|
||
- 新增展开列
|
||
- 展开后展示当前赛事的直播线路子表
|
||
|
||
子表字段：
|
||
|
||
- 直播标题
|
||
- 指向网址
|
||
- 主播放流（`play_url_m3u8`）
|
||
- 高清 m3u8（`play_url_hd_m3u8`）
|
||
- 标清 flv（`play_url_flv`）
|
||
- 高清 flv（`play_url_hd_flv`）
|
||
- 抓取状态
|
||
- 最近抓取时间
|
||
- 创建时间
|
||
- 更新时间
|
||
|
||
### 后台操作
|
||
|
||
子表提供：
|
||
|
||
- 新增线路
|
||
- 编辑线路
|
||
- 删除线路
|
||
|
||
人工可维护字段仅有：
|
||
|
||
- `title`
|
||
- `source_url`
|
||
|
||
以下字段只读：
|
||
|
||
- 4 个播放地址
|
||
- `fetch_status`
|
||
- `fetch_error`
|
||
- `last_fetch_at`
|
||
- `next_fetch_at`
|
||
- `create_time`
|
||
- `update_time`
|
||
|
||
### 旧字段替换
|
||
|
||
从赛事编辑弹窗中移除可编辑的 `live_url` 输入框。
|
||
|
||
可选保留只读展示：
|
||
|
||
- 字段名：`兼容主链接（自动）`
|
||
- 值：`la_match.live_url`
|
||
|
||
### adminapi 接口
|
||
|
||
新增控制器建议：
|
||
|
||
- `server/app/adminapi/controller/match/MatchLiveController.php`
|
||
|
||
新增接口：
|
||
|
||
- `GET /adminapi/match.matchLive/lists`
|
||
- `GET /adminapi/match.matchLive/detail`
|
||
- `POST /adminapi/match.matchLive/add`
|
||
- `POST /adminapi/match.matchLive/edit`
|
||
- `POST /adminapi/match.matchLive/delete`
|
||
|
||
新增对应层：
|
||
|
||
- `lists/match/MatchLiveLists.php`
|
||
- `logic/match/MatchLiveLogic.php`
|
||
- `validate/match/MatchLiveValidate.php`
|
||
|
||
`match.match/edit` 只维护赛事本身字段，不再接收人工写入的 `live_url`。
|
||
|
||
## 前台接口设计
|
||
|
||
### `/api/match/detail`
|
||
|
||
在现有赛事详情返回结构上新增 `live_list`。
|
||
|
||
`live_list` 单项字段：
|
||
|
||
- `id`
|
||
- `title`
|
||
- `source_url`
|
||
- `play_url_flv`
|
||
- `play_url_hd_flv`
|
||
- `play_url_m3u8`
|
||
- `play_url_hd_m3u8`
|
||
- `fetch_status`
|
||
- `last_fetch_at`
|
||
- `update_time`
|
||
- `default_play_url`
|
||
- `stream_options`
|
||
|
||
#### `default_play_url`
|
||
|
||
固定优先取值顺序：
|
||
|
||
1. `play_url_m3u8`
|
||
2. `play_url_hd_m3u8`
|
||
3. `play_url_flv`
|
||
4. `play_url_hd_flv`
|
||
|
||
当前业务上默认以 `play_url_m3u8` 作为主播放流。
|
||
|
||
#### `stream_options`
|
||
|
||
后端组装为可直接渲染的数组，顺序固定：
|
||
|
||
1. `M3U8` -> `play_url_m3u8`
|
||
2. `HD M3U8` -> `play_url_hd_m3u8`
|
||
3. `FLV` -> `play_url_flv`
|
||
4. `HD FLV` -> `play_url_hd_flv`
|
||
|
||
空值不返回。
|
||
|
||
## uniapp 页面设计
|
||
|
||
页面：`uniapp/src/pages/match_detail/match_detail.vue`
|
||
|
||
### 直播区域
|
||
|
||
将当前单个“直播详情”入口卡改造成“直播线路列表”。
|
||
|
||
每条线路展示：
|
||
|
||
- 直播标题
|
||
- 最近更新时间
|
||
- 抓取状态
|
||
- 默认播放流标识
|
||
|
||
### 播放行为
|
||
|
||
用户点击某条线路后：
|
||
|
||
- 进入独立播放页或播放器弹层
|
||
- 默认使用 `default_play_url`
|
||
- 播放流切换区展示 `stream_options`
|
||
- 用户可自由切换 4 条播放流
|
||
|
||
若某个流为空，则不展示该流的切换按钮。
|
||
|
||
### 兜底行为
|
||
|
||
- 若 `live_list` 不为空，优先渲染 `live_list`
|
||
- 若 `live_list` 为空但 `live_url` 有值，则保留旧入口卡
|
||
- 若两者都为空，则不显示直播区域
|
||
|
||
### 打开源网页
|
||
|
||
播放器区域保留“打开源网页”按钮，跳转 `source_url`，作为播放器兼容性兜底。
|
||
|
||
## Docker / Python 抓取设计
|
||
|
||
### 任务入口
|
||
|
||
新增文件：
|
||
|
||
- `docker/crawler/match_live_stream.py`
|
||
|
||
在 `docker/crawler/main.py` 注册 action：
|
||
|
||
- `match_live_stream`
|
||
|
||
### Docker 调度
|
||
|
||
在 `docker/crawler/config/crawler_tasks.yaml` 新增任务：
|
||
|
||
- `key: match_live_stream`
|
||
- `name: 赛事直播流抓取`
|
||
- `action: match_live_stream`
|
||
- `cron: "*/1 * * * *"`
|
||
|
||
### `la_dev_crontab` 记录
|
||
|
||
新增一条后台可见任务记录：
|
||
|
||
- `name`: 赛事直播流抓取
|
||
- `command`: `crawler`
|
||
- `params`: `match_live_stream`
|
||
- `expression`: `* * * * *`
|
||
|
||
这条记录沿用当前项目的“迁移到 Docker crawler”惯例：
|
||
|
||
- 后台可展示
|
||
- 真实执行由 Docker 调度
|
||
- PHP `crontab` 不直接执行抓取逻辑
|
||
|
||
## 抓取调度规则
|
||
|
||
### 选取规则
|
||
|
||
每分钟执行一次，从 `la_match_live` 中选择：
|
||
|
||
- `next_fetch_at <= now`
|
||
- 未删除
|
||
|
||
排序：
|
||
|
||
- `next_fetch_at asc`
|
||
- `id asc`
|
||
|
||
每轮限制 `20-50` 条，首版建议 `30` 条。
|
||
|
||
### 新线路 / 未完整抓取线路
|
||
|
||
判定为“未完整抓取”：
|
||
|
||
- 4 个播放地址中任意一个为空，或至少主流地址 `play_url_m3u8` 为空
|
||
|
||
行为：
|
||
|
||
- 新增或编辑 `source_url` 后立即置为 `fetch_status = 0`
|
||
- `next_fetch_at = now`
|
||
- 若抓取失败，`next_fetch_at = now + 60`
|
||
|
||
### 已抓到地址的线路
|
||
|
||
若线路已有可用播放地址：
|
||
|
||
- 抓取成功：`next_fetch_at = now + 600`
|
||
- 抓取失败：保留旧值，`next_fetch_at = now + 600`
|
||
|
||
### 解析来源
|
||
|
||
抓取入口为 `source_url`。
|
||
|
||
首版仅支持当前确认的直播站页面解析逻辑，不抽象成复杂通用框架。
|
||
|
||
### 播放地址回填
|
||
|
||
抓取成功后更新：
|
||
|
||
- `play_url_flv`
|
||
- `play_url_hd_flv`
|
||
- `play_url_m3u8`
|
||
- `play_url_hd_m3u8`
|
||
- `fetch_status = 1`
|
||
- `fetch_error = ''`
|
||
- `last_fetch_at = now`
|
||
- `next_fetch_at = now + 600`
|
||
- `update_time = now`
|
||
|
||
抓取失败后更新：
|
||
|
||
- `fetch_status = 2`
|
||
- `fetch_error = 最近错误`
|
||
- `last_fetch_at = now`
|
||
- `next_fetch_at = now + 60` 或 `now + 600`（视线路是否已有可用地址）
|
||
- `update_time = now`
|
||
|
||
## 稳定性设计
|
||
|
||
### 锁
|
||
|
||
`match_live_stream` action 增加跨进程锁，避免 Docker cron 重入。
|
||
|
||
### 超时
|
||
|
||
- 单条线路抓取需要超时
|
||
- 整个 action 在 `docker/crawler/main.py` 中配置 action 级别超时
|
||
|
||
### 失败保护
|
||
|
||
抓取失败时不得清空已有播放地址，避免前台线路因为一次失败整体不可用。
|
||
|
||
## 错误处理
|
||
|
||
- 页面结构变更导致解析不到 4 个地址时：
|
||
- 新线路维持 `pending/failed`
|
||
- 老线路保留旧地址
|
||
- 删除直播线路后，立即重新计算 `la_match.live_url`
|
||
- 后台人工编辑 `source_url` 后，播放地址字段只由 Python 任务刷新
|
||
|
||
## 代码改造范围
|
||
|
||
### server
|
||
|
||
- `server/app/common/model/match/MatchLive.php`
|
||
- `server/app/adminapi/controller/match/MatchLiveController.php`
|
||
- `server/app/adminapi/lists/match/MatchLiveLists.php`
|
||
- `server/app/adminapi/logic/match/MatchLiveLogic.php`
|
||
- `server/app/adminapi/validate/match/MatchLiveValidate.php`
|
||
- `server/app/adminapi/logic/match/MatchLogic.php`
|
||
- `server/app/api/controller/MatchController.php`
|
||
|
||
### admin
|
||
|
||
- `admin/src/api/match.ts`
|
||
- `admin/src/views/match/lists/index.vue`
|
||
|
||
### uniapp
|
||
|
||
- `uniapp/src/pages/match_detail/match_detail.vue`
|
||
- 如需独立播放页，再新增对应页面及路由注册
|
||
|
||
### docker/crawler
|
||
|
||
- `docker/crawler/match_live_stream.py`
|
||
- `docker/crawler/main.py`
|
||
- `docker/crawler/config/crawler_tasks.yaml`
|
||
- 对应测试文件
|
||
|
||
### docs/sql
|
||
|
||
- 新建 `create_match_live_table.sql`
|
||
- 新建 `insert_crontab_match_live_stream.sql`
|
||
- 如需停用旧逻辑，再补停用 SQL
|
||
|
||
## 验证方案
|
||
|
||
### 后端
|
||
|
||
- `php -l` 覆盖新增/修改的 PHP 文件
|
||
- 静态/最小回归脚本覆盖：
|
||
- 直播线路新增、编辑、删除
|
||
- `la_match.live_url` 自动回填
|
||
- `/api/match/detail` 返回 `live_list`
|
||
|
||
### Python crawler
|
||
|
||
单测覆盖：
|
||
|
||
- 目标站解析出 4 个播放地址
|
||
- 失败时保留旧地址
|
||
- 新线路 1 分钟重试
|
||
- 已抓地址线路 10 分钟更新
|
||
- 互斥锁防重入
|
||
|
||
### 管理后台
|
||
|
||
- 展开子表展示
|
||
- 子表新增、编辑、删除
|
||
- 播放地址只读展示
|
||
- `npm run build`
|
||
|
||
### uniapp
|
||
|
||
- 比赛详情页展示多条直播线路
|
||
- 默认使用 `play_url_m3u8`
|
||
- 允许手动切换流
|
||
- 空流不展示切换按钮
|
||
- `npm run build:h5`
|
||
|
||
## 上线边界
|
||
|
||
本轮改造包含：
|
||
|
||
- `server`
|
||
- `admin`
|
||
- `uniapp`
|
||
- `docker/crawler`
|
||
- `docs/sql`
|
||
|
||
本轮不包含：
|
||
|
||
- PC 前台直播线路 UI
|
||
- 抓取历史日志表
|
||
- 多站点通用解析抽象
|
||
|
||
## 风险点
|
||
|
||
1. 第三方直播站页面结构可能变更，导致解析失败。
|
||
2. `m3u8` / `flv` 地址多为时效链接，抓取周期与前台展示需要允许“旧值短期继续可用”。
|
||
3. `uniapp` 不同平台对直链播放兼容性不同，因此必须保留 `source_url` 跳转兜底。
|
||
4. 后台一旦放开人工编辑播放地址，容易与爬虫更新冲突，因此必须禁止手改播放地址字段。
|
||
|
||
## 实施顺序建议
|
||
|
||
1. 建表 + 后端模型与逻辑
|
||
2. 后台子表接口与 UI
|
||
3. Python crawler 与 Docker 调度
|
||
4. 前台 `/api/match/detail` 聚合
|
||
5. uniapp 多线路播放 UI
|
||
6. SQL、回归测试、部署验证
|