From bc82060cabe5ef1aca19da165b53896d5ff610b3 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sun, 12 Jul 2026 18:22:27 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E8=8D=89=E5=8E=9F?=
 =?UTF-8?q?=E6=8C=87=E5=8D=974K=E9=AA=8C=E6=94=B6=E4=B8=8E=E6=AD=A3?=
 =?UTF-8?q?=E5=BC=8F=E9=83=A8=E7=BD=B2=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../12_feat_grassland_guide_admin_mp_oss.md   | 38 +++++++++++++++++--
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md b/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md
index b2a8fb1..5833c3a 100644
--- a/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md
+++ b/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md
@@ -2,9 +2,9 @@
 
 > 日期：2026-07-12
 >
-> 后端 Issue：[HL #4919](https://git.1814.love:8443/wx/HL/issues/4919)、[HL #4922](https://git.1814.love:8443/wx/HL/issues/4922)
+> 后端 Issue：[HL #4919](https://git.1814.love:8443/wx/HL/issues/4919)、[HL #4922](https://git.1814.love:8443/wx/HL/issues/4922)、[HL #4927](https://git.1814.love:8443/wx/HL/issues/4927)
 >
-> 后端 PR：[HL #4921](https://git.1814.love:8443/wx/HL/pulls/4921)、[HL #4924](https://git.1814.love:8443/wx/HL/pulls/4924)
+> 后端 PR：[HL #4921](https://git.1814.love:8443/wx/HL/pulls/4921)、[HL #4924](https://git.1814.love:8443/wx/HL/pulls/4924)、[HL #4929](https://git.1814.love:8443/wx/HL/pulls/4929)
 >
 > 测试分支：`dev-v3`
 >
@@ -114,6 +114,7 @@ export async function readVideoDurationSeconds(file: File): Promise<number> {
 - 文件扩展名必须是 `.mp4`。
 - `contentType` 必须以 `video/mp4` 开头。
 - `durationSeconds` 必须大于 0。
+- 单个视频最大 `2147483648` 字节（2 GiB），大于 `10485760` 字节（10 MiB）时使用 OSS 分片上传。
 
 响应中的 `uploadMode` 有两种：
 
@@ -136,7 +137,13 @@ export async function readVideoDurationSeconds(file: File): Promise<number> {
 }
 ```
 
-确认成功后保存返回的 `materialId`，创建草原指南内容时作为 `videoMaterialId` 提交。
+确认接口会通过 OSS `HeadObject` 读取实际对象元数据，并校验：
+
+- OSS 对象必须真实存在。
+- 实际 `Content-Length` 必须等于申请上传凭证时声明的 `fileSize`。
+- MP4 的实际 `Content-Type` 必须是 `video/mp4`（允许携带参数）。
+
+任一校验失败时素材不会进入 `ACTIVE`。确认成功后保存返回的 `materialId`，创建草原指南内容时作为 `videoMaterialId` 提交。
 
 ### 3.4 文件夹上传
 
@@ -308,6 +315,7 @@ OSS MP4 支持 Range 请求，原生 `<video>` 能从 MP4 元数据读取并显
 | The Daily Dweebs | `2076195939797688322` | `2076196082752155649` | 61 秒 | `CUSTOM` |
 | Caminandes 3: Llamigos | `2076195998660550657` | `2076196084920610817` | 151 秒 | `AUTO` |
 | Glass Half | `2076196033146118145` | `2076196086652858370` | 194 秒 | `AUTO` |
+| 呼伦贝尔草原有多大？（3812×2160 原片） | `2076248042813480962` | `2076248969276551170` | 83 秒 | `CUSTOM` |
 
 验收结果：
 
@@ -322,8 +330,30 @@ OSS MP4 支持 Range 请求，原生 `<video>` 能从 MP4 元数据读取并显
 - 实测下架其中一条后推荐 `total` 从 2 变为 1，候选中不含下架内容；重上架后恢复为 2。
 - 故意提交伪造 `publishTime=2000年`、`durationSeconds=9999` 和旧 `relatedVideoIds`，后端均未采纳；下架重上架后首次发布时间保持不变。
 - 旧 `/play-auth` 接口已不可用。
+- 真实 4K 原片为 `412360919` 字节（约 393 MiB），通过 `STS_MULTIPART` 上传；OSS `HEAD` 返回 `200`、`Content-Type: video/mp4`、`Content-Length: 412360919`。
+- 对 4K 原片请求 `Range: bytes=0-1` 返回 `206`、`Content-Range: bytes 0-1/412360919`，证明 OSS 支持原生 `<video>` 所需的分段读取，流量不经过业务服务器。
+- 4K 内容使用独立上传的 JPEG 封面，详情返回 `coverSource=CUSTOM`；推荐分页返回 3 条上架内容且排除了当前视频。
+- 当前测试桶默认域名同时返回 `Content-Disposition: attachment` 和 `x-oss-force-download: true`。HTTP Range 能正常工作，但小程序仍须做真机播放验收；若原生 `<video>` 因该响应头拒绝播放，优先给同一 OSS Bucket 绑定自定义域名直出，不需要先接 CDN。
 
-## 8. 前端改造检查单
+## 8. 2026-07-14 正式环境 Nacos 部署清单
+
+草原指南一期暂不使用 CDN、VOD、HLS 或转码，正式环境仅同步 OSS 原片上传上限。部署 `hl-user-service` 前执行：
+
+1. 在正式 Nacos 读取并备份完整 `hl-user-service-prod.yml`，确认生产实例实际加载的 namespace、group 和 dataId。
+2. 只做最小配置修改：
+
+```yaml
+file:
+  max-size:
+    video: 2147483648
+  resumable-threshold: 10485760
+```
+
+3. 不复制仓库内测试配置中的其他值，不覆盖正式环境已有的 OSS、数据库、Redis 或鉴权配置。
+4. 串行滚动部署 `hl-user-service`，确认两实例均注册健康且配置已生效。
+5. 用正式 OSS 做一轮大于 10 MiB 的 MP4 分片上传、确认、`HEAD` 和 `Range 206` 验收；不得在日志或交付文档中记录 STS、AccessKey、Token 等凭证。
+
+## 9. 前端改造检查单
 
 - [ ] 新增“草原指南管理”列表、编辑和发布页面。
 - [ ] 素材库展示顶级分类“草原指南”，隐藏系统分类删除/停用/改码操作。