diff --git a/changelogs/2026-07/16_fix_grassland_guide_mp4_physical_interleave.md b/changelogs/2026-07/16_fix_grassland_guide_mp4_physical_interleave.md new file mode 100644 index 0000000..0068f2f --- /dev/null +++ b/changelogs/2026-07/16_fix_grassland_guide_mp4_physical_interleave.md @@ -0,0 +1,98 @@ +# 草原指南 MP4 物理交错修复与测试数据回填 + +> 日期:2026-07-16 +> +> 后端 Issue:[HL #5016](https://git.1814.love:8443/wx/HL/issues/5016) +> +> 后端 PR:[HL #5019](https://git.1814.love:8443/wx/HL/pulls/5019) +> +> 测试分支:`dev-v3` +> +> 影响服务:`hl-user-service` +> +> 本次不修改前端仓库,不新增或修改接口字段 + +## 1. 问题结论 + +草原指南真实 4K MP4 在 `1x`、`2x` 播放时出现固定位置反复缓冲。浏览器 Network 中同一文件产生大量被取消并重新发起的 `206 Partial Content` 请求,实际传输量可以超过文件本身体积。 + +该问题包含两个独立因素: + +1. 历史 MP4 虽然已经把 `moov` 移到 `mdat` 前面,但音频、视频 Sample 在 `mdat` 中没有按时间物理交错。播放到同一时间点时,浏览器需要在文件相距很远的位置来回读取音视频数据,造成 Range 请求抖动、取消和重复下载。 +2. 原片本身约 `357204588` 字节、`71` 秒,平均码率约 `40.25 Mbps`。2026-07-16 当前诊断链路连续读取 OSS Range 仅约 `0.52–1.44 MB/s`(约 `4.14–11.50 Mbps`),低于 `1x` 所需的约 `5.03 MB/s`,因此修复文件结构后仍可能因实际网络吞吐不足发生正常缓冲。 + +前端缓存策略不能补足长期吞吐缺口。`preload="auto"` 只能改善起播等待,不能让 `10 Mbps` 链路持续播放 `40 Mbps` 原片。 + +## 2. 后端修复 + +草原指南视频上传确认阶段新增 MP4 无损重封装: + +- 不重新编码,不改变 H.264/AAC Sample。 +- 不降低分辨率、帧率或码率。 +- 保持原视频、音频轨的 Sample 数量、Sample 总字节数和时长。 +- 将 `ftyp`、`moov` 放在文件前部。 +- 以约 2 秒为窗口重新排列音频、视频 Chunk,使相同时间点的数据物理相邻。 +- 重封装前后执行媒体指纹校验;不一致时拒绝替换原对象。 +- 新对象使用 `.progressive-...mp4` Key,成功后再以 CAS 更新文件记录;旧对象暂不删除,便于回滚。 +- 单个 Pod 同时只执行一个重封装任务,并检查临时磁盘空间,避免大文件并发耗尽磁盘。 + +接口路径和请求体保持不变: + +```http +POST /admin/material/upload/confirm +``` + +前端仍然只提交原有 `materialId`、`description` 和 `tagIds`,不需要增加重封装参数。 + +## 3. 历史测试数据回填 + +已对测试环境问题视频执行一次性回填: + +| 项目 | 值 | +| --- | --- | +| 草原指南视频 ID | `2076910159484928002` | +| 素材 ID | `2076909130286612482` | +| 文件 ID | `2076909128663379970` | +| 文件大小 | `357204588` 字节 | +| 新时长 | `71` 秒 | +| 新文件标识 | OSS Key 包含 `.progressive-2076909128663379970-` | + +回填结果: + +- `file_info` 已切换为新 `.progressive-...mp4`,状态为 `ACTIVE / OSS_MP4_READY_V1`。 +- `material.oss_url`、自动封面和时长已切换。 +- `grassland_guide_video` 自动封面和时长已同步,业务记录仍为 `PUBLISHED`。 +- 资源服务 `8082/8182` 与网关 `8080` 的匿名详情、播放接口均返回新地址。 +- OSS `HEAD` 返回 `200 video/mp4`、`Content-Length: 357204588`、`Accept-Ranges: bytes`。 +- `Range: bytes=0-1048575` 返回 `206` 和正确的 `Content-Range`。 + +## 4. 部署与验证证据 + +- 修复提交:`4529da5e97fea21022ca700390a146944608eadc` +- `dev-v3` 合并提交:`65c63a68d903370d07dd80ffea62ac58ccfb31c8` +- `hl-user-service` 测试环境滚动部署任务:`f4d670ba` +- 两实例 `8081/8181` 均启动健康。 +- `hl-user-service` 测试:`3226` 个测试,`0` 失败,`0` 错误,`6` 跳过。 +- 真实 357 MB 文件无损重封装测试通过;重封装前后轨道 Sample 数、Sample 字节数和时长一致。 +- 原文件约 44 秒处的音频、视频数据物理距离约 `185.7 MB`;重封装后缩短到约 `69.7 KB`。 + +## 5. 仍需处理的基础设施边界 + +本次后端修复解决“文件内部排列导致重复 Range 请求”的问题,但不能提高用户到 OSS 的实时带宽。 + +在“不降低码率、不生成低清档”的前提下: + +- `1x` 需要链路持续高于约 `40.25 Mbps`,还应预留网络波动余量。 +- `2x` 平均需要约 `80.50 Mbps`,短时峰值可能更高。 +- 当前测试桶传输加速域名请求返回 `400`,未形成可用的加速播放链路。 +- 若目标用户链路长期低于原片码率,只能选择 OSS 前置 CDN/边缘缓存、开通并验证 OSS 传输加速,或让用户在播放前基本下载完整文件;单纯调整浏览器缓冲逻辑无法解决。 + +接入 CDN 或 OSS 传输加速会改变基础设施和费用,须单独确认后实施。不得为规避该问题把流量代理到 Java 服务,也不得把几百 MB 文件整体读入服务内存。 + +## 6. 大文件上传确认超时提醒 + +本次真实文件在测试环境完成下载、重封装、上传共耗时约 `410` 秒,超过当前网关约 `60` 秒的请求超时。 + +- 服务端任务能够继续完成,但前端可能先收到 `504`。 +- 在异步媒体处理改造完成前,前端不得因单次 `504` 立即重复提交或重复上传,应重新查询素材状态。 +- 正式发布前应单独改造为异步处理状态机,或提供明确的后台任务查询接口;不建议简单把网关超时提高到数分钟。