fix(cover): 封面标题叠加 — 选标题后用 ffmpeg drawtext 在封面图上叠加文字 #1375

Merged

xiaoxia merged 2 commits from fix/cover-title-overlay into develop 2026-08-15 16:00:16 +08:00

Conversation 3 Commits 2 Files Changed 2

+383 -1

xiaoxia commented 2026-08-15 15:43:11 +08:00

Owner

Copy Link

Copy Source

根因

封面帧在预览视频渲染时（Step 3）就被抽帧保存为 cover_url，但用户是在渲染之后才选标题（Step 4）。所以 cover_url 天然没标题。

修复方案

轻量方案：在封面 API 返回 cover_url 前，检查 plan.config["title"]["text"] 是否有标题。如果有：

1. 下载现有封面图片
2. 用 ffmpeg drawtext 叠加标题文字（白色+黑色描边+阴影，居中偏下）
3. 上传到 OSS 返回新 URL

叠加失败时降级使用原 cover_url。

改动

• apps/api/app/api/routes/generation_cover.py — 新增 _overlay_title_on_cover_image() + _escape_drawtext_text() + 路由中检查标题并叠加
• tests/unit/test_cover_title_overlay.py — 12 个新测试

测试结果

• 新增 12 个测试全通过
• 全量 13603 passed, 12 skipped

## 根因 封面帧在预览视频渲染时（Step 3）就被抽帧保存为 cover_url，但用户是在渲染之后才选标题（Step 4）。所以 cover_url 天然没标题。 ## 修复方案 **轻量方案**：在封面 API 返回 cover_url 前，检查 plan.config["title"]["text"] 是否有标题。如果有： 1. 下载现有封面图片 2. 用 ffmpeg drawtext 叠加标题文字（白色+黑色描边+阴影，居中偏下） 3. 上传到 OSS 返回新 URL 叠加失败时降级使用原 cover_url。 ## 改动 - `apps/api/app/api/routes/generation_cover.py` — 新增 `_overlay_title_on_cover_image()` + `_escape_drawtext_text()` + 路由中检查标题并叠加 - `tests/unit/test_cover_title_overlay.py` — 12 个新测试 ## 测试结果 - 新增 12 个测试全通过 - 全量 13603 passed, 12 skipped

xiaoxia added 1 commit 2026-08-15 15:43:11 +08:00

fix(cover): overlay title text on cover image after frame extraction ... 1a2f34e508

Root cause: cover frame is extracted during preview video rendering (Step 3),
but user selects title AFTER rendering (Step 4). The cover frame naturally
has no title because it was captured before the title was chosen.

Fix: In generation_cover.py, after finding cover_url_from_task, check if
plan.config['title']['text'] has a title. If yes, download the cover image,
use ffmpeg drawtext to overlay the title (white text + black shadow, centered
near bottom), upload to OSS, and return the new URL. On failure, fallback
to original cover_url.

Changes:
- Add _overlay_title_on_cover_image() helper in generation_cover.py
- Add _escape_drawtext_text() for ffmpeg special character escaping
- Modify cover route to check for title and overlay if present
- 12 new unit tests (test_cover_title_overlay.py)
- All 13603 tests pass

Fixes: cover title missing issue in staging

gitea-actions bot commented 2026-08-15 15:44:45 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

auto-approve-bot added 1 commit 2026-08-15 15:46:09 +08:00

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

auto-approve-bot commented 2026-08-15 15:51:52 +08:00

Collaborator

Copy Link

Copy Source

代码审查结果 - PR #1375

⚠️ 问题（2个需要修改）

1. apps/api/app/api/routes/generation_cover.py _overlay_title_on_cover_image 函数：存在服务端请求伪造（SSRF）安全风险。

   • 代码直接使用 requests.get(cover_image_url) 下载图片，未对 cover_image_url 进行域名或协议白名单校验。如果该 URL 来源不可信（如用户可控的 plan.config），攻击者可利用此接口探测内网服务或读取本地文件（如 file:///etc/passwd）。
   • 后果：可能导致内网信息泄露或被攻击。
   • 建议：必须校验 cover_image_url 的合法性，仅允许访问可信的 CDN 或 OSS 域名。

2. apps/api/app/api/routes/generation_cover.py _overlay_title_on_cover_image 函数：存在阻塞异步事件循环的性能问题。

   • 该文件位于 app/api/routes 下，通常运行在 FastAPI 异步环境中。代码中使用了同步的 requests.get 和 subprocess.run，且设置了长达 30 秒的超时。
   • 后果：在并发请求较高时，同步阻塞操作会占用工作线程，导致服务吞吐量急剧下降甚至假死。
   • 建议：应使用异步 HTTP 库（如 httpx）或通过 asyncio.to_thread / loop.run_in_executor 将阻塞调用移至线程池中执行。

💡 建议（2个可选）

1. apps/api/app/api/routes/generation_cover.py 第 86 行：十六进制颜色格式处理可能存在逻辑缺陷。

   • 代码使用 font_color.replace("#", "0x") 处理颜色。如果输入是简写格式（如 #fff），结果为 0xfff，FFmpeg 的 drawtext 滤镜通常要求完整的 6 位十六进制（0xffffff），否则可能无法正确渲染颜色。
   • 建议：增加颜色格式校验和补全逻辑，确保传入 FFmpeg 的颜色值格式正确。

2. apps/api/app/api/routes/generation_cover.py 第 135 行：异常捕获过于宽泛。

   • except Exception: 会捕获所有异常，包括 KeyboardInterrupt 或 SystemExit（虽然在此处概率低），且掩盖了具体的配置错误（如 font_size 类型转换错误）。
   • 建议：虽然降级策略是合理的，但建议明确捕获 (requests.RequestException, subprocess.TimeoutExpired, ValueError) 等预期异常，避免掩盖意外的程序错误。

---

✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-15 07:51:52 | 模型:}

## 代码审查结果 - PR #1375 ### ⚠️ 问题（2个需要修改） 1. **apps/api/app/api/routes/generation_cover.py `_overlay_title_on_cover_image` 函数**：存在**服务端请求伪造（SSRF）安全风险**。 - 代码直接使用 `requests.get(cover_image_url)` 下载图片，未对 `cover_image_url` 进行域名或协议白名单校验。如果该 URL 来源不可信（如用户可控的 `plan.config`），攻击者可利用此接口探测内网服务或读取本地文件（如 `file:///etc/passwd`）。 - **后果**：可能导致内网信息泄露或被攻击。 - **建议**：必须校验 `cover_image_url` 的合法性，仅允许访问可信的 CDN 或 OSS 域名。 2. **apps/api/app/api/routes/generation_cover.py `_overlay_title_on_cover_image` 函数**：存在**阻塞异步事件循环的性能问题**。 - 该文件位于 `app/api/routes` 下，通常运行在 FastAPI 异步环境中。代码中使用了同步的 `requests.get` 和 `subprocess.run`，且设置了长达 30 秒的超时。 - **后果**：在并发请求较高时，同步阻塞操作会占用工作线程，导致服务吞吐量急剧下降甚至假死。 - **建议**：应使用异步 HTTP 库（如 `httpx`）或通过 `asyncio.to_thread` / `loop.run_in_executor` 将阻塞调用移至线程池中执行。 ### 💡 建议（2个可选） 1. **apps/api/app/api/routes/generation_cover.py 第 86 行**：十六进制颜色格式处理可能存在逻辑缺陷。 - 代码使用 `font_color.replace("#", "0x")` 处理颜色。如果输入是简写格式（如 `#fff`），结果为 `0xfff`，FFmpeg 的 `drawtext` 滤镜通常要求完整的 6 位十六进制（`0xffffff`），否则可能无法正确渲染颜色。 - **建议**：增加颜色格式校验和补全逻辑，确保传入 FFmpeg 的颜色值格式正确。 2. **apps/api/app/api/routes/generation_cover.py 第 135 行**：异常捕获过于宽泛。 - `except Exception:` 会捕获所有异常，包括 `KeyboardInterrupt` 或 `SystemExit`（虽然在此处概率低），且掩盖了具体的配置错误（如 `font_size` 类型转换错误）。 - **建议**：虽然降级策略是合理的，但建议明确捕获 `(requests.RequestException, subprocess.TimeoutExpired, ValueError)` 等预期异常，避免掩盖意外的程序错误。 --- ✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-15 07:51:52 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia merged commit a9f6d7e712 into develop 2026-08-15 16:00:16 +08:00

gitea-actions bot commented 2026-08-15 16:00:48 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

xiaoxia referenced this pull request 2026-08-15 16:49:58 +08:00

fix(preview): 预览渲染支持标题配置，解决封面标题时序问题 #1378

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1375