201 行
5.0 KiB
Markdown
201 行
5.0 KiB
Markdown
# Runtime Operations
|
||
|
||
更新时间：2026-03-15 08:20 CST。
|
||
|
||
本文档说明以下几类运行时能力与维护动作：
|
||
|
||
- 后台任务的超时、重试、心跳与失败收敛
|
||
- 日志页面和任务中心的降级行为
|
||
- 实时分析增强项与 PC 轻剪辑增强项
|
||
- 全量重启、日志清理和线上 smoke check 的标准步骤
|
||
|
||
## 1. 后台任务稳定性
|
||
|
||
### 1.1 外部请求超时与重试
|
||
|
||
服务端新增了统一的 `fetchWithTimeout` 封装，当前已接入：
|
||
|
||
- LLM 请求
|
||
- media service 会话查询
|
||
|
||
相关环境变量：
|
||
|
||
- `LLM_TIMEOUT_MS`
|
||
- `LLM_RETRY_COUNT`
|
||
- `MEDIA_FETCH_TIMEOUT_MS`
|
||
- `MEDIA_FETCH_RETRY_COUNT`
|
||
|
||
默认策略：
|
||
|
||
- LLM：超时 45 秒，失败后按配置重试
|
||
- media session 查询：超时 12 秒，失败后按配置重试
|
||
|
||
这样做的目的：
|
||
|
||
- 降低上游网关偶发慢响应导致的前台直接失败
|
||
- 把超时边界显式化，避免请求悬挂
|
||
- 为后台任务提供更稳定的失败判定
|
||
|
||
### 1.2 Worker 心跳与失败收敛
|
||
|
||
后台任务 worker 当前行为：
|
||
|
||
- 领取任务后定期写入 `lockedAt` 心跳
|
||
- 服务异常重启后，超时未续约的 running 任务会重新入队
|
||
- 超过 `maxAttempts` 的 queued 任务会自动转为 failed，不再无限重试
|
||
|
||
相关环境变量：
|
||
|
||
- `BACKGROUND_TASK_POLL_MS`
|
||
- `BACKGROUND_TASK_STALE_MS`
|
||
- `BACKGROUND_TASK_HEARTBEAT_MS`
|
||
|
||
### 1.3 录制归档完全异步化
|
||
|
||
`task.createMediaFinalize` 现在只负责入队，不再在 API 请求阶段同步查询 media service。
|
||
|
||
效果：
|
||
|
||
- 录制页结束录制时更快返回
|
||
- media service 暂时抖动时，不会把前台提交动作直接拖成超时
|
||
- 真正的会话校验、归档、回放可用性判断都在 worker 中执行
|
||
|
||
## 2. 前端任务观测与降级
|
||
|
||
### 2.1 任务中心
|
||
|
||
`TaskCenter` 当前增强：
|
||
|
||
- 查询失败时保留最近一次成功结果
|
||
- 自动重试
|
||
- 显示任务耗时
|
||
- 后台任务成功/失败继续触发前端提示
|
||
|
||
适用页面：
|
||
|
||
- 顶部任务中心
|
||
- `/logs`
|
||
|
||
### 2.2 日志页
|
||
|
||
`/logs` 当前用于查看：
|
||
|
||
- 后台任务状态
|
||
- 错误原因
|
||
- 尝试次数
|
||
- 执行耗时
|
||
- 通知记录
|
||
|
||
当 `task.list` 拉取失败时：
|
||
|
||
- 页面会提示“当前显示最近一次成功结果”
|
||
- 不会因为一次 502 就直接清空日志视图
|
||
|
||
## 3. 实时分析增强
|
||
|
||
`/live-camera` 当前新增与强化内容：
|
||
|
||
- 低可见度守卫：人体关键点可见度不足时优先判定为未知动作
|
||
- 更稳的动作判定：补充前移、躯干偏移、触球高度、双腕展开等启发式
|
||
- 动作分布面板：按非未知动作统计区间数、时长、平均得分、平均置信度
|
||
- 区间筛选：可按动作类型只看正手、反手、发球等片段
|
||
- 会话质量带：根据总分、有效识别率和有效区间数给出“高质量 / 稳定 / 待加强”
|
||
- 最佳片段摘要：显示当前会话的最佳片段得分
|
||
- 最近会话回放入口：已有 `videoUrl` 时可直接打开回放
|
||
|
||
这部分的设计目标不是替代专业模型，而是让前台实时分析在弱模型条件下仍然具备：
|
||
|
||
- 可判断
|
||
- 可筛选
|
||
- 可回看
|
||
|
||
## 4. PC 轻剪辑增强
|
||
|
||
`/videos` 中的轻剪辑工作台当前新增：
|
||
|
||
- 草稿片段数量、总剪辑时长、建议片段数、当前区间时长概览
|
||
- 当前区间循环预览
|
||
- 建议片段一键载入区间
|
||
- 建议片段循环预览
|
||
- 草稿片段快速回填到编辑区
|
||
- 草稿片段信息复制
|
||
- JSON 草稿导出
|
||
- cue sheet 文本清单导出
|
||
|
||
当前仍属于“粗剪计划”层，不直接产出服务器端裁剪视频文件。
|
||
|
||
适合的使用方式：
|
||
|
||
- 先在浏览器里完成粗剪与讲解思路整理
|
||
- 导出草稿或清单
|
||
- 再交给后续的后台剪辑任务或人工剪辑流程
|
||
|
||
## 5. 运行日志清理
|
||
|
||
如需清理所有用户的任务和通知运行日志，可执行：
|
||
|
||
```sql
|
||
DELETE FROM background_tasks;
|
||
DELETE FROM notification_log;
|
||
```
|
||
|
||
说明：
|
||
|
||
- 这会清空 `/logs` 和任务中心中与后台任务相关的历史记录
|
||
- 不影响训练记录、视频、分析结果、成就、评分等业务数据
|
||
- 建议在确认当前没有需要保留的任务审计信息后再执行
|
||
|
||
## 6. 标准重启流程
|
||
|
||
使用 Docker Compose 重启全部服务：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
应至少确认以下服务状态正常：
|
||
|
||
- `app`
|
||
- `app-worker`
|
||
- `db`
|
||
- `media`
|
||
- `media-worker`
|
||
|
||
检查命令：
|
||
|
||
```bash
|
||
docker compose ps
|
||
docker compose logs --tail=80 app-worker
|
||
curl http://127.0.0.1:8081/media/health
|
||
```
|
||
|
||
## 7. 线上 Smoke Check
|
||
|
||
全量重启后建议至少执行：
|
||
|
||
```bash
|
||
curl -I https://te.hao.work/
|
||
curl -I https://te.hao.work/assets/index-BS2QgeEv.css
|
||
pnpm test:llm
|
||
```
|
||
|
||
其中旧资源 URL 返回 `404` 是正确行为，表示缺失静态资源不会再回退成 `index.html`。
|
||
|
||
浏览器级 smoke check 继续复用：
|
||
|
||
```bash
|
||
cd /root/.codex/skills/playwright-skill
|
||
node run.js /tmp/playwright-test-te-full-smoke.js
|
||
```
|
||
|
||
期望结果：
|
||
|
||
- `dashboardOk: true`
|
||
- `trainingOk: true`
|
||
- `videosOk: true`
|
||
- `visionOk: true`
|
||
- `liveCameraOk: true`
|
||
- `adminOk: true`
|
||
- `recorderOk: true`
|
||
- `issueCount: 0`
|