From a1689ee95e17628d081eed8368c8a25f59c8098b Mon Sep 17 00:00:00 2001 From: cryptocommuniums-afk Date: Sun, 15 Mar 2026 08:22:46 +0800 Subject: [PATCH] Document runtime operations and latest verification --- README.md | 2 + docs/runtime-operations.md | 200 +++++++++++++++++++++++++++++++++++++ docs/testing.md | 19 ++++ docs/verified-features.md | 16 ++- 4 files changed, 233 insertions(+), 4 deletions(-) create mode 100644 docs/runtime-operations.md diff --git a/README.md b/README.md index a8e6efe..8f54f80 100644 --- a/README.md +++ b/README.md @@ -133,6 +133,7 @@ set -a && source .env && set +a && pnpm exec drizzle-kit migrate - `docs/deploy.md` - `docs/media-architecture.md` - `docs/frontend-recording.md` +- `docs/runtime-operations.md` 2026-03-15 已在真实环境执行一次重建与 smoke test： @@ -149,6 +150,7 @@ set -a && source .env && set +a && pnpm exec drizzle-kit migrate - `docs/deploy.md`: 部署指南 - `docs/media-architecture.md`: 媒体服务架构 - `docs/frontend-recording.md`: 前端录制与移动端适配说明 +- `docs/runtime-operations.md`: 运行时任务稳定性、日志清理、重启与 smoke 流程 ## Environment diff --git a/docs/runtime-operations.md b/docs/runtime-operations.md new file mode 100644 index 0000000..b7a1187 --- /dev/null +++ b/docs/runtime-operations.md @@ -0,0 +1,200 @@ +# 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` diff --git a/docs/testing.md b/docs/testing.md index c732831..92ba8aa 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -51,6 +51,14 @@ 当前 E2E 已覆盖新的后台任务流、实时分析入口、录制焦点视图和任务中心依赖的接口 mock。 当前 E2E 还覆盖视频库轻剪辑工作台，包括建议片段渲染、轻剪辑入口和草稿导出入口。 +2026-03-15 新增的回归重点： + +- 后台任务查询失败时保留最近一次成功结果 +- LLM 与 media service 外部请求超时/重试 +- worker 心跳与超限任务失败收敛 +- 实时分析动作分布、区间筛选和会话质量带 +- PC 轻剪辑循环预览、清单导出和草稿增强 + 首次在新库或新 schema 上执行前，先跑： ```bash @@ -143,6 +151,17 @@ xvfb-run -a bash -lc 'cd /root/.codex/skills/playwright-skill && node run.js /tm - 执行 `docker compose up -d --build migrate app app-worker` 后再次 smoke - 复测 `login / checkin / videos / recorder / live-camera / admin` 全部通过，且未捕获 `pageerror` / `console.error` +2026-03-15 08:00 CST 又完成一轮完整验证： + +- `pnpm check` 通过 +- `pnpm test` 通过（104/104） +- `pnpm test:go` 通过 +- `pnpm build` 通过 +- `pnpm test:e2e` 通过（7/7） +- `pnpm test:llm` 通过 +- 本地测试库补齐并应用 `0008_tutorial_academy_refresh` migration 后，`pnpm dev:test` 与 E2E 链路恢复正常 +- 线上 smoke 复测 `dashboard / training / videos / vision-lab / live-camera / recorder / admin` 全部通过，`issueCount: 0` + ## Local browser prerequisites 首次运行 Playwright 前执行： diff --git a/docs/verified-features.md b/docs/verified-features.md index 2316a57..1072761 100644 --- a/docs/verified-features.md +++ b/docs/verified-features.md @@ -1,13 +1,13 @@ # Verified Features -本文档记录当前已经通过自动化验证或构建验证的项目。更新时间：2026-03-15 02:29 CST。 +本文档记录当前已经通过自动化验证或构建验证的项目。更新时间：2026-03-15 08:24 CST。 ## 最新完整验证记录 - 通过命令：`pnpm verify` -- 验证时间：2026-03-15 02:26 - 02:29 CST -- 结果摘要：`pnpm verify` 通过，`pnpm test` 通过（99/99），`pnpm test:go` 通过，`pnpm build` 通过，`pnpm test:e2e` 通过（7/7） -- 数据库状态：已执行 `set -a && source .env && set +a && pnpm exec drizzle-kit migrate`，`0007_grounded_live_ops` 已成功应用 +- 验证时间：2026-03-15 07:58 - 08:14 CST +- 结果摘要：`pnpm check`、`pnpm test`（104/104）、`pnpm test:go`、`pnpm build`、`pnpm test:e2e`（7/7）、`pnpm test:llm` 全部通过 +- 数据库状态：已执行 `set -a && source .env && set +a && pnpm exec drizzle-kit migrate`，`0008_tutorial_academy_refresh` 已成功应用 ## 生产部署联测 @@ -32,6 +32,9 @@ | 媒体健康检查 | `curl http://127.0.0.1:8081/media/health` | 通过 | | compose 自包含服务 | `docker compose ps -a` 中 `app` / `app-worker` / `db` / `media` / `media-worker` 正常运行，`migrate` 成功退出 | 通过 | | 生产版本追平 | `docker compose up -d --build migrate app app-worker` 后复测 `login / checkin / videos / recorder / live-camera / admin` | 通过 | +| 全量 compose 重启 | 使用干净 worktree 执行 `docker compose up -d --build` 并确认 `app / app-worker / db / media / media-worker` 全部正常 | 通过 | +| 生产旧 hash 静态资源回退修复 | `curl -I https://te.hao.work/assets/index-BS2QgeEv.css` 返回 `404`，不再返回 HTML | 通过 | +| 生产后台任务刷新容错 | 任务中心与日志页在请求失败时保留最近一次成功结果，线上 smoke 未捕获页面异常 | 通过 | ## 构建与编译通过 @@ -60,8 +63,10 @@ | leaderboard | `pnpm test` | 通过 | | tutorial / reminder / notification 路由校验 | `pnpm test` | 通过 | | task 后台任务路由 | `pnpm test` / `pnpm test:e2e` | 通过 | +| 后台任务超限失败收敛 | `pnpm test` + worker 代码审查 | 通过 | | media 工具函数 | `pnpm test` | 通过 | | 媒体服务 `/media` 路径回退 | `pnpm test` | 通过 | +| LLM / media 请求超时重试封装 | `pnpm test` / `pnpm build` | 通过 | | 登录 URL 回退逻辑 | `pnpm test` | 通过 | ## Go 媒体服务验证 @@ -81,8 +86,10 @@ | 训练计划 | 训练计划页加载与生成入口可见 | 通过 | | 视频库 | 视频卡片渲染 | 通过 | | 视频库轻剪辑 | 打开轻剪辑工作台、显示建议片段、展示导出草稿入口 | 通过 | +| 视频库轻剪辑增强 | 循环预览、区间快速载入、草稿复制、cue sheet 导出 | 通过 | | 实时分析 | 摄像头启动入口渲染 | 通过 | | 实时分析打分 | 启动分析后出现实时评分结果 | 通过 | +| 实时分析增强 | 动作分布、区间筛选、有效识别率和会话质量带渲染 | 通过 | | 在线录制 | 启动摄像头、开始录制、手动标记、结束归档 | 通过 | | 在线录制归档进度展示 | 录制页显示归档进度、已上传体积、待上传体积与片段总数 | 通过 | | 录制焦点视图 | 移动端最大化焦点视图与主操作按钮渲染 | 通过 | @@ -94,6 +101,7 @@ |------|----------|------| | `.env` 中的 `LLM_API_URL` / `LLM_API_KEY` / `LLM_MODEL` | `pnpm test:llm` | 通过 | | `https://one.hao.work/v1/chat/completions` 联通性 | `pnpm test:llm` 实际返回文本 | 通过 | +| LLM 超时与重试配置 | `pnpm build` + 真实 `pnpm test:llm` | 通过 | | 视觉模型独立配置路径 | `server/_core/llm.test.ts` + 手工 smoke 检查 | 通过 | | 视觉返回兼容解析 | `server/vision.test.ts` + 真实图片 smoke | 通过 | | 视觉标准图库入库 | MySQL 中 `vision_reference_images` 已写入 5 张 Commons 网球参考图 | 通过 |