hl-api-changelog/changelogs/2026-07/16_fix_grassland_guide_mp4_physical_interleave.md

草原指南 MP4 物理交错修复与测试数据回填

日期：2026-07-16

后端 Issue：HL #5016

后端 PR：HL #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 同时只执行一个重封装任务，并检查临时磁盘空间，避免大文件并发耗尽磁盘。

接口路径和请求体保持不变：

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 立即重复提交或重复上传，应重新查询素材状态。
• 正式发布前应单独改造为异步处理状态机，或提供明确的后台任务查询接口；不建议简单把网关超时提高到数分钟。