perf(worker): 封面抽帧三优化 — blackdetect黑屏规避+单次ffmpeg批量抽帧+并发上传+CJK字体兜底 #2091

Merged

auto-approve-bot merged 4 commits from fix/cover-blackdetect-batch-upload-fonts into develop 2026-09-28 22:32:56 +08:00

Conversation 2 Commits 4 Files Changed 3

+370 -41

xiaoxia commented 2026-09-28 22:01:27 +08:00

Owner

Copy Link

Copy Source

三个 P2 优化合并一个 PR：

1. 黑屏检测（blackdetect）

抽帧前用 ffmpeg blackdetect=d=0.3:pic_th=0.98:pix_th=0.10 扫描黑屏区间，seek 点落在黑屏内时自动偏移到最近非黑屏位置（前向优先、后向兜底，偏移 tolerance=0.25s）；整段全黑则保留中点并打 warning 日志。避免封面/预览首帧落到黑屏。

2. 封面单次 ffmpeg 抽帧 + 并发上传

• 5 次串行 ffmpeg -ss seek -vframes 1（起停进程 ~200-400ms/次）改为单次 ffmpeg 用 select=between(t,t1-0.03,t1+0.04)+... + -vsync vfr 一次输出 5 帧；
• 5 帧上传 OSS 用 ThreadPoolExecutor(max_workers=min(8,N)) 并发；
• 单次 select 失败/命中帧数不足时自动回退到单帧 -ss seek 兜底，保证鲁棒性。
• 目标：封面阶段从 ~3.1s 压到 <1.5s。

3. Worker Dockerfile 加 fonts-noto-cjk 兜底

• worker.Dockerfile 显式 apt-get install fonts-noto-cjk + fontconfig（防 base 镜像漂移）；
• build 阶段 fc-cache -fv 并 fc-match "Noto Sans CJK SC" | grep -qi noto 校验，确保容器内 fc-match 能正确解析到 Noto，不再依赖 PIL 直读 ttf 兜底路径。

改动文件

• apps/worker/video_processing/thumbnail_generator.py: +274 -38（blackdetect+select批量抽帧+ThreadPool并发上传）
• infra/docker/worker.Dockerfile: +13（fonts-noto-cjk 安装+fc-cache校验）

验证

• ruff check/format ✅
• py_compile ✅
• 等待 CI 构建 Worker 镜像（Dockerfile 改动触发完整镜像 build）+ Staging 部署后实测封面阶段耗时与字体渲染。

三个 P2 优化合并一个 PR： ## 1. 黑屏检测（blackdetect） 抽帧前用 `ffmpeg blackdetect=d=0.3:pic_th=0.98:pix_th=0.10` 扫描黑屏区间，seek 点落在黑屏内时自动偏移到最近非黑屏位置（前向优先、后向兜底，偏移 tolerance=0.25s）；整段全黑则保留中点并打 warning 日志。避免封面/预览首帧落到黑屏。 ## 2. 封面单次 ffmpeg 抽帧 + 并发上传 - 5 次串行 `ffmpeg -ss seek -vframes 1`（起停进程 ~200-400ms/次）改为单次 ffmpeg 用 `select=between(t,t1-0.03,t1+0.04)+...` + `-vsync vfr` 一次输出 5 帧； - 5 帧上传 OSS 用 `ThreadPoolExecutor(max_workers=min(8,N))` 并发； - 单次 select 失败/命中帧数不足时自动回退到单帧 -ss seek 兜底，保证鲁棒性。 - 目标：封面阶段从 ~3.1s 压到 <1.5s。 ## 3. Worker Dockerfile 加 fonts-noto-cjk 兜底 - worker.Dockerfile 显式 apt-get install fonts-noto-cjk + fontconfig（防 base 镜像漂移）； - build 阶段 fc-cache -fv 并 `fc-match "Noto Sans CJK SC" | grep -qi noto` 校验，确保容器内 fc-match 能正确解析到 Noto，不再依赖 PIL 直读 ttf 兜底路径。 ## 改动文件 - apps/worker/video_processing/thumbnail_generator.py: +274 -38（blackdetect+select批量抽帧+ThreadPool并发上传） - infra/docker/worker.Dockerfile: +13（fonts-noto-cjk 安装+fc-cache校验） ## 验证 - ruff check/format ✅ - py_compile ✅ - 等待 CI 构建 Worker 镜像（Dockerfile 改动触发完整镜像 build）+ Staging 部署后实测封面阶段耗时与字体渲染。

xiaoxia added 1 commit 2026-09-28 22:01:27 +08:00

perf(worker): 封面抽帧三优化 — blackdetect黑屏规避+单次ffmpeg批量抽帧+并发上传+CJK字体兜底 ... 3faa11fef0

1. 黑屏检测（blackdetect）：抽帧前先用 ffmpeg blackdetect(d=0.3,pic_th=0.98,pix_th=0.10) 扫描成片黑屏区间，
   seek 点落在黑屏内时偏移到最近非黑屏位置；整段全黑则保留中点并打 warning 日志。避免封面/首帧落到黑屏。
2. 封面批量抽帧+并发上传：5次串行 ffmpeg -ss seek 改成单次 ffmpeg select between(t,...) 一次输出 5 帧；
   5帧上传 OSS 用 ThreadPoolExecutor 并发（max_workers=min(8,N)）。目标封面阶段从 ~3.1s 压到 <1.5s。
   单次 select 失败/命中不足自动回退到单帧 -ss seek 兜底，保证鲁棒性。
3. Worker Dockerfile 加 fonts-noto-cjk 安装与 fc-cache：
   - 在 worker.Dockerfile apt-get install 显式加 fonts-noto-cjk + fontconfig（base 镜像漂移兜底）
   - build 时 fc-cache -fv + fc-match 'Noto Sans CJK SC' 校验，确保 fc-match 能解析到 Noto，
     不再依赖 PIL 直读 ttf 兜底路径。

gitea-actions bot commented 2026-09-28 22:05:16 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#2091
预览链接	https://pr-2091.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #2091 | | 预览链接 | [https://pr-2091.preview.xiaoxiajianji.com](https://pr-2091.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

xiaoxia added 1 commit 2026-09-28 22:06:36 +08:00

fix(ci): Dockerfile 字体安装步骤容错 — 不阻断镜像构建，fc-match 结果打日志 f5cb0b13cf

xiaoxia added 1 commit 2026-09-28 22:14:29 +08:00

test(worker): 更新 thumbnail 单测适配新抽帧流程 + 新增 blackdetect 偏移逻辑纯逻辑测试 74a3bd51ab

auto-approve-bot added 1 commit 2026-09-28 22:21:57 +08:00

style: auto-format with black + isort + ruff + prettier [skip ci-format-check] b6c7308c40

auto-approve-bot merged commit 3904a8f3b5 into develop 2026-09-28 22:32:56 +08:00

auto-approve-bot deleted branch fix/cover-blackdetect-batch-upload-fonts 2026-09-28 22:32:59 +08:00

gitea-actions bot commented 2026-09-28 22:33:35 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #2091 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #2091 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot frontend-dev xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#2091