fix(P0): gpu-encoder 冷启动防护 — pre-warm + 首字节短超时兜底 (#2072)

Co-authored-by: xiaoxia <dev@xiaoxiajianji.com>
Co-committed-by: xiaoxia <dev@xiaoxiajianji.com>

.gitea/workflows/ci-pipeline.yml

@@ -813,7 +813,7 @@ jobs:
         IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:pr-${GITHUB_SHA}"
         CACHE_REF="${REGISTRY}/${{ matrix.cache_name }}:develop"
 
-        EXTRA_BUILD_ARGS="APP_VERSION=\"${GITHUB_SHA}\""
+        EXTRA_BUILD_ARGS="APP_VERSION=${GITHUB_SHA}"
 
         # Worker 与 API/Web 统一走持久 builder（ci-builder-persist），共享宿主机层缓存
         NO_CACHE_FLAG=""
@@ -1014,7 +1014,7 @@ jobs:
           PUSHED_TAGS_SUMMARY="${BRANCH_TAG}"
         fi
 
-        EXTRA_BUILD_ARGS="APP_VERSION=\"${GITHUB_SHA}\""
+        EXTRA_BUILD_ARGS="APP_VERSION=${GITHUB_SHA}"
 
         NO_CACHE_FLAG=""
         for i in 1 2 3; do
@@ -1238,9 +1238,11 @@ jobs:
         ACR_PASSWORD: "${{ secrets.ACR_PASSWORD }}"
       run: |
         set -eux
-        # CI runner (act_runner) 部署在 116 staging 本机（116.62.226.203 公网 22 未开放），
-        # 默认走 127.0.0.1:22 本机 SSH，避免跨机网络依赖；可通过 secrets 覆盖。
-        staging_host="${STAGING_SSH_HOST:-127.0.0.1}"
+        # Staging 业务机 = 116.62.226.203（公网 sshd 端口 22）。
+        # 47.98.113.167 现为生产机（sshd 端口 22222），不承载 staging 容器。
+        # CI job 在隔离容器网络内执行，127.0.0.1 会指向 job 容器自身而失败，
+        # 故默认目标必须是 staging 业务机；仍可通过 secrets 覆盖。
+        staging_host="${STAGING_SSH_HOST:-116.62.226.203}"
         staging_user="${STAGING_SSH_USER:-root}"
         staging_port="${STAGING_SSH_PORT:-22}"
         echo "Host: $staging_host"
@@ -1552,7 +1554,7 @@ jobs:
         IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:${TAG_NAME}"
         CACHE_REF="${REGISTRY}/${{ matrix.cache_name }}:main"
 
-        EXTRA_BUILD_ARGS="APP_VERSION=\"${TAG_NAME}\""
+        EXTRA_BUILD_ARGS="APP_VERSION=${TAG_NAME}"
 
         # Docker build 带重试：失败自动重试2次，第2次重试加--no-cache
         NO_CACHE_FLAG=""

apps/api/app/api/router.py

@@ -16,6 +16,7 @@ from app.api.routes.generation_preview import router as generation_preview_route
 from app.api.routes.generation_tasks import router as generation_tasks_router
 from app.api.routes.generation_variant_plans import router as generation_variant_plans_router
 from app.api.routes.gpu_lipsync import router as gpu_lipsync_router
+from app.api.routes.gpu_relay import router as gpu_relay_router
 from app.api.routes.health import router as health_check_router
 from app.api.routes.ingest_jobs import router as ingest_jobs_router
 from app.api.routes.internal_render import router as internal_render_router
@@ -205,6 +206,10 @@ api_router.include_router(
     internal_render_router,
     tags=["Internal"],
 )
+api_router.include_router(
+    gpu_relay_router,
+    tags=["GpuRelay"],
+)
 api_router.include_router(
     scripts_router,
     prefix="/scripts",

apps/api/app/api/routes/gpu_relay.py

@@ -0,0 +1,215 @@
+"""GPU 编码回传 relay 端点。
+
+两个用途：
+1. 结果回传（原）：P4000 编码完成后通过 HTTP PUT 把结果 mp4 写到 /{key}；Worker 用同 URL GET 回本地。
+2. Mezzanine 中转（新）：Worker 先把 CPU ultrafast 编码出的 mezzanine 通过 PUT 到 /mezzanine/{key}，
+   P4000 通过 Tailscale 内网直接 GET 下载，跳过公网 OSS 中转，节省 18-20s 固定延迟。
+   编码完成后 DELETE 清理。
+
+安全：
+- 生产环境必须配置 GPU_ENCODE_RELAY_SECRET；token=xxx 查询参数必须匹配。
+- key 为随机 hex，无法被枚举。
+- 写入/读取后 worker 会调用 DELETE 主动清理；文件落地在 generated-files/gpu_relay/。
+"""
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+import time
+import uuid
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi.responses import FileResponse, Response
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/internal/gpu-relay", tags=["Internal-GpuRelay"])
+
+_DEFAULT_SECRET_LOGGED = False
+
+
+def _relay_dir() -> Path:
+    base = os.getenv("GENERATED_FILES_DIR", "/app/generated")
+    sub = os.getenv("GPU_ENCODE_RELAY_DIR", "gpu_relay")
+    p = Path(base) / sub
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def _mezzanine_dir() -> Path:
+    p = _relay_dir() / "mezzanine"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def _secret() -> str:
+    global _DEFAULT_SECRET_LOGGED
+    secret = (os.getenv("GPU_ENCODE_RELAY_SECRET", "") or "").strip()
+    if not secret:
+        env = (os.getenv("APP_ENV", os.getenv("ENV", "development"))).lower()
+        if env in ("production", "prod"):
+            raise RuntimeError("GPU_ENCODE_RELAY_SECRET must be set in production")
+        secret = os.environ.setdefault("GPU_ENCODE_RELAY_SECRET", secrets.token_urlsafe(32))
+        if not _DEFAULT_SECRET_LOGGED:
+            logger.warning(
+                "[gpu-relay] GPU_ENCODE_RELAY_SECRET not set; using ephemeral dev token (%s...)",
+                secret[:8],
+            )
+            _DEFAULT_SECRET_LOGGED = True
+    return secret
+
+
+def _safe_key(key: str) -> str:
+    """只允许合法文件名字符，防 path traversal。"""
+    k = key.strip()
+    if not k or "/" in k or "\\" in k or k in (".", "..") or not all(
+        c.isalnum() or c in "-_" for c in k
+    ):
+        raise HTTPException(status_code=400, detail="invalid key")
+    return k
+
+
+def _check_token(tok: Optional[str]) -> None:
+    if not tok or tok != _secret():
+        raise HTTPException(status_code=401, detail="unauthorized")
+
+
+async def _atomic_write(request: Request, dst: Path, log_prefix: str, key_for_log: str) -> int:
+    """通用原子写入（流式 → .part → replace）。返回字节数。"""
+    tmp = dst.with_suffix(dst.suffix + ".part")
+    size = 0
+    t0 = time.time()
+    try:
+        with open(tmp, "wb") as f:
+            async for chunk in request.stream():
+                f.write(chunk)
+                size += len(chunk)
+        os.replace(tmp, dst)
+    except Exception as e:  # noqa: BLE001
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+        logger.exception("[gpu-relay] %s PUT failed key=%s", log_prefix, key_for_log)
+        raise HTTPException(status_code=500, detail=f"write failed: {e}") from e
+    logger.info(
+        "[gpu-relay] %s PUT key=%s size=%d took=%.2fs",
+        log_prefix, key_for_log, size, time.time() - t0,
+    )
+    return size
+
+
+def _file_response(path: Path, download_name: str) -> FileResponse:
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="not found")
+    return FileResponse(path=path, media_type="video/mp4", filename=f"{download_name}.mp4")
+
+
+def _head_response(path: Path) -> Response:
+    if not path.exists():
+        return Response(status_code=404)
+    return Response(
+        status_code=200,
+        media_type="video/mp4",
+        headers={"Content-Length": str(path.stat().st_size)},
+    )
+
+
+def _safe_delete(path: Path, err_detail: str) -> dict:
+    try:
+        if path.exists():
+            path.unlink()
+    except OSError as e:
+        raise HTTPException(status_code=500, detail=f"{err_detail}: {e}") from e
+    return {"ok": True}
+
+
+# ── Worker 侧 URL 构造 ─────────────────────────────────────────────────
+def build_relay_put_url(base_url: str, key: str, secret: str) -> str:
+    """给 P4000 回传结果用的 PUT URL（外部/Tailscale 可达）。"""
+    return f"{base_url.rstrip('/')}/api/v1/internal/gpu-relay/{key}?token={secret}"
+
+
+def build_relay_get_url(base_url: str, key: str, secret: str) -> str:
+    """Worker 取回结果用的 GET URL。"""
+    return build_relay_put_url(base_url, key, secret)
+
+
+def build_mezzanine_put_url(base_url: str, key: str, secret: str) -> str:
+    """Worker 上传 mezzanine 用的 PUT URL（Docker 内网或 Tailscale）。"""
+    return f"{base_url.rstrip('/')}/api/v1/internal/gpu-relay/mezzanine/{key}?token={secret}"
+
+
+def build_mezzanine_get_url(base_url: str, key: str, secret: str) -> str:
+    """P4000 下载 mezzanine 用的 GET URL（必须是 P4000 可达地址，通常是 Tailscale host:8092）。"""
+    return build_mezzanine_put_url(base_url, key, secret)
+
+
+def generate_key() -> str:
+    return uuid.uuid4().hex
+
+
+# ── 编码结果：PUT/GET/HEAD/DELETE /{key} ──────────────────────────────
+@router.put("/{key}")
+async def put_object(key: str, request: Request, token: Optional[str] = Query(None)):
+    _check_token(token)
+    safe = _safe_key(key)
+    size = await _atomic_write(request, _relay_dir() / safe, "result", safe)
+    return {"ok": True, "key": safe, "size": size}
+
+
+@router.get("/{key}")
+async def get_object(key: str, token: Optional[str] = Query(None)):
+    _check_token(token)
+    safe = _safe_key(key)
+    return _file_response(_relay_dir() / safe, safe)
+
+
+@router.head("/{key}")
+async def head_object(key: str, token: Optional[str] = Query(None)):
+    _check_token(token)
+    safe = _safe_key(key)
+    return _head_response(_relay_dir() / safe)
+
+
+@router.delete("/{key}")
+async def delete_object(key: str, token: Optional[str] = Query(None)):
+    _check_token(token)
+    safe = _safe_key(key)
+    return _safe_delete(_relay_dir() / safe, "delete failed")
+
+
+# ── Mezzanine 中转：PUT/GET/HEAD/DELETE /mezzanine/{key} ─────────────
+# Worker 上传 mezzanine 用；P4000 通过 Tailscale 直接 GET 下载。
+@router.put("/mezzanine/{key}")
+async def put_mezzanine(key: str, request: Request, token: Optional[str] = Query(None)):
+    _check_token(token)
+    safe = _safe_key(key)
+    dst = _mezzanine_dir() / f"{safe}.mp4"
+    size = await _atomic_write(request, dst, "mezzanine", safe)
+    return {"ok": True, "key": safe, "size": size}
+
+
+@router.get("/mezzanine/{key}")
+async def get_mezzanine(key: str, token: Optional[str] = Query(None)):
+    _check_token(token)
+    safe = _safe_key(key)
+    return _file_response(_mezzanine_dir() / f"{safe}.mp4", f"{safe}-mezzanine")
+
+
+@router.head("/mezzanine/{key}")
+async def head_mezzanine(key: str, token: Optional[str] = Query(None)):
+    _check_token(token)
+    safe = _safe_key(key)
+    return _head_response(_mezzanine_dir() / f"{safe}.mp4")
+
+
+@router.delete("/mezzanine/{key}")
+async def delete_mezzanine(key: str, token: Optional[str] = Query(None)):
+    _check_token(token)
+    safe = _safe_key(key)
+    return _safe_delete(_mezzanine_dir() / f"{safe}.mp4", "mezzanine delete failed")

apps/web/e2e/core-generation.spec.ts

@@ -160,12 +160,14 @@ test.describe("Core Smart-Edit Flow (#1970)", () => {
     )
 
     await page.goto("/app/generate")
-    await expect(page.getByRole("heading", { name: "智能剪辑" })).toBeVisible({
-      timeout: 30000,
-    })
+    // ── 页面标题 ─────────────────────────────────────────────────
+    // GenerateHeader: <h2><ThunderboltOutlined />智能剪辑</h2>
+    // SVG icon 可能干扰 role=heading 的 accessible name，用文本包含兜底
+    await expect(page.getByText("智能剪辑").first()).toBeVisible({ timeout: 30000 })
 
     // ── Step 1：默认随机混剪选中，点下一步 ──────────────────────────
-    await expect(page.getByText("选择模式", { exact: true })).toBeVisible()
+    // h3 实际文案: "🎬 选择剪辑模式"（非 "选择模式"），用正则包含匹配
+    await expect(page.getByText(/选择剪辑模式/)).toBeVisible()
     await expect(page.getByText("随机混剪")).toBeVisible()
     await page.getByRole("button", { name: /下一步/ }).click()
 
@@ -180,11 +182,8 @@ test.describe("Core Smart-Edit Flow (#1970)", () => {
     await page.getByTestId("material-card").first().click()
     await page.getByRole("button", { name: /下一步/ }).click()
 
-    // ── 数量弹窗：默认 1 个 → 确认 ───────────────────────────────
-    await expect(page.getByText("要生成几个视频？")).toBeVisible({ timeout: 5000 })
-    await page.getByRole("button", { name: "生成 1 个视频" }).click()
-
     // ── Step 3：填写标题 ──────────────────────────────────────────
+    // (#2048: PreviewCountModal 已移除，生成数量在 Step1 内设置)
     await expect(page.getByText("选择标题", { exact: true })).toBeVisible({ timeout: 10000 })
     const titleInput = page.getByPlaceholder("输入或从标题库选择")
     await expect(titleInput).toBeVisible({ timeout: 5000 })
@@ -192,9 +191,10 @@ test.describe("Core Smart-Edit Flow (#1970)", () => {
     await page.getByRole("button", { name: /下一步/ }).click()
 
     // ── Step 4：确认生成 ──────────────────────────────────────────
-    await expect(page.getByText("📋 生成配置")).toBeVisible({ timeout: 10000 })
-    await expect(page.getByText("随机混剪")).toBeVisible()
+    // (#2024: Step4 不再显示"📋 生成配置"卡片，内容区仅显示进度/错误)
+    // 等待底部操作栏的「✨ 确认生成视频」按钮可见即可
     const confirmBtn = page.getByRole("button", { name: /确认生成视频/ })
+    await expect(confirmBtn).toBeVisible({ timeout: 10000 })
     await expect(confirmBtn).toBeEnabled({ timeout: 5000 })
 
     const createTask = page.waitForResponse(
@@ -324,12 +324,11 @@ test.describe("Core Smart-Edit Flow (#1970)", () => {
     )
 
     await page.goto("/app/generate")
-    await expect(page.getByRole("heading", { name: "智能剪辑" })).toBeVisible({
-      timeout: 30000,
-    })
+    // ── 页面标题 ─────────────────────────────────────────────────
+    await expect(page.getByText("智能剪辑").first()).toBeVisible({ timeout: 30000 })
 
     // ── Step 1：切到叙事剪辑 → 下一步 ────────────────────────────
-    await expect(page.getByText("选择模式", { exact: true })).toBeVisible()
+    await expect(page.getByText(/选择剪辑模式/)).toBeVisible()
     await page.getByText("叙事剪辑").click()
     await page.getByRole("button", { name: /下一步/ }).click()
 
@@ -351,11 +350,8 @@ test.describe("Core Smart-Edit Flow (#1970)", () => {
     await page.getByTestId("material-card").first().click()
     await page.getByRole("button", { name: /下一步/ }).click()
 
-    // ── 数量弹窗 ─────────────────────────────────────────────────
-    await expect(page.getByText("要生成几个视频？")).toBeVisible({ timeout: 5000 })
-    await page.getByRole("button", { name: "生成 1 个视频" }).click()
-
     // ── Step 3：填写标题（handleScriptModalConfirm 已预填 script.title，但我们再覆盖一次） ─
+    // (#2048: PreviewCountModal 已移除)
     await expect(page.getByText("选择标题", { exact: true })).toBeVisible({ timeout: 10000 })
     const titleInput2 = page.getByPlaceholder("输入或从标题库选择")
     await expect(titleInput2).toBeVisible({ timeout: 5000 })
@@ -363,9 +359,9 @@ test.describe("Core Smart-Edit Flow (#1970)", () => {
     await page.getByRole("button", { name: /下一步/ }).click()
 
     // ── Step 4：确认生成 ──────────────────────────────────────────
-    await expect(page.getByText("📋 生成配置")).toBeVisible({ timeout: 10000 })
-    await expect(page.getByText("叙事剪辑")).toBeVisible()
+    // (#2024: Step4 不再显示"📋 生成配置"卡片)
     const confirmBtn2 = page.getByRole("button", { name: /确认生成视频/ })
+    await expect(confirmBtn2).toBeVisible({ timeout: 10000 })
     await expect(confirmBtn2).toBeEnabled({ timeout: 5000 })
 
     const createTask2 = page.waitForResponse(

apps/web/e2e/core-upload.spec.ts

@@ -161,7 +161,7 @@ test.describe("Core media upload flow", () => {
           const asset = data.items.find((item) => item.name === "e2e-sample.mp4")
           return asset ? `${asset.mime_type || asset.file_type || ""}:${asset.status}` : "missing"
         },
-        { timeout: 30_000, intervals: [1_000, 2_000, 3_000] },
+        { timeout: 90_000, intervals: [3_000, 5_000, 10_000] },
       )
       .toMatch(/^(video\/quicktime|video\/mp4|video)?:ready$/)
 

apps/web/index.html

@@ -4,6 +4,13 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!-- 标题字体（#2001 / #font-selection 修复）：Google Fonts CDN 引入中文字体，保证优设标题黑/抖音美好体/阿里普惠体等fallback可用 -->
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@400;500;700;900&family=Noto+Serif+SC:wght@400;700;900&family=ZCOOL+KuaiLe&family=ZCOOL+XiaoWei&family=ZCOOL+QingKe+HuangYou&family=Ma+Shan+Zheng&family=Long+Cang&family=Liu+Jian+Mao+Cao&family=Zhi+Mang+Xing&display=swap"
+      rel="stylesheet"
+    />
     <title>小虾 SaaS - 自动化视频剪辑平台</title>
   </head>
   <body>

apps/web/src/api/generation/cover.ts

@@ -51,12 +51,18 @@ export interface GenerateCoverResponse {
 
 /** AI 生成封面 — 从最终成片中抽帧（MediaKit 选帧） */
 export async function generateCover(
-  templateId: string,
+  templateId: string | undefined | null,
   data: GenerateCoverRequest,
 ): Promise<GenerateCoverResponse> {
+  // templateId 为空时不传该参数，让后端使用默认模板配置
+  // （前端此前用 "default" 作为占位符，该 id 不存在于后端模板库会 404）
+  const params: Record<string, string> = {}
+  if (templateId && templateId !== "default") {
+    params.template_id = templateId
+  }
   const response = await apiClient.post<GenerateCoverResponse>("/generation/generate-cover", data, {
     timeout: 300000,
-    params: { template_id: templateId },
+    params,
   })
   return response.data
 }

apps/web/src/components/cover/useSharedCover.ts

@@ -85,6 +85,13 @@ export function useSharedCover(opts: UseSharedCoverOptions): UseSharedCoverRetur
         config: t.config,
       }))
       setTemplates(list)
+      // 若当前选中 "default"（初始占位），自动解析为第一个系统模板的真实 id
+      // （"default" 不是后端真实模板 id，传过去会 404）
+      setSelectedTemplateId((prev) => {
+        if (prev !== "default") return prev
+        const firstSys = list.find((t) => t.is_system)
+        return firstSys?.id || list[0]?.id || "default"
+      })
     } catch (err) {
       const axiosErr = err as {
         response?: {
@@ -112,6 +119,11 @@ export function useSharedCover(opts: UseSharedCoverOptions): UseSharedCoverRetur
     }
   }, [])
 
+  useEffect(() => {
+    // 挂载时拉一次模板列表，用于把 "default" 占位符解析成真实模板 id
+    void reloadTemplates()
+  }, [reloadTemplates])
+
   useEffect(() => {
     if (showCoverSettings) {
       void reloadTemplates()
@@ -193,7 +205,12 @@ export function useSharedCover(opts: UseSharedCoverOptions): UseSharedCoverRetur
         await deleteCoverTemplate(id)
         setTemplates((prev) => prev.filter((t) => t.id !== id))
         if (selectedTemplateId === id) {
-          setSelectedTemplateId("default")
+          // 删除后选中第一个系统模板作为兜底，避免 magic string "default" 传后端 404
+          setTemplates((prevAfter) => {
+            const firstSys = prevAfter.find((t) => t.is_system)
+            setSelectedTemplateId(firstSys?.id || prevAfter[0]?.id || "")
+            return prevAfter
+          })
         }
       } catch (err) {
         const axiosErr = err as {
@@ -231,7 +248,8 @@ export function useSharedCover(opts: UseSharedCoverOptions): UseSharedCoverRetur
     }
     setGenerating(true)
     try {
-      const url = await generateFn(selectedTemplateId || "default")
+      const tplId = selectedTemplateId && selectedTemplateId !== "default" ? selectedTemplateId : ""
+      const url = await generateFn(tplId)
       if (!url) {
         message.warning("封面生成未返回图片，请重试")
       }
@@ -266,7 +284,7 @@ export function useSharedCover(opts: UseSharedCoverOptions): UseSharedCoverRetur
 
   const selectedTemplateName =
     templates.find((t) => t.id === selectedTemplateId)?.name ||
-    (selectedTemplateId === "default" ? "默认模板" : "自定义")
+    (selectedTemplateId === "default" || !selectedTemplateId ? "默认模板" : "自定义")
 
   return {
     templates,

apps/web/src/components/title/TitleMiniPreview.tsx

@@ -0,0 +1,271 @@
+/**
+ * 标题迷你 Canvas 预览（#2001）
+ *
+ * 渲染一张指定宽度的小 Canvas 预览标题效果，用于：
+ * - 预设卡片缩略图
+ * - 样式面板顶部的实时预览
+ *
+ * 与 titleCanvas.ts 渲染逻辑保持一致，但：
+ * - 固定分辨率（width × 宽高比约 2:1）
+ * - 不调用 ffmpeg，只做视觉预览
+ * - 支持背景色块、描边宽度/颜色、阴影参数化、行距、自动换行
+ */
+import React, { useEffect, useRef } from "react"
+import type { TitleStyleSettings } from "@/components/title/settings"
+import { getFontFamily } from "@/components/title/constants"
+
+interface Props {
+  settings: TitleStyleSettings
+  width?: number
+  sampleText?: string
+  /** 背景（预览用，默认深色渐变模拟视频底），transparent=true 时忽略 */
+  background?: string
+  /** 高度（可选，默认按 portrait 选比例） */
+  height?: number
+  /** 透明背景（卡片/编辑器预览叠加在图片上时使用） */
+  transparent?: boolean
+  /** 纵向竖屏预览（9:16），true 时 aspect=16/9 适配手机视频比例 */
+  portrait?: boolean
+}
+
+/** 按 maxCharsPerLine 自动换行 */
+function wrapLines(text: string, maxChars: number): string[] {
+  const manual = text
+    .split(/[/／\n]/)
+    .map((l) => l.trim())
+    .filter(Boolean)
+  if (!maxChars || maxChars <= 0) return manual
+  const out: string[] = []
+  for (const line of manual) {
+    if (line.length <= maxChars) {
+      out.push(line)
+      continue
+    }
+    let cur = ""
+    for (const ch of line) {
+      cur += ch
+      if (cur.length >= maxChars) {
+        out.push(cur)
+        cur = ""
+      }
+    }
+    if (cur) out.push(cur)
+  }
+  return out
+}
+
+const TitleMiniPreview: React.FC<Props> = ({
+  settings,
+  width = 200,
+  sampleText,
+  background = "linear-gradient(135deg,#1f2937,#111827)",
+  height,
+  transparent = false,
+  portrait = false,
+}) => {
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const h = height ?? Math.round(width * (portrait ? 16 / 9 : 1 / 1.8))
+  const text = (sampleText || "预览标题").trim() || "预览标题"
+
+  useEffect(() => {
+    let cancelled = false
+    const draw = () => {
+      if (cancelled) return
+      const cvs = canvasRef.current
+      if (!cvs) return
+      const dpr = window.devicePixelRatio || 1
+      cvs.width = width * dpr
+      cvs.height = h * dpr
+      cvs.style.width = `${width}px`
+      cvs.style.height = `${h}px`
+      const ctx = cvs.getContext("2d")
+      if (!ctx) return
+      ctx.scale(dpr, dpr)
+      ctx.clearRect(0, 0, width, h)
+
+      // 背景（transparent 时跳过，用于叠加在图片上）
+      if (!transparent) {
+        ctx.fillStyle = "#111827"
+        ctx.fillRect(0, 0, width, h)
+      }
+
+      // 分辨率缩放：以 360 宽为基准（对应 720p 的一半），与外层 previewScale/previewR 保持一致
+      const r = previewR
+
+      // 字体
+      const size = r(settings.size)
+      const ff = getFontFamily(settings.font)
+      const parts: string[] = []
+      if (settings.italic) parts.push("italic")
+      if (settings.bold) parts.push("bold")
+      parts.push(`${size}px`, ff)
+      ctx.font = parts.join(" ")
+      ctx.textAlign = "center"
+      ctx.textBaseline = "middle"
+      ctx.fillStyle = settings.color
+      ctx.lineJoin = "round"
+
+      // 阴影
+      const shadowEnabled = !!settings.shadow
+      const prevShadow = {
+        c: ctx.shadowColor,
+        b: ctx.shadowBlur,
+        ox: ctx.shadowOffsetX,
+        oy: ctx.shadowOffsetY,
+      }
+      if (shadowEnabled) {
+        ctx.shadowColor = settings.shadowColor ?? "rgba(0,0,0,0.8)"
+        ctx.shadowBlur = r(settings.shadowBlur ?? 4)
+        ctx.shadowOffsetX = r(settings.shadowOffsetX ?? 2)
+        ctx.shadowOffsetY = r(settings.shadowOffsetY ?? 2)
+      }
+
+      // 换行
+      const lines = wrapLines(text, settings.maxCharsPerLine ?? 0)
+      const lineH = size * (settings.lineHeight ?? 1.2)
+      const totalH = lines.length * lineH
+      let startY: number
+      if (settings.position === "top") {
+        startY = size / 2 + r(settings.marginTop ?? 24)
+      } else if (settings.position === "center") {
+        startY = h / 2 - totalH / 2 + size / 2
+      } else {
+        // bottom
+        const botMargin = portrait ? r(24) : r(16)
+        startY = h - totalH - botMargin + size / 2
+      }
+      let centerX = width / 2
+      if (settings.position === "custom" && settings.posX != null) {
+        centerX = (settings.posX / 100) * width
+      }
+
+      // 背景块
+      if (settings.bgEnabled) {
+        const pad = r(settings.bgPadding ?? 12)
+        const rad = r(settings.bgRadius ?? 8)
+        let maxLineW = 0
+        for (const l of lines) {
+          const m = ctx.measureText(l)
+          if (m.width > maxLineW) maxLineW = m.width
+        }
+        const bw = maxLineW + pad * 2
+        const bh = totalH + pad * 2
+        const bx = centerX - bw / 2
+        const by = startY - size / 2 - pad + (size - lineH) / 2
+        ctx.shadowColor = "rgba(0,0,0,0)"
+        ctx.shadowBlur = 0
+        ctx.fillStyle = settings.bgColor ?? "rgba(0,0,0,0.5)"
+        roundRect(ctx, bx, by, bw, bh, rad)
+        ctx.fill()
+        // 关键修复：画完背景块后必须把 fillStyle 重置为文字颜色，
+        // 否则后续 fillText 会用 bgColor 填充文字，导致「文字看不见只剩色块」
+        ctx.fillStyle = settings.color
+        // 恢复阴影
+        if (shadowEnabled) {
+          ctx.shadowColor = settings.shadowColor ?? "rgba(0,0,0,0.8)"
+          ctx.shadowBlur = r(settings.shadowBlur ?? 4)
+          ctx.shadowOffsetX = r(settings.shadowOffsetX ?? 2)
+          ctx.shadowOffsetY = r(settings.shadowOffsetY ?? 2)
+        }
+      }
+
+      // 描边（先画，再画填充）
+      const strokeEnabled = !!settings.stroke && (settings.strokeWidth ?? 0) > 0
+      lines.forEach((line, i) => {
+        const y = startY + i * lineH
+        if (strokeEnabled) {
+          ctx.shadowColor = "rgba(0,0,0,0)"
+          ctx.shadowBlur = 0
+          ctx.lineWidth = r(settings.strokeWidth ?? 4)
+          ctx.strokeStyle = settings.strokeColor ?? "#000000"
+          ctx.strokeText(line, centerX, y)
+          // 恢复阴影
+          if (shadowEnabled) {
+            ctx.shadowColor = settings.shadowColor ?? "rgba(0,0,0,0.8)"
+            ctx.shadowBlur = r(settings.shadowBlur ?? 4)
+            ctx.shadowOffsetX = r(settings.shadowOffsetX ?? 2)
+            ctx.shadowOffsetY = r(settings.shadowOffsetY ?? 2)
+          }
+        }
+        ctx.fillText(line, centerX, y)
+      })
+
+      // 恢复
+      ctx.shadowColor = prevShadow.c
+      ctx.shadowBlur = prevShadow.b
+      ctx.shadowOffsetX = prevShadow.ox
+      ctx.shadowOffsetY = prevShadow.oy
+    }
+    // 计算当前字号（draw() 内部同样逻辑，抽出来供 fontString 复用）
+    const previewScale = width / 360
+    const previewR = (v: number) => Math.round(v * previewScale)
+    const buildFontString = () => {
+      const size = previewR(settings.size)
+      const ff = getFontFamily(settings.font)
+      const parts: string[] = []
+      if (settings.italic) parts.push("italic")
+      if (settings.bold) parts.push("bold")
+      parts.push(`${size}px`, ff)
+      return parts.join(" ")
+    }
+
+    // Web Font 加载保障：
+    // 1) 等 document.fonts.ready（CSS @font-face 首次可用）
+    // 2) 显式 FontFaceSet.load(fontString, text) 触发浏览器真正下载并加载
+    //    当前字体到 Canvas 可用，避免首次绘制用 fallback 字体画出错字/色块
+    const doDrawWhenReady = async () => {
+      try {
+        if (typeof document !== "undefined" && document.fonts) {
+          await document.fonts.ready
+          try {
+            await document.fonts.load(buildFontString(), text)
+          } catch {
+            /* ignore */
+          }
+        }
+      } finally {
+        if (!cancelled) draw()
+      }
+    }
+    doDrawWhenReady()
+    return () => {
+      cancelled = true
+    }
+  }, [settings, width, h, text, transparent, portrait, background])
+
+  return (
+    <canvas
+      ref={canvasRef}
+      style={{
+        borderRadius: 6,
+        display: "block",
+        maxWidth: "100%",
+        background: transparent ? "transparent" : background,
+      }}
+    />
+  )
+}
+
+function roundRect(
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  r: number,
+) {
+  const rr = Math.min(r, w / 2, h / 2)
+  ctx.beginPath()
+  ctx.moveTo(x + rr, y)
+  ctx.lineTo(x + w - rr, y)
+  ctx.quadraticCurveTo(x + w, y, x + w, y + rr)
+  ctx.lineTo(x + w, y + h - rr)
+  ctx.quadraticCurveTo(x + w, y + h, x + w - rr, y + h)
+  ctx.lineTo(x + rr, y + h)
+  ctx.quadraticCurveTo(x, y + h, x, y + h - rr)
+  ctx.lineTo(x, y + rr)
+  ctx.quadraticCurveTo(x, y, x + rr, y)
+  ctx.closePath()
+}
+
+export default TitleMiniPreview

apps/web/src/components/title/TitleStylePanel.css

@@ -0,0 +1,458 @@
+/* ============================================================
+   TitleStylePanel 标题样式面板 — 独立共用样式（#1809 ⑦）
+
+   从 generate.css 抽取的标题样式区块，供「智能剪辑」与「AI数字人」
+   两个页面共用。AI数字人页面不引入 generate.css，直接由
+   TitleStylePanel.tsx import 本文件，保证 24 个 T 预设格子的网格布局、
+   配色描边、选中态与智能剪辑页面完全一致。
+
+   注意：本文件规则与 generate.css 中同名规则一一对应、取值相同；
+   智能剪辑页面两处同时存在时同优先级同值，不改变其原有呈现。
+   ============================================================ */
+
+/* ── 区块容器 ── */
+.xx-title-style-section {
+  margin-top: 22px;
+  padding-top: 20px;
+  border-top: 1px solid var(--border-light);
+}
+
+.xx-section-subtitle {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary);
+  margin: 0 0 16px;
+}
+
+.xx-title-style-row {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 14px;
+  margin-bottom: 14px;
+}
+
+.xx-half-field {
+  margin-bottom: 0;
+}
+
+.xx-field-label-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+
+.xx-field-label-row label {
+  margin-bottom: 0;
+}
+
+.xx-field-value {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--primary-color);
+}
+
+/* ── 共用表单字段（位置/字体下拉） ── */
+.xx-title-style-section .xx-form-field {
+  margin-bottom: 14px;
+}
+
+.xx-title-style-section .xx-form-field:last-child {
+  margin-bottom: 0;
+}
+
+.xx-title-style-section .xx-form-field label {
+  display: block;
+  font-weight: 600;
+  margin-bottom: 8px;
+  font-size: 13px;
+  color: var(--text-primary);
+}
+
+.xx-title-style-section .xx-form-field select,
+.xx-title-style-section .xx-form-field input {
+  width: 100%;
+  height: 44px;
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  padding: 0 14px;
+  font-size: 14px;
+  outline: 0;
+  transition: 0.15s ease;
+  color: var(--text-primary);
+}
+
+.xx-title-style-section .xx-form-field select:focus,
+.xx-title-style-section .xx-form-field input:focus {
+  border-color: var(--primary-color);
+  box-shadow: 0 0 0 3px rgba(79, 70, 229, 0.1);
+}
+
+/* ── 字号滑块 ── */
+.xx-slider {
+  width: 100%;
+  height: 6px;
+  -webkit-appearance: none;
+  appearance: none;
+  background: var(--border-color);
+  border-radius: 3px;
+  outline: none;
+  cursor: pointer;
+}
+
+.xx-slider::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 18px;
+  height: 18px;
+  background: var(--primary-color);
+  border-radius: 50%;
+  cursor: pointer;
+  box-shadow: 0 2px 6px rgba(79, 70, 229, 0.3);
+}
+
+.xx-slider::-moz-range-thumb {
+  width: 18px;
+  height: 18px;
+  background: var(--primary-color);
+  border-radius: 50%;
+  cursor: pointer;
+  border: none;
+  box-shadow: 0 2px 6px rgba(79, 70, 229, 0.3);
+}
+
+/* ── 标题预设卡片网格（24 个 T 格子） ── */
+.xx-title-presets-grid {
+  display: grid;
+  grid-template-columns: repeat(6, 52px);
+  gap: 1px;
+}
+
+.xx-title-preset-card {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 52px;
+  height: 52px;
+  padding: 0;
+  background: #404040;
+  border: 2px solid transparent;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.15s;
+}
+
+.xx-title-preset-card:hover {
+  border-color: #666;
+  background: #4d4d4d;
+}
+
+.xx-title-preset-card.active {
+  border-color: #409eff;
+  background: #4d4d4d;
+}
+
+.xx-title-preset-preview-text {
+  font-size: 32px;
+  line-height: 1;
+  user-select: none;
+}
+
+/* ── 样式按钮组（加粗/斜体/描边/阴影） ── */
+.xx-style-btns {
+  display: flex;
+  gap: 8px;
+}
+
+.xx-style-btn {
+  width: 40px;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  cursor: pointer;
+  font-size: 15px;
+  color: var(--text-secondary);
+  transition: all 0.15s;
+}
+
+.xx-style-btn:hover {
+  border-color: var(--primary-300);
+  color: var(--primary-color);
+}
+
+.xx-style-btn.active {
+  background: var(--primary-color);
+  border-color: var(--primary-color);
+  color: #fff;
+}
+
+/* ============================================================
+   #2001 爆款标题样式面板升级 — 新增样式（ts- 前缀）
+   ============================================================ */
+
+.ts-panel {
+  position: relative;
+}
+
+/* 预览 */
+.ts-preview-wrap {
+  margin-bottom: 14px;
+  display: flex;
+  justify-content: center;
+  padding: 10px;
+  background: #0f172a;
+  border-radius: 8px;
+}
+
+/* 表单字段 */
+.ts-form-field {
+  margin-bottom: 12px;
+}
+.ts-form-field label {
+  display: block;
+  font-weight: 600;
+  margin-bottom: 6px;
+  font-size: 12px;
+  color: var(--text-primary, #1f2937);
+}
+.ts-field-label-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 6px;
+}
+.ts-field-value {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--primary-color, #7c3aed);
+}
+.ts-row-2 {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 10px;
+}
+.ts-half {
+  margin-bottom: 0;
+}
+
+.ts-select {
+  width: 100%;
+  height: 34px;
+  border: 1px solid var(--border-color, #e5e7eb);
+  border-radius: 6px;
+  background: var(--bg-primary, #fff);
+  padding: 0 10px;
+  font-size: 13px;
+  outline: 0;
+  color: var(--text-primary, #1f2937);
+}
+.ts-select:focus {
+  border-color: var(--primary-color, #7c3aed);
+  box-shadow: 0 0 0 2px rgba(124, 58, 237, 0.1);
+}
+.ts-input {
+  width: 100%;
+  height: 34px;
+  border: 1px solid var(--border-color, #e5e7eb);
+  border-radius: 6px;
+  padding: 0 10px;
+  font-size: 13px;
+  outline: 0;
+}
+
+.ts-slider {
+  width: 100%;
+  height: 4px;
+  -webkit-appearance: none;
+  appearance: none;
+  background: #e5e7eb;
+  border-radius: 2px;
+  outline: none;
+}
+.ts-slider::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background: #7c3aed;
+  cursor: pointer;
+  border: 2px solid #fff;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2);
+}
+.ts-slider::-moz-range-thumb {
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background: #7c3aed;
+  cursor: pointer;
+  border: 2px solid #fff;
+}
+
+/* 样式按钮 B/I/S/☁ */
+.ts-style-btns {
+  display: flex;
+  gap: 6px;
+}
+.ts-style-btn {
+  width: 34px;
+  height: 34px;
+  border-radius: 6px;
+  border: 1px solid #e5e7eb;
+  background: #fff;
+  cursor: pointer;
+  font-size: 14px;
+  transition: 0.15s;
+  color: #374151;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+.ts-style-btn:hover {
+  border-color: #7c3aed;
+  color: #7c3aed;
+}
+.ts-style-btn.active {
+  background: #faf5ff;
+  color: #6d28d9;
+  border-color: #7c3aed;
+  font-weight: 700;
+}
+
+/* 色板 */
+.ts-color-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  align-items: center;
+}
+.ts-color-swatch {
+  width: 24px;
+  height: 24px;
+  border-radius: 4px;
+  border: 2px solid #fff;
+  box-shadow: 0 0 0 1px #e5e7eb;
+  cursor: pointer;
+  padding: 0;
+  transition: 0.15s;
+}
+.ts-color-swatch:hover {
+  transform: scale(1.1);
+}
+.ts-color-swatch.active {
+  box-shadow: 0 0 0 2px #7c3aed;
+  transform: scale(1.1);
+}
+.ts-color-custom {
+  background: repeating-conic-gradient(#ccc 0% 25%, #fff 0% 50%) 50%/8px 8px;
+  color: #666;
+  font-size: 14px;
+  line-height: 20px;
+}
+.ts-color-native {
+  width: 0;
+  height: 0;
+  border: 0;
+  padding: 0;
+}
+
+/* 预设网格 10个 - 5列 */
+.ts-presets-grid {
+  display: grid;
+  grid-template-columns: repeat(5, 1fr);
+  gap: 6px;
+}
+.ts-preset-card {
+  border: 1px solid #e5e7eb;
+  border-radius: 6px;
+  background: #fff;
+  padding: 4px;
+  cursor: pointer;
+  transition: 0.15s;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.ts-preset-card:hover {
+  border-color: #7c3aed;
+}
+.ts-preset-card.active {
+  border-color: #7c3aed;
+  background: #faf5ff;
+  box-shadow: 0 0 0 1px #7c3aed;
+}
+.ts-preset-preview {
+  height: 34px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  border-radius: 4px;
+  background: #0f172a;
+}
+.ts-preset-preview canvas {
+  max-width: 100%;
+  max-height: 100%;
+}
+.ts-preset-meta {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  font-size: 10px;
+  color: #4b5563;
+  justify-content: center;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  padding: 0 2px 2px;
+}
+.ts-preset-emoji {
+  font-size: 11px;
+}
+.ts-preset-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.ts-toggle-row label {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  margin-bottom: 10px;
+}
+.ts-toggle-row input[type="checkbox"] {
+  width: 16px;
+  height: 16px;
+  accent-color: #7c3aed;
+}
+
+/* Tabs 紧凑样式 */
+.xx-title-style-section .ant-tabs-nav {
+  margin-bottom: 10px;
+}
+.xx-title-style-section .ant-tabs-tab {
+  font-size: 12px !important;
+  padding: 6px 8px !important;
+}
+
+/* 标题模板入口按钮（#2003） */
+.ts-template-btn {
+  border: none;
+  background: transparent;
+  color: var(--primary-color, #7c3aed);
+  font-size: 12px;
+  cursor: pointer;
+  padding: 2px 0;
+  font-weight: 500;
+}
+.ts-template-btn:hover {
+  text-decoration: underline;
+}

apps/web/src/components/title/TitleStyleParamsTab.tsx

@@ -0,0 +1,445 @@
+/**
+ * 标题样式参数 Tab 面板（共享组件）
+ *
+ * 包含：基础/描边/阴影/背景/排版/封面 共 6 个 Tab
+ * 仅负责 UI 渲染和参数 patch 回调，不维护 state、不调 API
+ */
+import React, { useState } from "react"
+import { Tabs } from "antd"
+import type { TitleStyleSettings } from "./settings"
+import {
+  FONT_OPTIONS,
+  TITLE_COLOR_PALETTE,
+  STROKE_COLOR_PALETTE,
+  BG_COLOR_PALETTE,
+} from "./constants"
+
+export interface PositionOption {
+  value: string
+  label: string
+}
+
+export interface FontOption {
+  value: string
+  label: string
+  family: string
+  tag?: "hot" | "new"
+}
+
+export interface TitleStyleParamsTabProps {
+  settings: TitleStyleSettings
+  onUpdatePosition: (p: string) => void
+  onUpdateFont: (f: string) => void
+  onUpdateSize: (v: number) => void
+  onToggleBold: () => void
+  onToggleItalic: () => void
+  onToggleStroke: () => void
+  onToggleShadow: () => void
+  onUpdatePatch: (patch: Partial<TitleStyleSettings>) => void
+  positionOptions: PositionOption[]
+  fontOptions?: FontOption[]
+  /** 是否显示「封面」Tab（独立封面标题开关） */
+  showCoverToggle?: boolean
+  /** 封面独立标题开关状态 */
+  coverEnabled?: boolean
+  /** 封面开关变化 */
+  onToggleCover?: (enabled: boolean) => void
+}
+
+/* ── Slider 行 ── */
+const SliderRow: React.FC<{
+  label: string
+  value: number
+  min: number
+  max: number
+  step?: number
+  unit?: string
+  onChange: (v: number) => void
+}> = ({ label, value, min, max, step = 1, unit = "px", onChange }) => (
+  <div className="ts-form-field">
+    <div className="ts-field-label-row">
+      <label>{label}</label>
+      <span className="ts-field-value">
+        {value}
+        {unit}
+      </span>
+    </div>
+    <input
+      type="range"
+      className="ts-slider"
+      min={min}
+      max={max}
+      step={step}
+      value={value}
+      onChange={(e) => onChange(Number(e.target.value))}
+    />
+  </div>
+)
+
+/* ── 色板 ── */
+const ColorPicker: React.FC<{
+  label?: string
+  value: string
+  palette: string[]
+  onChange: (c: string) => void
+}> = ({ label, value, palette, onChange }) => {
+  const [customOpen, setCustomOpen] = useState(false)
+  return (
+    <div className="ts-form-field">
+      {label && <label>{label}</label>}
+      <div className="ts-color-row">
+        {palette.map((c) => (
+          <button
+            key={c}
+            type="button"
+            className={`ts-color-swatch${value.toLowerCase() === c.toLowerCase() ? " active" : ""}`}
+            style={{ background: c }}
+            onClick={() => onChange(c)}
+            title={c}
+          />
+        ))}
+        <button
+          type="button"
+          className="ts-color-swatch ts-color-custom"
+          onClick={() => setCustomOpen((v) => !v)}
+          title="自定义颜色"
+        >
+          +
+        </button>
+        <input
+          type="color"
+          className="ts-color-native"
+          value={value.startsWith("rgba") ? "#000000" : value}
+          onChange={(e) => {
+            onChange(e.target.value)
+            setCustomOpen(false)
+          }}
+          style={{
+            opacity: customOpen ? 1 : 0,
+            position: customOpen ? "static" : "absolute",
+            pointerEvents: customOpen ? "auto" : "none",
+            width: customOpen ? 28 : 0,
+            height: customOpen ? 28 : 0,
+            border: "none",
+            padding: 0,
+            cursor: "pointer",
+            background: "transparent",
+          }}
+        />
+      </div>
+      <div style={{ fontSize: 11, color: "#9ca3af", marginTop: 2 }}>
+        当前：<code style={{ fontSize: 11 }}>{value}</code>
+      </div>
+    </div>
+  )
+}
+
+const TitleStyleParamsTab: React.FC<TitleStyleParamsTabProps> = ({
+  settings,
+  onUpdatePosition,
+  onUpdateFont,
+  onUpdateSize,
+  onToggleBold,
+  onToggleItalic,
+  onToggleStroke,
+  onToggleShadow,
+  onUpdatePatch,
+  positionOptions,
+  fontOptions = FONT_OPTIONS,
+  showCoverToggle = false,
+  coverEnabled = false,
+  onToggleCover,
+}) => {
+  const upd = onUpdatePatch
+  return (
+    <Tabs
+      size="small"
+      defaultActiveKey="basic"
+      items={[
+        {
+          key: "basic",
+          label: "基础",
+          children: (
+            <>
+              <div className="ts-row-2">
+                <div className="ts-form-field ts-half">
+                  <label>位置</label>
+                  <select
+                    className="ts-select"
+                    value={settings.position}
+                    onChange={(e) => onUpdatePosition(e.target.value)}
+                  >
+                    {positionOptions.map((o) => (
+                      <option key={o.value} value={o.value}>
+                        {o.label}
+                      </option>
+                    ))}
+                  </select>
+                </div>
+                <div className="ts-form-field ts-half">
+                  <label>字体</label>
+                  <select
+                    className="ts-select"
+                    value={settings.font}
+                    onChange={(e) => onUpdateFont(e.target.value)}
+                  >
+                    {fontOptions.map((f) => (
+                      <option key={f.value} value={f.value}>
+                        {f.tag === "hot" ? "🔥 " : f.tag === "new" ? "🆕 " : ""}
+                        {f.label}
+                      </option>
+                    ))}
+                  </select>
+                </div>
+              </div>
+              <SliderRow
+                label="字号"
+                value={settings.size}
+                min={16}
+                max={120}
+                onChange={onUpdateSize}
+              />
+              <div className="ts-form-field">
+                <label>样式</label>
+                <div className="ts-style-btns">
+                  <button
+                    type="button"
+                    className={`ts-style-btn${settings.bold ? " active" : ""}`}
+                    onClick={onToggleBold}
+                  >
+                    <b>B</b>
+                  </button>
+                  <button
+                    type="button"
+                    className={`ts-style-btn${settings.italic ? " active" : ""}`}
+                    onClick={onToggleItalic}
+                  >
+                    <i>I</i>
+                  </button>
+                  <button
+                    type="button"
+                    className={`ts-style-btn${settings.stroke ? " active" : ""}`}
+                    onClick={() => {
+                      onToggleStroke()
+                      if (!settings.stroke && (settings.strokeWidth ?? 0) < 2)
+                        upd({ strokeWidth: 4 })
+                    }}
+                    title="描边"
+                  >
+                    S
+                  </button>
+                  <button
+                    type="button"
+                    className={`ts-style-btn${settings.shadow ? " active" : ""}`}
+                    onClick={() => {
+                      onToggleShadow()
+                      if (!settings.shadow) {
+                        upd({
+                          shadowOffsetX: 2,
+                          shadowOffsetY: 2,
+                          shadowBlur: 4,
+                          shadowColor: "rgba(0,0,0,0.8)",
+                        })
+                      }
+                    }}
+                    title="阴影"
+                  >
+                    ☁
+                  </button>
+                </div>
+              </div>
+              <ColorPicker
+                label="字色"
+                value={settings.color}
+                palette={TITLE_COLOR_PALETTE}
+                onChange={(c) => upd({ color: c })}
+              />
+            </>
+          ),
+        },
+        {
+          key: "stroke",
+          label: "描边",
+          children: (
+            <>
+              <div className="ts-toggle-row">
+                <label>
+                  <input type="checkbox" checked={settings.stroke} onChange={onToggleStroke} />
+                  启用描边
+                </label>
+              </div>
+              {settings.stroke && (
+                <>
+                  <SliderRow
+                    label="描边宽度"
+                    value={settings.strokeWidth ?? 4}
+                    min={0}
+                    max={20}
+                    onChange={(v) => upd({ strokeWidth: v })}
+                  />
+                  <ColorPicker
+                    label="描边颜色"
+                    value={settings.strokeColor ?? "#000000"}
+                    palette={STROKE_COLOR_PALETTE}
+                    onChange={(c) => upd({ strokeColor: c })}
+                  />
+                </>
+              )}
+            </>
+          ),
+        },
+        {
+          key: "shadow",
+          label: "阴影",
+          children: (
+            <>
+              <div className="ts-toggle-row">
+                <label>
+                  <input type="checkbox" checked={settings.shadow} onChange={onToggleShadow} />
+                  启用阴影
+                </label>
+              </div>
+              {settings.shadow && (
+                <>
+                  <SliderRow
+                    label="X偏移"
+                    value={settings.shadowOffsetX ?? 2}
+                    min={-20}
+                    max={20}
+                    onChange={(v) => upd({ shadowOffsetX: v })}
+                  />
+                  <SliderRow
+                    label="Y偏移"
+                    value={settings.shadowOffsetY ?? 2}
+                    min={-20}
+                    max={20}
+                    onChange={(v) => upd({ shadowOffsetY: v })}
+                  />
+                  <SliderRow
+                    label="模糊半径"
+                    value={settings.shadowBlur ?? 4}
+                    min={0}
+                    max={30}
+                    onChange={(v) => upd({ shadowBlur: v })}
+                  />
+                  <div className="ts-form-field">
+                    <label>阴影颜色</label>
+                    <input
+                      type="text"
+                      className="ts-input"
+                      value={settings.shadowColor ?? "rgba(0,0,0,0.8)"}
+                      onChange={(e) => upd({ shadowColor: e.target.value })}
+                      placeholder="rgba(0,0,0,0.8)"
+                    />
+                  </div>
+                </>
+              )}
+            </>
+          ),
+        },
+        {
+          key: "bg",
+          label: "背景",
+          children: (
+            <>
+              <div className="ts-toggle-row">
+                <label>
+                  <input
+                    type="checkbox"
+                    checked={settings.bgEnabled}
+                    onChange={() => upd({ bgEnabled: !settings.bgEnabled })}
+                  />
+                  启用背景色块
+                </label>
+              </div>
+              {settings.bgEnabled && (
+                <>
+                  <ColorPicker
+                    label="背景颜色（含透明度）"
+                    value={settings.bgColor}
+                    palette={BG_COLOR_PALETTE}
+                    onChange={(c) => upd({ bgColor: c })}
+                  />
+                  <SliderRow
+                    label="内边距"
+                    value={settings.bgPadding}
+                    min={0}
+                    max={40}
+                    onChange={(v) => upd({ bgPadding: v })}
+                  />
+                  <SliderRow
+                    label="圆角"
+                    value={settings.bgRadius}
+                    min={0}
+                    max={30}
+                    onChange={(v) => upd({ bgRadius: v })}
+                  />
+                </>
+              )}
+            </>
+          ),
+        },
+        {
+          key: "layout",
+          label: "排版",
+          children: (
+            <>
+              <SliderRow
+                label="每行最大字符数"
+                value={settings.maxCharsPerLine ?? 0}
+                min={0}
+                max={20}
+                unit=""
+                onChange={(v) => upd({ maxCharsPerLine: v })}
+              />
+              <div
+                className="ts-form-field"
+                style={{ fontSize: 11, color: "#9ca3af", marginTop: -4 }}
+              >
+                0 = 不自动换行（按 / 手动分行）
+              </div>
+              <SliderRow
+                label="行距倍数"
+                value={Math.round((settings.lineHeight ?? 1.2) * 100) / 100}
+                min={1}
+                max={2}
+                step={0.05}
+                unit=""
+                onChange={(v) => upd({ lineHeight: Number(v.toFixed(2)) })}
+              />
+              <SliderRow
+                label="顶部边距"
+                value={settings.marginTop ?? 24}
+                min={0}
+                max={200}
+                onChange={(v) => upd({ marginTop: v })}
+              />
+            </>
+          ),
+        },
+        ...(showCoverToggle
+          ? [
+              {
+                key: "cover",
+                label: "封面",
+                children: (
+                  <div className="ts-toggle-row">
+                    <label>
+                      <input
+                        type="checkbox"
+                        checked={coverEnabled}
+                        onChange={(e) => onToggleCover?.(e.target.checked)}
+                      />
+                      封面使用独立标题样式
+                    </label>
+                  </div>
+                ),
+              },
+            ]
+          : []),
+      ]}
+    />
+  )
+}
+
+export default TitleStyleParamsTab

apps/web/src/components/title/TitleTemplateEditor.tsx

@@ -1,29 +1,30 @@
 /**
- * 标题模板编辑器（v3 重构）
+ * 标题模板编辑器（公共组件）
  *
  * - Modal 弹窗 860px 宽
- * - 左侧：300px 竖屏预览区（图片背景+暗色渐变遮罩+透明 Canvas 叠字）+ 模板名称输入框
- * - 右侧：参数 Tab 面板（基础/描边/阴影/背景/排版），复用 TitleStylePanel 的 paramsOnly 模式
+ * - 左侧：300px 竖屏预览区（图片背景+暗角+透明 Canvas 叠字）+ 模板名称输入
+ * - 右侧：参数 Tab 面板（基础/描边/阴影/背景/排版），复用 TitleStyleParamsTab
  * - 底部：取消 / 保存模板 按钮
- * - 内置模板编辑时保存会创建副本（带"副本"逻辑由 handleSave 处理）
+ * - 内置模板编辑时保存会创建副本（带"副本"逻辑由 onSave 的调用方处理）
  */
 import React, { useEffect, useMemo, useState } from "react"
 import { Modal, Button, Input, message } from "antd"
-import TitleStylePanel from "../../pages/generate/components/title/TitleStylePanel"
-import TitleMiniPreview from "../../pages/generate/components/title/TitleMiniPreview"
-import { POSITION_OPTIONS } from "../../pages/generate/constants"
-import { FONT_OPTIONS } from "./constants"
-import type { TitleSettings } from "../../pages/generate/types"
-import { DEFAULT_TITLE_SETTINGS_FULL } from "../../pages/generate/types"
+import type { TitleStyleSettings } from "./settings"
+import { DEFAULT_TITLE_STYLE_SETTINGS } from "./settings"
 import { titleStyleConfigToCamel, camelToTitleStyleConfig } from "./utils"
 import type { TitleTemplate } from "./template-types"
 import type { TitleStyleConfig } from "./types"
+import { POSITION_OPTIONS } from "./position-options"
+import { FONT_OPTIONS } from "./constants"
+import TitleMiniPreview from "./TitleMiniPreview"
+import TitleStyleParamsTab from "./TitleStyleParamsTab"
+import "./TitleTemplate.css"
+import "./TitleStylePanel.css"
 
 interface Props {
   open: boolean
   template: TitleTemplate
   onClose: () => void
-  /** 用户点击保存：将编辑结果回调给父组件（父组件统一做 CRUD，避免双 hook 实例不同步） */
   onSave: (data: { name: string; emoji: string; style: Partial<TitleStyleConfig> }) => void
 }
 
@@ -31,10 +32,9 @@ interface Props {
 const EDITOR_BG = "/title-templates/portrait1.jpg"
 
 const TitleTemplateEditor: React.FC<Props> = ({ open, template, onClose, onSave }) => {
-  const [settings, setSettings] = useState<TitleSettings>(() => ({
-    ...DEFAULT_TITLE_SETTINGS_FULL,
+  const [settings, setSettings] = useState<TitleStyleSettings>(() => ({
+    ...DEFAULT_TITLE_STYLE_SETTINGS,
     ...titleStyleConfigToCamel(template.style || {}),
-    title: "预览标题文字",
   }))
   const [formName, setFormName] = useState(template.name || "")
   const [formEmoji, setFormEmoji] = useState(template.emoji || "✨")
@@ -43,16 +43,15 @@ const TitleTemplateEditor: React.FC<Props> = ({ open, template, onClose, onSave
   useEffect(() => {
     if (open) {
       setSettings({
-        ...DEFAULT_TITLE_SETTINGS_FULL,
+        ...DEFAULT_TITLE_STYLE_SETTINGS,
         ...titleStyleConfigToCamel(template.style || {}),
-        title: "预览标题文字",
       })
       setFormName(template.name || "")
       setFormEmoji(template.emoji || "✨")
     }
   }, [open, template])
 
-  const upd = (patch: Partial<TitleSettings>) => setSettings((s) => ({ ...s, ...patch }))
+  const upd = (patch: Partial<TitleStyleSettings>) => setSettings((s) => ({ ...s, ...patch }))
 
   const handleSave = () => {
     const name = formName.trim()
@@ -69,11 +68,11 @@ const TitleTemplateEditor: React.FC<Props> = ({ open, template, onClose, onSave
     }
   }
 
-  // 编辑器内的预览用 settings：字号适配竖屏
-  const previewSettings = useMemo<TitleSettings>(() => {
-    // 竖屏宽度 200px，按比例缩放字号，让预览看起来协调
-    return { ...settings, size: Math.round(settings.size * 0.55) }
-  }, [settings])
+  // 编辑器预览 settings：竖屏宽度 200px，字号按比例缩放
+  const previewSettings = useMemo<TitleStyleSettings>(
+    () => ({ ...settings, size: Math.round(settings.size * 0.55) }),
+    [settings],
+  )
 
   return (
     <Modal
@@ -140,7 +139,7 @@ const TitleTemplateEditor: React.FC<Props> = ({ open, template, onClose, onSave
         </div>
         {/* 右侧：参数 Tab */}
         <div className="ttv3-editor-right">
-          <TitleStylePanel
+          <TitleStyleParamsTab
             settings={settings}
             onUpdatePosition={(p) => upd({ position: p, posX: null, posY: null })}
             onUpdateFont={(f) => upd({ font: f })}
@@ -155,15 +154,9 @@ const TitleTemplateEditor: React.FC<Props> = ({ open, template, onClose, onSave
               })
             }
             onToggleShadow={() => upd({ shadow: !settings.shadow })}
-            onApplyPreset={() => {
-              /* 编辑器内不使用系统预设快捷键 */
-            }}
-            onUpdateStyle={(patch) => upd(patch)}
-            activePreset={null}
-            titlePresets={[]}
-            POSITION_OPTIONS={POSITION_OPTIONS}
-            FONT_OPTIONS={FONT_OPTIONS}
-            paramsOnly
+            onUpdatePatch={upd}
+            positionOptions={POSITION_OPTIONS}
+            fontOptions={FONT_OPTIONS}
           />
         </div>
       </div>

apps/web/src/components/title/TitleTemplateSelector.tsx

@@ -0,0 +1,343 @@
+/**
+ * 标题模板选择器 — 大卡片网格（共享组件）
+ *
+ * 渲染「我的模板」+「系统模板」两个分组的 3:4 竖版大圆角卡片：
+ * - 卡片上半：示例背景图 + vignette 暗角 + 透明 Canvas 大字预览
+ * - 卡片下半：emoji + 名称 + 系统/我的标签 + 始终可见的编辑/复制/导出/删除按钮
+ * - 选中紫色边框；右上角「新建模板」按钮；点编辑/新建弹 TitleTemplateEditor
+ *
+ * Props 通用化，不耦合业务 state。
+ */
+import React, { useCallback, useMemo, useState } from "react"
+import { Button, message, Popconfirm } from "antd"
+import {
+  PlusOutlined,
+  EditOutlined,
+  CopyOutlined,
+  DeleteOutlined,
+  ExportOutlined,
+  CheckOutlined,
+} from "@ant-design/icons"
+import type { TitleTemplate } from "./template-types"
+import type { TitleStyleSettings } from "./settings"
+import { DEFAULT_TITLE_STYLE_SETTINGS } from "./settings"
+import {
+  titleStyleConfigToCamel,
+  camelToTitleStyleConfig,
+  templateToPreviewSettings,
+} from "./utils"
+import { useTitleTemplates } from "./useTitleTemplates"
+import TitleMiniPreview from "./TitleMiniPreview"
+import TitleTemplateEditor from "./TitleTemplateEditor"
+import "./TitleTemplate.css"
+import "./TitleStylePanel.css"
+
+export interface TitleTemplateSelectorProps {
+  /** 当前选中模板 id（受控） */
+  value?: string | null
+  /** 选中模板时回调（templateId, fullStyleSettings, template） */
+  onChange?: (templateId: string, style: TitleStyleSettings, template: TitleTemplate) => void
+  /** 是否显示编辑器入口（新建/编辑按钮），默认 true */
+  showEditor?: boolean
+  /** 显示哪些分组，默认全部 */
+  categories?: Array<"system" | "custom">
+  /** 使用场景标识（仅作 data-attr，不影响样式） */
+  context?: string
+}
+
+/* ── 卡片预览背景图池（按 index 轮换） ── */
+const PREVIEW_BG_IMAGES = [
+  "/title-templates/portrait1.jpg",
+  "/title-templates/portrait2.jpg",
+  "/title-templates/scene1.jpg",
+]
+
+/* ── 预览容器：用 ref 测量宽度后再渲染透明 Canvas，保证文字清晰 ── */
+const FillPreview: React.FC<{
+  settings: TitleStyleSettings
+  sampleText: string
+  portrait?: boolean
+}> = ({ settings, sampleText, portrait }) => {
+  const [w, setW] = useState(0)
+  // 首次挂载后测量一次
+  const setRef = useCallback((el: HTMLDivElement | null) => {
+    if (el) setW(Math.floor(el.clientWidth))
+  }, [])
+  return (
+    <div ref={setRef} className="tt-fill-canvas-wrap">
+      {w > 0 && (
+        <TitleMiniPreview
+          settings={settings}
+          width={w}
+          sampleText={sampleText}
+          transparent
+          portrait={portrait}
+        />
+      )}
+    </div>
+  )
+}
+
+const TitleTemplateSelector: React.FC<TitleTemplateSelectorProps> = ({
+  value,
+  onChange,
+  showEditor = true,
+  categories = ["system", "custom"],
+  context,
+}) => {
+  const {
+    templates,
+    createTemplate,
+    duplicateTemplate,
+    updateTemplate,
+    deleteTemplate,
+    exportTemplate,
+  } = useTitleTemplates()
+
+  const [editingTemplate, setEditingTemplate] = useState<TitleTemplate | null>(null)
+  const [editorOpen, setEditorOpen] = useState(false)
+
+  const grouped = useMemo(
+    () => ({
+      builtin: templates.filter((t) => t.isBuiltin),
+      custom: templates.filter((t) => !t.isBuiltin),
+    }),
+    [templates],
+  )
+
+  const showSys = categories.includes("system")
+  const showMine = categories.includes("custom")
+
+  /* ── 选中模板：合成完整 TitleStyleSettings 回调给父组件 ── */
+  const handleSelectTemplate = useCallback(
+    (tpl: TitleTemplate) => {
+      const full: TitleStyleSettings = {
+        ...DEFAULT_TITLE_STYLE_SETTINGS,
+        ...titleStyleConfigToCamel(tpl.style),
+      }
+      onChange?.(tpl.id, full, tpl)
+    },
+    [onChange],
+  )
+
+  const handleRequestCreate = useCallback(() => {
+    // 新建：以当前选中模板样式为起点，否则用默认样式
+    let base: TitleStyleSettings = DEFAULT_TITLE_STYLE_SETTINGS
+    if (value) {
+      const sel = templates.find((t) => t.id === value)
+      if (sel) {
+        base = { ...DEFAULT_TITLE_STYLE_SETTINGS, ...titleStyleConfigToCamel(sel.style) }
+      }
+    }
+    const draft: TitleTemplate = {
+      id: "",
+      name: "我的标题模板",
+      emoji: "✨",
+      isBuiltin: false,
+      style: camelToTitleStyleConfig({
+        ...base,
+        position: base.position === "custom" ? "bottom" : base.position,
+      }),
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    }
+    setEditingTemplate(draft)
+    setEditorOpen(true)
+  }, [value, templates])
+
+  const handleRequestEdit = useCallback((tpl: TitleTemplate) => {
+    setEditingTemplate(tpl)
+    setEditorOpen(true)
+  }, [])
+
+  const handleDuplicate = useCallback(
+    (t: TitleTemplate) => {
+      const dup = duplicateTemplate(t.id)
+      if (dup) message.success(`已复制：${dup.name}`)
+    },
+    [duplicateTemplate],
+  )
+  const handleDelete = useCallback(
+    (t: TitleTemplate) => {
+      deleteTemplate(t.id)
+      message.success("已删除模板")
+    },
+    [deleteTemplate],
+  )
+  const handleExport = useCallback(
+    (t: TitleTemplate) => {
+      const json = exportTemplate(t.id)
+      if (!json) return
+      const blob = new Blob([json], { type: "application/json" })
+      const url = URL.createObjectURL(blob)
+      const a = document.createElement("a")
+      a.href = url
+      a.download = `${t.name}.title-template.json`
+      a.click()
+      URL.revokeObjectURL(url)
+    },
+    [exportTemplate],
+  )
+
+  const handleEditorSave = useCallback(
+    (data: { name: string; emoji: string; style: Partial<import("./types").TitleStyleConfig> }) => {
+      if (!editingTemplate) return
+      let saved: TitleTemplate
+      if (editingTemplate.isBuiltin || !editingTemplate.id) {
+        saved = createTemplate({ name: data.name, emoji: data.emoji, style: data.style })
+      } else {
+        updateTemplate(editingTemplate.id, {
+          name: data.name,
+          emoji: data.emoji,
+          style: data.style,
+        })
+        saved = {
+          ...editingTemplate,
+          name: data.name,
+          emoji: data.emoji,
+          style: data.style,
+          updatedAt: new Date().toISOString(),
+        }
+      }
+      setEditorOpen(false)
+      setEditingTemplate(null)
+      message.success(`已保存：${data.name}`)
+      handleSelectTemplate(saved)
+    },
+    [editingTemplate, createTemplate, updateTemplate, handleSelectTemplate],
+  )
+
+  /* ── 渲染单张大卡片 ── */
+  const renderCard = (t: TitleTemplate, idx: number, section: "mine" | "sys") => {
+    const isSelected = value === t.id
+    const bgIdx = idx % PREVIEW_BG_IMAGES.length
+    const bgImg = PREVIEW_BG_IMAGES[bgIdx]
+    const preview = templateToPreviewSettings(t, 42)
+    return (
+      <div
+        key={t.id}
+        className={`ttv3-card${isSelected ? " selected" : ""}`}
+        onClick={() => handleSelectTemplate(t)}
+        data-context={context}
+      >
+        <div className="ttv3-preview">
+          <img className="ttv3-bg" src={bgImg} alt="" />
+          <div className="ttv3-vignette" />
+          <FillPreview settings={preview} sampleText="预览标题文字" portrait />
+          <span className={`ttv3-badge ttv3-badge--${section}`}>
+            {section === "sys" ? "系统" : "我的"}
+          </span>
+          <span className={`ttv3-check${isSelected ? " on" : ""}`}>
+            {isSelected && <CheckOutlined />}
+          </span>
+        </div>
+        <div className="ttv3-footer">
+          <div className="ttv3-name-row">
+            <span className="ttv3-emoji">{t.emoji || "✨"}</span>
+            <span className="ttv3-name" title={t.name}>
+              {t.name}
+            </span>
+            <span className={`ttv3-tag ttv3-tag--${section}`}>
+              {section === "sys" ? "系统" : "我的"}
+            </span>
+          </div>
+          {showEditor && (
+            <div className="ttv3-actions" onClick={(e) => e.stopPropagation()}>
+              <button
+                type="button"
+                className="ttv3-act ttv3-act--primary"
+                disabled={t.isBuiltin}
+                onClick={() => handleRequestEdit(t)}
+                title={t.isBuiltin ? "系统模板不可编辑，点击复制后可编辑" : "编辑"}
+              >
+                <EditOutlined /> 编辑
+              </button>
+              <button
+                type="button"
+                className="ttv3-act"
+                onClick={() => handleDuplicate(t)}
+                title="复制"
+              >
+                <CopyOutlined /> 复制
+              </button>
+              <button
+                type="button"
+                className="ttv3-act"
+                onClick={() => handleExport(t)}
+                title="导出"
+              >
+                <ExportOutlined /> 导出
+              </button>
+              <Popconfirm title="删除该模板？" onConfirm={() => handleDelete(t)}>
+                <button
+                  type="button"
+                  className="ttv3-act ttv3-act--danger"
+                  disabled={t.isBuiltin}
+                  title={t.isBuiltin ? "系统模板不可删除" : "删除"}
+                >
+                  <DeleteOutlined /> 删除
+                </button>
+              </Popconfirm>
+            </div>
+          )}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="xx-title-style-section ttv3-panel">
+      <div className="ttv3-header">
+        <span className="ttv3-title">标题模板</span>
+        {showEditor && (
+          <Button
+            type="primary"
+            size="small"
+            icon={<PlusOutlined />}
+            onClick={handleRequestCreate}
+            className="ttv3-new-btn"
+          >
+            新建模板
+          </Button>
+        )}
+      </div>
+
+      {showMine && (
+        <div className="ttv3-section">
+          <div className="ttv3-section-label">我的模板</div>
+          {grouped.custom.length === 0 ? (
+            <div className="ttv3-empty">
+              <div className="ttv3-empty-icon">✨</div>
+              <div className="ttv3-empty-text">还没有自定义模板，点右上角「新建模板」创建</div>
+            </div>
+          ) : (
+            <div className="ttv3-grid">
+              {grouped.custom.map((t, i) => renderCard(t, i, "mine"))}
+            </div>
+          )}
+        </div>
+      )}
+
+      {showSys && (
+        <div className="ttv3-section">
+          <div className="ttv3-section-label">系统模板</div>
+          <div className="ttv3-grid">{grouped.builtin.map((t, i) => renderCard(t, i, "sys"))}</div>
+        </div>
+      )}
+
+      {showEditor && editorOpen && editingTemplate && (
+        <TitleTemplateEditor
+          open={editorOpen}
+          template={editingTemplate}
+          onClose={() => {
+            setEditorOpen(false)
+            setEditingTemplate(null)
+          }}
+          onSave={handleEditorSave}
+        />
+      )}
+    </div>
+  )
+}
+
+export default TitleTemplateSelector

apps/web/src/components/title/constants.ts

@@ -20,54 +20,84 @@ export const FONT_OPTIONS: FontOption[] = [
   {
     value: "优设标题黑",
     label: "优设标题黑",
+    // 原版"优设标题黑"为商用字体非开源；优先本地已安装字体，兜底用 Noto Sans SC（Google Fonts 已加载 wght@900，保证 bold 字重可用），再用 ZCOOL 庆科黄油体作风格兜底
     family:
-      '"YouShe Title Black","YouSheBiaoTiHei","Source Han Sans SC Heavy","Noto Sans SC","PingFang SC",sans-serif',
+      '"YouSheBiaoTiHei","YouShe Title Black","Noto Sans SC","ZCOOL QingKe HuangYou","PingFang SC","Microsoft YaHei",sans-serif',
     tag: "hot",
   },
   {
     value: "阿里普惠体Bold",
     label: "阿里普惠体Bold",
+    // 阿里普惠体需从阿里官网下载；兜底用 Noto Sans SC 900（同等字重，已在 Google Fonts wght@400;500;700;900 加载）
     family:
-      '"Alibaba PuHuiTi Bold","Alibaba PuHuiTi","Source Han Sans SC","PingFang SC",sans-serif',
+      '"Alibaba PuHuiTi","Alibaba PuHuiTi Bold","Alibaba Sans","Noto Sans SC",system-ui,"PingFang SC","Microsoft YaHei",sans-serif',
     tag: "hot",
   },
   {
     value: "抖音美好体",
     label: "抖音美好体",
-    family: '"Douyin Sans","DouyinSans","Source Han Sans SC","PingFang SC",sans-serif',
+    // 抖音美好体为版权字体；兜底用 Noto Sans SC（确保 bold 字重可用），再用 ZCOOL KuaiLe（站酷快乐体，圆润卡通风格近似）
+    family:
+      '"Douyin Sans","DouyinSans","Noto Sans SC","ZCOOL KuaiLe","PingFang SC","Microsoft YaHei",sans-serif',
     tag: "hot",
   },
   {
     value: "思源黑体Heavy",
     label: "思源黑体Heavy",
     family:
-      '"Source Han Sans SC Heavy","Noto Sans SC","Source Han Sans CN Heavy","PingFang SC",sans-serif',
+      '"Noto Sans SC","Source Han Sans SC","Source Han Sans CN Heavy","PingFang SC","Microsoft YaHei",sans-serif',
     tag: "new",
   },
   {
     value: "思源黑体",
     label: "思源黑体",
-    family: '"Source Han Sans SC","Noto Sans SC","PingFang SC","Microsoft YaHei",sans-serif',
+    family: '"Noto Sans SC","Source Han Sans SC","PingFang SC","Microsoft YaHei",sans-serif',
   },
   {
     value: "思源宋体",
     label: "思源宋体",
-    family: '"Source Han Serif SC","Noto Serif SC","Songti SC","SimSun",serif',
+    family: '"Noto Serif SC","Source Han Serif SC","Songti SC","SimSun",serif',
   },
   {
     value: "苹方",
     label: "苹方",
-    family: '"PingFang SC",-apple-system,"Helvetica Neue",sans-serif',
+    family:
+      '"PingFang SC",-apple-system,blinkmacsystemfont,"Helvetica Neue","Noto Sans SC",sans-serif',
   },
   {
     value: "微软雅黑",
     label: "微软雅黑",
-    family: '"Microsoft YaHei","PingFang SC",sans-serif',
+    family: '"Microsoft YaHei","PingFang SC","Noto Sans SC",sans-serif',
   },
   {
     value: "楷体",
     label: "楷体",
-    family: '"KaiTi","STKaiti","DFKai-SB",serif',
+    family: '"KaiTi","STKaiti","DFKai-SB","Kaiti SC",serif',
+  },
+  {
+    value: "站酷小薇体",
+    label: "站酷小薇体",
+    family: '"ZCOOL XiaoWei","Noto Serif SC",serif',
+  },
+  {
+    value: "马善政毛笔",
+    label: "马善政毛笔",
+    family: '"Ma Shan Zheng","STXingkai","KaiTi",cursive',
+  },
+  {
+    value: "龙藏体",
+    label: "龙藏体",
+    family: '"Long Cang","STXingkai","KaiTi",cursive',
+  },
+  {
+    value: "流江毛笔草",
+    label: "流江毛笔草",
+    family: '"Liu Jian Mao Cao","STXingkai",cursive',
+  },
+  {
+    value: "志莽行书",
+    label: "志莽行书",
+    family: '"Zhi Mang Xing","STXingkai",cursive',
   },
 ]
 

apps/web/src/components/title/index.ts

@@ -0,0 +1,19 @@
+/**
+ * 公共标题模板/样式组件统一导出
+ *
+ * 任何页面需要标题样式配置/模板选择/模板编辑，从这里 import，
+ * 不要直接 import pages/generate/components/title/* 下的内部组件。
+ */
+export { default as TitleTemplateSelector } from "./TitleTemplateSelector"
+export { default as TitleTemplateEditor } from "./TitleTemplateEditor"
+export { default as TitleStyleParamsTab } from "./TitleStyleParamsTab"
+export { default as TitleMiniPreview } from "./TitleMiniPreview"
+export { useTitleTemplates } from "./useTitleTemplates"
+export * from "./constants"
+export * from "./types"
+export * from "./template-types"
+export * from "./settings"
+export * from "./utils"
+export { POSITION_OPTIONS } from "./position-options"
+export type { PositionOption, FontOption, TitleStyleParamsTabProps } from "./TitleStyleParamsTab"
+export type { TitleTemplateSelectorProps } from "./TitleTemplateSelector"

apps/web/src/components/title/position-options.ts

@@ -0,0 +1,14 @@
+/**
+ * 标题位置选项（公共常量）
+ */
+export interface PositionOption {
+  value: string
+  label: string
+}
+
+export const POSITION_OPTIONS: PositionOption[] = [
+  { value: "top", label: "顶部" },
+  { value: "center", label: "居中" },
+  { value: "bottom", label: "底部" },
+  { value: "custom", label: "自定义" },
+]

apps/web/src/components/title/settings.ts

@@ -0,0 +1,64 @@
+/**
+ * 标题样式设置 — 公共 camelCase 类型与默认值
+ *
+ * 本文件是 @/components/title 公共包的唯一样式类型出口，不依赖任何业务页面（generate/ai-avatar）的私有类型。
+ * - 字段与后端 snake_case TitleStyleConfig 一一对应（camelCase 版本）
+ * - DEFAULT_TITLE_STYLE_SETTINGS 用于组件内部补全默认值
+ * - aiAutoSelect / title / coverTitle 等业务状态不在本类型中——它们属于页面业务 state
+ */
+import type { TitleLineOverride } from "./types"
+
+export interface TitleStyleSettings {
+  position: string
+  font: string
+  size: number
+  bold: boolean
+  italic: boolean
+  stroke: boolean
+  shadow: boolean
+  color: string
+  posX: number | null
+  posY: number | null
+  lineHeight: number
+  marginTop: number
+  maxCharsPerLine: number
+  strokeWidth: number
+  strokeColor: string
+  shadowOffsetX: number
+  shadowOffsetY: number
+  shadowBlur: number
+  shadowColor: string
+  bgEnabled: boolean
+  bgColor: string
+  bgPadding: number
+  bgRadius: number
+  lineOverrides: TitleLineOverride[]
+}
+
+/** 公共默认样式（经典白字黑描边） */
+export const DEFAULT_TITLE_STYLE_SETTINGS: TitleStyleSettings = {
+  position: "bottom",
+  font: "思源黑体",
+  size: 56,
+  bold: true,
+  italic: false,
+  stroke: true,
+  shadow: false,
+  color: "#ffffff",
+  posX: null,
+  posY: null,
+  lineHeight: 1.2,
+  marginTop: 24,
+  maxCharsPerLine: 10,
+  strokeWidth: 5,
+  strokeColor: "#000000",
+  shadowOffsetX: 2,
+  shadowOffsetY: 2,
+  shadowBlur: 4,
+  shadowColor: "rgba(0,0,0,0.8)",
+  bgEnabled: false,
+  bgColor: "rgba(0,0,0,0.5)",
+  bgPadding: 12,
+  bgRadius: 8,
+  lineOverrides: [],
+}

apps/web/src/components/title/utils.ts

@@ -1,24 +1,25 @@
 /**
  * 标题样式工具（#2001 / 模板系统 #2003）
  *
- * - snake_case TitleStyleConfig ↔ camelCase TitleSettings 互转
+ * - snake_case TitleStyleConfig <-> camelCase TitleStyleSettings 互转
  * - preset 归一化预览（修复"标题"两字大小不一）
+ * - template -> preview settings 转换
  */
 import type { TitleStyleConfig } from "./types"
-import type { TitleSettings } from "../../pages/generate/types"
+import type { TitleStyleSettings } from "./settings"
+import { DEFAULT_TITLE_STYLE_SETTINGS } from "./settings"
 import { TITLE_PRESETS } from "./constants"
-import { DEFAULT_TITLE_SETTINGS_FULL } from "../../pages/generate/types"
 import type { TitleTemplate } from "./template-types"
 
-/** snake_case TitleStyleConfig → camelCase TitleSettings（仅覆盖已知字段） */
-export function titleStyleConfigToCamel(s: Partial<TitleStyleConfig>): Partial<TitleSettings> {
-  const out: Partial<TitleSettings> = {}
+/** snake_case TitleStyleConfig -> camelCase TitleStyleSettings（仅覆盖已知字段） */
+export function titleStyleConfigToCamel(s: Partial<TitleStyleConfig>): Partial<TitleStyleSettings> {
+  const out: Partial<TitleStyleSettings> = {}
   if (s.font != null) out.font = s.font
   if (s.size != null) out.size = s.size
   if (s.color != null) out.color = s.color
   if (s.bold != null) out.bold = s.bold
   if (s.italic != null) out.italic = s.italic
-  if (s.position != null) out.position = s.position as TitleSettings["position"]
+  if (s.position != null) out.position = s.position
   if (s.pos_x != null) out.posX = s.pos_x
   if (s.pos_y != null) out.posY = s.pos_y
   if (s.line_height != null) out.lineHeight = s.line_height
@@ -40,8 +41,8 @@ export function titleStyleConfigToCamel(s: Partial<TitleStyleConfig>): Partial<T
   return out
 }
 
-/** camelCase TitleSettings patch → snake_case TitleStyleConfig patch */
-export function camelToTitleStyleConfig(p: Partial<TitleSettings>): Partial<TitleStyleConfig> {
+/** camelCase TitleStyleSettings patch -> snake_case TitleStyleConfig patch */
+export function camelToTitleStyleConfig(p: Partial<TitleStyleSettings>): Partial<TitleStyleConfig> {
   const out: Partial<TitleStyleConfig> = {}
   if (p.font != null) out.font = p.font
   if (p.size != null) out.size = p.size
@@ -71,15 +72,15 @@ export function camelToTitleStyleConfig(p: Partial<TitleSettings>): Partial<Titl
 }
 
 /**
- * 把 preset style（snake_case）归一化为固定字号的 TitleSettings，
+ * 把 preset style（snake_case）归一化为固定字号的 TitleStyleSettings，
  * 用于"预设卡片"缩略预览——所有卡片视觉上"标题"两字大小一致，便于辨识。
  * 描边/阴影/背景padding 按 fixedSize / 原始 size 比例缩放，避免粗描边爆框。
  */
 export function buildPresetPreviewSettings(
-  base: TitleSettings,
+  base: TitleStyleSettings,
   presetKey: string,
   fixedSize = 56,
-): TitleSettings {
+): TitleStyleSettings {
   const preset = TITLE_PRESETS.find((p) => p.key === presetKey)
   if (!preset) return base
   const origSize = preset.style.size ?? fixedSize
@@ -87,25 +88,25 @@ export function buildPresetPreviewSettings(
   const scale = (v: number | undefined, fallback: number): number =>
     v != null ? Math.round(v * ratio) : fallback
   return {
+    ...DEFAULT_TITLE_STYLE_SETTINGS,
     ...base,
     ...titleStyleConfigToCamel(preset.style),
     size: fixedSize,
-    strokeWidth: scale(preset.style.stroke_width, base.strokeWidth) ?? base.strokeWidth,
-    shadowOffsetX: scale(preset.style.shadow_offset_x, base.shadowOffsetX) ?? base.shadowOffsetX,
-    shadowOffsetY: scale(preset.style.shadow_offset_y, base.shadowOffsetY) ?? base.shadowOffsetY,
-    shadowBlur: scale(preset.style.shadow_blur, base.shadowBlur) ?? base.shadowBlur,
-    bgPadding: scale(preset.style.bg_padding, base.bgPadding) ?? base.bgPadding,
+    strokeWidth: scale(preset.style.stroke_width, base.strokeWidth),
+    shadowOffsetX: scale(preset.style.shadow_offset_x, base.shadowOffsetX),
+    shadowOffsetY: scale(preset.style.shadow_offset_y, base.shadowOffsetY),
+    shadowBlur: scale(preset.style.shadow_blur, base.shadowBlur),
+    bgPadding: scale(preset.style.bg_padding, base.bgPadding),
     lineOverrides: [],
   }
 }
 
 /**
- * 把 TitleTemplate 渲染为完整 TitleSettings（带默认值），用于卡片预览。
- * 与模板选择器中保持一致，抽出共用。
+ * 把 TitleTemplate 渲染为完整 TitleStyleSettings（带默认值），用于卡片预览。
  */
-export function templateToPreviewSettings(t: TitleTemplate, fixedSize = 48): TitleSettings {
-  const base: TitleSettings = {
-    ...DEFAULT_TITLE_SETTINGS_FULL,
+export function templateToPreviewSettings(t: TitleTemplate, fixedSize = 48): TitleStyleSettings {
+  const base: TitleStyleSettings = {
+    ...DEFAULT_TITLE_STYLE_SETTINGS,
     ...titleStyleConfigToCamel(t.style),
   }
   // 预览时用固定字号保证所有卡片字大小一致；描边/阴影/padding按比例缩放

apps/web/src/pages/ai-avatar/components/PanelTitleConfig.tsx

@@ -412,7 +412,7 @@ const PanelTitleConfig: React.FC<PanelTitleConfigProps> = ({ titleConfig, onUpda
         onUpdateStyle={handleUpdateStyle}
         showCoverToggle
         previewWidth={280}
-        enableTemplates
+        enableTemplates={true}
         selectedTemplateId={selectedTemplateId}
         onApplyTemplate={handleApplyTemplate}
         activePreset={activePreset}

apps/web/src/pages/generate/GeneratePage.tsx

@@ -14,7 +14,6 @@ import VoiceSelectModal from "./components/VoiceSelectModal"
 import ScriptSelectModal from "./components/ScriptSelectModal"
 import TtsVoiceModal from "./components/TtsVoiceModal"
 import GenerateHeader from "./components/GenerateHeader"
-import PreviewCountModal from "./components/PreviewCountModal"
 import GenerateStepsBar from "./components/GenerateStepsBar"
 import GenerateStepContent from "./components/GenerateStepContent"
 import GenerateStepActions from "./components/GenerateStepActions"
@@ -107,6 +106,7 @@ const GeneratePage: React.FC = () => {
     setPreviewCovers,
     selectedVariantIds,
     setSelectedVariantIds,
+    setSelectedTemplate,
   } = formState
 
   const isBatch = previewCount > 1
@@ -137,8 +137,8 @@ const GeneratePage: React.FC = () => {
     }
   }, [selectedVoice, isBatch, voiceModePerVideo, setVoiceLibraryIds])
 
-  /* ── 数量选择弹窗 ── */
-  const [countModalOpen, setCountModalOpen] = useState(false)
+  /* ── 标题面板模式：true = 内联大卡片模板网格（默认），false = 旧预设+参数 Tab ── */
+  const enableTemplates = true
 
   /* ── Step5 保存中状态 ── */
   const [finishing, setFinishing] = useState(false)
@@ -199,6 +199,7 @@ const GeneratePage: React.FC = () => {
     generated,
     generateError,
     generatedVideos,
+    currentTaskId,
     batchTasks,
     generate: handleGenerate,
     retry: handleRetryGenerate,
@@ -244,38 +245,37 @@ const GeneratePage: React.FC = () => {
     },
   })
 
-  /* ── 数量弹窗确认 ── */
-  const handleCountConfirm = useCallback(
-    (count: number) => {
-      setPreviewCount(count)
-      setCountModalOpen(false)
-      setPreviewTitles((prev) => {
-        const list = prev || []
-        const base = list[0] || titleSettings.title || ""
-        return Array.from({ length: count }, (_, i) => list[i] ?? (i === 0 ? base : ""))
-      })
-      setVoiceLibraryIds((prev) => {
-        const list = prev || []
-        return Array.from({ length: count }, (_, i) => list[i] ?? selectedVoice ?? "")
-      })
-      setPreviewCovers((prev) => {
-        const list = prev || []
-        return Array.from({ length: count }, (_, i) => list[i] ?? "")
-      })
-      setSelectedVariantIds(Array.from({ length: count }, (_, i) => i))
-      setCurrentStep(3)
-    },
-    [
-      setPreviewCount,
-      setPreviewTitles,
-      setVoiceLibraryIds,
-      setPreviewCovers,
-      setSelectedVariantIds,
-      setCurrentStep,
-      titleSettings.title,
-      selectedVoice,
-    ],
-  )
+  /* ── 对齐批量数组长度到 previewCount（用于进入 Step3 时） ── */
+  const ensureArraysAligned = useCallback(() => {
+    setPreviewTitles((prev) => {
+      const list = prev || []
+      if (list.length === previewCount) return list
+      const base = list[0] || titleSettings.title || ""
+      return Array.from({ length: previewCount }, (_, i) => list[i] ?? (i === 0 ? base : ""))
+    })
+    setVoiceLibraryIds((prev) => {
+      const list = prev || []
+      if (list.length === previewCount) return list
+      return Array.from({ length: previewCount }, (_, i) => list[i] ?? selectedVoice ?? "")
+    })
+    setPreviewCovers((prev) => {
+      const list = prev || []
+      if (list.length === previewCount) return list
+      return Array.from({ length: previewCount }, (_, i) => list[i] ?? "")
+    })
+    setSelectedVariantIds((prev) => {
+      if (prev && prev.length === previewCount) return prev
+      return Array.from({ length: previewCount }, (_, i) => i)
+    })
+  }, [
+    previewCount,
+    setPreviewTitles,
+    setVoiceLibraryIds,
+    setPreviewCovers,
+    setSelectedVariantIds,
+    titleSettings.title,
+    selectedVoice,
+  ])
 
   /* ── #1970：Step1 弹窗回调 ── */
   const handleVoiceModalConfirm = useCallback(
@@ -398,7 +398,7 @@ const GeneratePage: React.FC = () => {
     smartSelectedIds,
     titleSettings,
     generated,
-    onOpenCountModal: () => setCountModalOpen(true),
+    onBeforeEnterStep3: ensureArraysAligned,
     onOpenStep1Modal: () => {
       if (editMode === "random") {
         setVoiceModalOpen(true)
@@ -421,7 +421,10 @@ const GeneratePage: React.FC = () => {
         return
       }
     } else {
-      if (!finalVideo) {
+      // 单视频：finalVideo 可能因 /results 接口在 awaiting_cover 阶段暂未返回
+      // GeneratedVideo 记录而为 undefined；此时 currentTaskId 已在创建任务时保存，
+      // 下面 singleTaskId 兜底逻辑会用 currentTaskId 调 finalize，不应拦截
+      if (!finalVideo && !currentTaskId) {
         message.warning("请等待视频生成完成")
         return
       }
@@ -429,30 +432,36 @@ const GeneratePage: React.FC = () => {
     setFinishing(true)
     const hide = message.loading("正在保存到视频库...", 0)
     try {
-      const taskIds =
-        batchTasks && batchTasks.length > 0
-          ? batchTasks.map((t) => t.taskId).filter(Boolean)
-          : finalVideo?.generation_task_id
-            ? [finalVideo.generation_task_id]
-            : []
+      // 收集需要 finalize 的任务 ID：批量用 batchTasks；单视频优先用 finalVideo.generation_task_id，兜底 currentTaskId
+      const singleTaskId = finalVideo?.generation_task_id || currentTaskId || ""
 
-      // 单视频/批量：为每个 awaiting_cover 任务调用 finalize（入库 + 绑定封面 + 自定义标题）
-      if (isBatch && previewCovers.length > 0) {
+      // 单视频/批量：为每个任务调用 finalize（入库 + 绑定封面 + 自定义标题）
+      // 批量时必须按 batchTasks[i].variantIndex 对齐 previewCovers/previewTitles（taskIds 顺序不一定按变体序号）
+      if (isBatch && batchTasks.length > 0) {
         await Promise.all(
-          taskIds.map(async (taskId, idx) => {
-            const coverUrl = previewCovers[idx] || ""
-            return finalizeGeneration(taskId, {
+          batchTasks.map(async (task) => {
+            const vi = task.variantIndex
+            const rawCoverUrl = previewCovers[vi] || ""
+            const coverUrl = rawCoverUrl.startsWith("blob:") ? "" : rawCoverUrl
+            const title = previewTitles[vi] || titleSettings.title || ""
+            return finalizeGeneration(task.taskId, {
               cover_url: coverUrl || undefined,
-              custom_title: previewTitles[idx] || titleSettings.title || "",
+              custom_title: title || undefined,
             })
           }),
         )
-      } else if (finalVideo?.generation_task_id) {
-        const coverUrl = coverSettings.thumbnail_url || coverSettings.upload_url || ""
-        await finalizeGeneration(finalVideo.generation_task_id, {
+      } else if (singleTaskId) {
+        // 单视频：cover_url 仅在非 blob: 本地预览地址时才传；blob: URL 浏览器本地临时地址，
+        // 后端无法下载，此时不传让后端回退自动截帧封面（避免 400 保存失败）。
+        // 正常流程本地上传完成后 uploadLocalCover 会把 URL 替换为 OSS 真实 URL，这里仅兜底异常场景。
+        const rawCoverUrl = coverSettings.thumbnail_url || coverSettings.upload_url || ""
+        const coverUrl = rawCoverUrl.startsWith("blob:") ? "" : rawCoverUrl
+        await finalizeGeneration(singleTaskId, {
           cover_url: coverUrl || undefined,
-          custom_title: titleSettings.title || "",
+          custom_title: titleSettings.title || undefined,
         })
+      } else {
+        console.warn("[handleFinish] 未找到任务 ID，跳过 finalize 直接跳转")
       }
 
       hide()
@@ -481,6 +490,7 @@ const GeneratePage: React.FC = () => {
     previewTitles,
     titleSettings.title,
     coverSettings,
+    currentTaskId,
     navigate,
   ])
 
@@ -539,7 +549,7 @@ const GeneratePage: React.FC = () => {
             onUpdateStyle={styleUpdaters.updateStyle}
             activePreset={styleUpdaters.activePreset}
             titlePresets={styleUpdaters.titlePresets}
-            enableTemplates
+            enableTemplates={enableTemplates}
             selectedTemplateId={selectedTitleTemplateId}
             onApplyTemplate={(settings, tpl) => {
               styleUpdaters.applyTemplate(settings)
@@ -563,6 +573,8 @@ const GeneratePage: React.FC = () => {
             generateError={generateError}
             progress={progress}
             generatedVideos={generatedVideos}
+
+            currentTaskId={currentTaskId}
             onRetry={handleRetryGenerate}
             onRetryBatchTask={handleRetryBatchTask}
             onDismissError={handleDismissError}
@@ -577,6 +589,9 @@ const GeneratePage: React.FC = () => {
             previewCovers={previewCovers}
             onPreviewCoversChange={setPreviewCovers}
             selectedVariantIds={selectedVariantIds}
+            selectedCoverTemplate={selectedTemplate}
+            onSelectedCoverTemplateChange={setSelectedTemplate}
+            onConfirmGenerate={handleConfirmGenerate}
           />
 
           {/* ════ 步骤4（单视频）：成片播放器 ════ */}
@@ -664,14 +679,6 @@ const GeneratePage: React.FC = () => {
         </div>
       </div>
 
-      {/* 数量选择弹窗 */}
-      <PreviewCountModal
-        open={countModalOpen}
-        defaultCount={1}
-        onConfirm={handleCountConfirm}
-        onCancel={() => setCountModalOpen(false)}
-      />
-
       {/* 音色克隆弹窗 */}
       <CloneModal
         open={cloneModalOpen}

apps/web/src/pages/generate/components/GenerateStepContent.tsx

@@ -89,6 +89,12 @@ export interface GenerateStepContentProps {
   previewCovers: string[]
   onPreviewCoversChange: (urls: string[]) => void
   selectedVariantIds?: number[]
+  selectedCoverTemplate?: string
+  onSelectedCoverTemplateChange?: (templateId: string) => void
+  /** 单视频任务 ID（兜底，awaiting_cover 状态下 results 接口未入库时用） */
+  currentTaskId?: string
+  /** Step3 右上角确认生成按钮 */
+  onConfirmGenerate?: () => void | Promise<void>
 }
 
 export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) => {
@@ -142,6 +148,9 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
     previewCovers,
     onPreviewCoversChange,
     selectedVariantIds,
+    selectedCoverTemplate,
+    onSelectedCoverTemplateChange,
+    onConfirmGenerate,
   } = props
 
   switch (currentStep) {
@@ -195,6 +204,11 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
           previewCount={previewCount}
           previewTitles={previewTitles}
           onPreviewTitlesChange={onPreviewTitlesChange}
+          onConfirmGenerate={onConfirmGenerate}
+          generating={props.generating}
+          selectedCount={
+            props.previewCount && props.previewCount > 1 ? props.selectedVariantIds?.length || 1 : 1
+          }
         />
       )
     case 4:
@@ -250,6 +264,9 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
           previewCovers={previewCovers}
           onPreviewCoversChange={onPreviewCoversChange}
           selectedVariantIndexes={selectedVariantIds}
+          selectedTemplate={selectedCoverTemplate}
+          onTemplateChange={onSelectedCoverTemplateChange}
+          currentTaskId={props.currentTaskId}
         />
       )
     default:

apps/web/src/pages/generate/components/PreviewCountModal.tsx

@@ -1,127 +0,0 @@
-/**
- * 生成数量选择弹窗（Issue #1677）
- * Step1 选完模板点「下一步」时弹出：要生成几个视频？（1~10）
- * 默认 1，回车 = 1（零额外操作）
- */
-import React, { useState, useEffect, useRef } from "react"
-import { MAX_PREVIEW_COUNT } from "../constants"
-
-interface PreviewCountModalProps {
-  open: boolean
-  /** 默认值（上次选择，默认1） */
-  defaultCount?: number
-  onConfirm: (count: number) => void
-  onCancel: () => void
-}
-
-const PreviewCountModal: React.FC<PreviewCountModalProps> = ({
-  open,
-  defaultCount = 1,
-  onConfirm,
-  onCancel,
-}) => {
-  const [count, setCount] = useState(defaultCount)
-  const inputRef = useRef<HTMLInputElement>(null)
-
-  useEffect(() => {
-    if (open) {
-      setCount(defaultCount)
-      // 弹窗打开后聚焦并选中，方便直接回车=默认1
-      setTimeout(() => inputRef.current?.focus(), 50)
-    }
-  }, [open, defaultCount])
-
-  const clamp = (n: number) => Math.max(1, Math.min(MAX_PREVIEW_COUNT, n || 1))
-
-  const handleConfirm = () => {
-    onConfirm(clamp(count))
-  }
-
-  const handleKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key === "Enter") {
-      e.preventDefault()
-      handleConfirm()
-    }
-    if (e.key === "Escape") {
-      onCancel()
-    }
-  }
-
-  if (!open) return null
-
-  return (
-    <div className="xx-modal-mask" onClick={onCancel}>
-      <div className="xx-modal-box xx-count-modal" onClick={(e) => e.stopPropagation()}>
-        <h3 style={{ margin: "0 0 8px", fontSize: 18 }}>要生成几个视频？</h3>
-        <p style={{ margin: "0 0 20px", fontSize: 13, color: "var(--text-secondary, #666)" }}>
-          素材共用，AI 随机剪辑出不同版本，每个视频可独立设置标题、配音和封面
-        </p>
-
-        <div className="xx-count-selector">
-          <button
-            type="button"
-            className="xx-count-btn"
-            onClick={() => setCount((c) => clamp(c - 1))}
-            disabled={count <= 1}
-            aria-label="减少"
-          >
-            −
-          </button>
-          <input
-            ref={inputRef}
-            type="number"
-            min={1}
-            max={MAX_PREVIEW_COUNT}
-            value={count}
-            onChange={(e) => setCount(clamp(parseInt(e.target.value, 10) || 1))}
-            onKeyDown={handleKeyDown}
-            className="xx-count-input"
-          />
-          <button
-            type="button"
-            className="xx-count-btn"
-            onClick={() => setCount((c) => clamp(c + 1))}
-            disabled={count >= MAX_PREVIEW_COUNT}
-            aria-label="增加"
-          >
-            +
-          </button>
-        </div>
-
-        <div className="xx-count-quick">
-          {[1, 3, 5, 10].map((n) => (
-            <button
-              key={n}
-              type="button"
-              className={`xx-count-chip ${count === n ? "active" : ""}`}
-              onClick={() => setCount(n)}
-            >
-              {n} 个
-            </button>
-          ))}
-        </div>
-
-        <div className="xx-count-actions">
-          <button type="button" className="xx-btn xx-btn-ghost" onClick={onCancel}>
-            取消
-          </button>
-          <button type="button" className="xx-btn xx-btn-primary" onClick={handleConfirm}>
-            {count === 1 ? "生成 1 个视频" : `生成 ${count} 个视频`}
-          </button>
-        </div>
-        <p
-          style={{
-            margin: "12px 0 0",
-            fontSize: 12,
-            color: "var(--text-tertiary, #999)",
-            textAlign: "center",
-          }}
-        >
-          直接按回车 = 生成 1 个
-        </p>
-      </div>
-    </div>
-  )
-}
-
-export default PreviewCountModal

apps/web/src/pages/generate/components/Step4TitleSettings.tsx

@@ -47,6 +47,12 @@ interface Step4TitleSettingsProps {
   enableTemplates?: boolean
   selectedTemplateId?: string | null
   onApplyTemplate?: (settings: TitleSettings, template: TitleTemplate) => void
+  /** Step3 右上角「🎬 确认生成」主按钮 */
+  onConfirmGenerate?: () => void | Promise<void>
+  /** 是否生成中 */
+  generating?: boolean
+  /** 批量模式下勾选数量 */
+  selectedCount?: number
 }
 
 const Step4TitleSettings: React.FC<Step4TitleSettingsProps> = (props) => {
@@ -69,6 +75,9 @@ const Step4TitleSettings: React.FC<Step4TitleSettingsProps> = (props) => {
     enableTemplates,
     selectedTemplateId,
     onApplyTemplate,
+    onConfirmGenerate,
+    generating,
+    selectedCount = 1,
   } = props
 
   const isBatch = previewCount > 1
@@ -90,7 +99,47 @@ const Step4TitleSettings: React.FC<Step4TitleSettingsProps> = (props) => {
   )
 
   return (
-    <div className="xx-form-section">
+    <div className="xx-form-section" style={{ position: "relative" }}>
+      {/* ── 右上角「🎬 确认生成」主按钮 ── */}
+      {onConfirmGenerate && (
+        <button
+          type="button"
+          onClick={() => {
+            if (generating) return
+            void onConfirmGenerate()
+          }}
+          disabled={generating}
+          style={{
+            position: "absolute",
+            top: 0,
+            right: 0,
+            background: generating ? "#a78bfa" : "#7c3aed",
+            color: "#fff",
+            border: "none",
+            borderRadius: 10,
+            padding: "12px 24px",
+            fontSize: 15,
+            fontWeight: 600,
+            cursor: generating ? "not-allowed" : "pointer",
+            boxShadow: "0 4px 14px rgba(124,58,237,0.4)",
+            transition: "all .2s",
+            zIndex: 5,
+            whiteSpace: "nowrap",
+          }}
+          onMouseEnter={(e) => {
+            if (!generating) (e.currentTarget as HTMLButtonElement).style.background = "#6d28d9"
+          }}
+          onMouseLeave={(e) => {
+            if (!generating) (e.currentTarget as HTMLButtonElement).style.background = "#7c3aed"
+          }}
+        >
+          {generating
+            ? "⏳ 生成中..."
+            : selectedCount > 1
+              ? `🎬 确认生成 ${selectedCount} 个视频`
+              : "🎬 确认生成"}
+        </button>
+      )}
       <h3>📝 选择标题</h3>
 
       {!isBatch ? (

apps/web/src/pages/generate/components/Step6CoverSettings.tsx

@@ -5,8 +5,8 @@
  *
  * 模板 CRUD + 编辑器弹窗 + 自动生成 + 上传 复用 components/cover/useSharedCover
  */
-import React, { useEffect, useMemo } from "react"
-import { Modal, Spin } from "antd"
+import React, { useCallback, useEffect, useMemo, useState } from "react"
+import { Modal, Spin, message } from "antd"
 import { LoadingOutlined } from "@ant-design/icons"
 import type { CoverConfig } from "../types/cover"
 import type { GeneratedVideo } from "@/api/template-editor"
@@ -17,6 +17,7 @@ import CoverSettingsModal from "./cover-settings/CoverSettingsModal"
 import CoverEditorModal from "./cover-settings/CoverEditorModal"
 import { useSharedCover } from "@/components/cover/useSharedCover"
 import { generateCover as apiGenerateCover } from "@/api/generation"
+import { uploadAssetDirect, getAssetLibraries } from "@/api/assets"
 
 interface Step6CoverSettingsProps {
   coverSettings: CoverConfig
@@ -30,6 +31,8 @@ interface Step6CoverSettingsProps {
   onPreviewCoversChange?: (urls: string[]) => void
   selectedVariantIndexes?: number[]
   onTemplateChange?: (templateId: string) => void
+  /** 单视频任务 ID（awaiting_cover 阶段 results 接口可能返回 preview-xxx 合成对象，兜底用） */
+  currentTaskId?: string
 }
 
 const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
@@ -47,6 +50,32 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
     props.generatedVideos.find((v) => v.status === "completed" || v.status === "awaiting_cover") ||
     props.generatedVideos[0]
 
+  /**
+   * 兜底任务/视频 ID：awaiting_cover 阶段后端 /results 可能还没有入库 GeneratedVideo，
+   * 只返回合成的 preview-{taskId} 轻量对象；此时用 currentTaskId 兜底让后端能找到任务。
+   * 同时统一抽取 taskId（generation_task_id 优先）用于日志/错误提示。
+   */
+  const effectiveTaskId =
+    (finalVideo as { generation_task_id?: string } | undefined)?.generation_task_id ||
+    props.currentTaskId ||
+    ""
+  const _rawVideoId =
+    (finalVideo as { id?: string; video_id?: string } | undefined)?.id ||
+    (finalVideo as { video_id?: string } | undefined)?.video_id ||
+    ""
+  // preview-{taskId} 是后端合成的临时 id，gv_repo.get 查不到 → 不传 generated_video_id，
+  // 让后端走 plan.config.generation_task_id / rendered_storage_key 兜底路径。
+  const effectiveVideoId = _rawVideoId && !_rawVideoId.startsWith("preview-") ? _rawVideoId : ""
+  const effectiveVideoUrl = finalVideo?.file_url || finalVideo?.download_url || ""
+
+  /** 按钮可用：非批量 且 （有 finalVideo 对象或兜底 taskId） 且 视频状态已完成/等待封面/未设置 */
+  const isVideoReady =
+    !finalVideo ||
+    finalVideo.status === "completed" ||
+    finalVideo.status === "awaiting_cover" ||
+    !finalVideo.status
+  const canGenerateCover = !isBatch && (!!finalVideo || !!effectiveTaskId) && isVideoReady
+
   const completedVideos = useMemo(
     () =>
       props.generatedVideos.filter(
@@ -60,37 +89,58 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
    * 批量场景 canGenerate=false，避免 shared.generateAutoCover 被误触发
    */
   const shared = useSharedCover({
-    canGenerate: !!finalVideo && !isBatch,
-    disabledHint: isBatch ? "批量场景请在上方操作卡片" : "请先生成视频再选择封面",
-    initialTemplateId: props.selectedTemplate || "default",
+    canGenerate: canGenerateCover,
+    disabledHint: isBatch
+      ? "批量场景请在上方操作卡片"
+      : !finalVideo && !effectiveTaskId
+        ? "请先生成视频再选择封面"
+        : "视频尚未就绪，请稍候",
+    initialTemplateId: "default", // 封面模板独立于编辑模板，默认用 default
     generateFn: async (tplId) => {
-      if (!finalVideo || isBatch) return null
-      const response = await apiGenerateCover(tplId, {
-        generated_video_id: finalVideo.id,
-        video_url: finalVideo.file_url || finalVideo.download_url || "",
+      if (isBatch) return null
+      if (!finalVideo && !effectiveTaskId) {
+        console.warn("[Cover] generateAutoCover: no finalVideo and no taskId")
+        return null
+      }
+      // 请求体：generated_video_id 仅在后端已入库（非 preview-xxx 合成id）时传；
+      // video_url 兜底让后端能直接下载视频抽帧；generation_task_id 后端已从 plan.config 自动读取。
+      const requestBody: {
+        generated_video_id?: string
+        video_url?: string
+        cover_type: "ai_frame"
+        title_config?: Record<string, unknown>
+      } = {
         cover_type: "ai_frame",
-        ...(props.titleSettings?.title
-          ? {
-              title_config: {
-                text: props.titleSettings.title,
-                font: props.titleSettings.font,
-                font_size: props.titleSettings.size,
-                font_color: props.titleSettings.color,
-                position: props.titleSettings.position,
-                bold: props.titleSettings.bold,
-                stroke: props.titleSettings.stroke,
-                shadow: props.titleSettings.shadow,
-              },
-            }
-          : {}),
-      })
-      const url = response.cover?.image_url || ""
+      }
+      if (effectiveVideoId) {
+        requestBody.generated_video_id = effectiveVideoId
+      }
+      if (effectiveVideoUrl) {
+        requestBody.video_url = effectiveVideoUrl
+      }
+      if (props.titleSettings?.title) {
+        requestBody.title_config = {
+          text: props.titleSettings.title,
+          font: props.titleSettings.font,
+          font_size: props.titleSettings.size,
+          font_color: props.titleSettings.color,
+          position: props.titleSettings.position,
+          bold: props.titleSettings.bold,
+          stroke: props.titleSettings.stroke,
+          shadow: props.titleSettings.shadow,
+        }
+      }
+      console.log("[Cover] auto-generate request:", { tplId, ...requestBody })
+      const response = await apiGenerateCover(tplId, requestBody)
+      const url = response.cover?.image_url || response.cover?.thumbnail_url || ""
       if (url) {
         props.onCoverSettingsChange({
           ...props.coverSettings,
           thumbnail_url: url,
           ai_suggested_time: response.cover?.frame_time ?? null,
         })
+      } else {
+        console.warn("[Cover] generate returned empty url:", response)
       }
       return url
     },
@@ -98,15 +148,77 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
 
   // 选中模板变化时通知父组件（用于批量生成时透传 template_id）
   const { onTemplateChange, selectedTemplate: parentSelectedTemplate } = props
+  // 父组件 selectedTemplate 变化时同步到子（例如从 Step1/Step4 切换到 Step6 时）
+  useEffect(() => {
+    if (parentSelectedTemplate && parentSelectedTemplate !== shared.selectedTemplateId) {
+      shared.handleSelectTemplate(parentSelectedTemplate)
+    }
+  }, [parentSelectedTemplate]) // eslint-disable-line react-hooks/exhaustive-deps
   useEffect(() => {
     if (isBatch && onTemplateChange && shared.selectedTemplateId !== parentSelectedTemplate) {
       onTemplateChange(shared.selectedTemplateId)
     }
   }, [isBatch, shared.selectedTemplateId, parentSelectedTemplate, onTemplateChange])
 
+  /** 单视频本地上传封面：选完文件后上传到素材库 OSS，拿到真实 URL 再 set */
+  const [uploadingLocalCover, setUploadingLocalCover] = useState(false)
+  const { coverSettings: curCoverSettings, onCoverSettingsChange } = props
+  const uploadLocalCover = useCallback(
+    async (file: File): Promise<string | null> => {
+      const hide = message.loading("正在上传封面...", 0)
+      setUploadingLocalCover(true)
+      try {
+        // 立即创建 blob URL 用于即时预览，同时异步上传 OSS
+        const previewUrl = URL.createObjectURL(file)
+        onCoverSettingsChange({
+          ...curCoverSettings,
+          upload_url: previewUrl,
+          thumbnail_url: previewUrl,
+          mode: "upload",
+        })
+        // 查找图片素材库（复用批量封面的逻辑）
+        const libs = await getAssetLibraries()
+        const imageLib = libs.find((l) => l.kind === "image") || libs[0]
+        if (!imageLib) {
+          hide()
+          message.error("未找到素材库，请先创建图片素材库")
+          return previewUrl
+        }
+        const result = await uploadAssetDirect({ file, library_id: imageLib.id })
+        const realUrl = result?.url || ""
+        if (!realUrl) {
+          hide()
+          message.warning("上传完成但未获取到URL，将使用本地预览")
+          return previewUrl
+        }
+        hide()
+        // 替换 blob URL 为真实 OSS URL（blob 用于预览过渡，finalize 时必须用真实 URL）
+        onCoverSettingsChange({
+          ...curCoverSettings,
+          upload_url: realUrl,
+          thumbnail_url: realUrl,
+          mode: "upload",
+        })
+        message.success("封面上传成功")
+        return realUrl
+      } catch (err) {
+        hide()
+        console.error("[Step6] 封面上传失败:", err)
+        message.error("封面上传失败，请重试")
+        return null
+      } finally {
+        setUploadingLocalCover(false)
+      }
+    },
+    [curCoverSettings, onCoverSettingsChange],
+  )
   useEffect(() => {
-    shared.setOnUploadFile(() => null)
-  }, [shared])
+    // 单视频：注册实际上传函数；批量场景已由 batchCovers.uploadOne 接管，
+    // 这里不要覆盖（批量时 input ref 绑定到 batchUploadRef，不走 shared.handleFileInputChange）
+    if (!isBatch) {
+      shared.setOnUploadFile((file) => uploadLocalCover(file))
+    }
+  }, [shared, isBatch, uploadLocalCover])
 
   const batchUploadRef = React.useRef<HTMLInputElement>(null)
   const [batchUploadCard, setBatchUploadCard] = React.useState<number | null>(null)
@@ -131,7 +243,7 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
    * 透传给 useBatchCovers，由其在 generateOne/generateAll 中发给后端。
    */
   const batchCovers = useBatchCovers({
-    selectedTemplate: shared.selectedTemplateId || "default",
+    selectedTemplate: shared.selectedTemplateId,
     generatedVideos: props.generatedVideos,
     titles: batchTitles,
     titleStyle: {
@@ -309,7 +421,7 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
     <div className="xx-form-section">
       <h3>🖼️ 选择封面</h3>
 
-      {finalVideo && (
+      {(finalVideo || effectiveTaskId) && (
         <div
           style={{
             padding: "10px 14px",
@@ -321,7 +433,7 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
             color: "var(--text-secondary, #666)",
           }}
         >
-          🎬 封面将从最终成片「{finalVideo.name}」中智能选帧
+          🎬 封面将从最终成片{finalVideo?.name ? `「${finalVideo.name}」` : ""}中智能选帧
           {shared.selectedTemplateId && shared.selectedTemplateId !== "default" && (
             <>
               {" "}
@@ -335,15 +447,21 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
         <Button
           buttonType="primary"
           onClick={() => void shared.generateAutoCover()}
-          disabled={!finalVideo || shared.generating}
+          disabled={!canGenerateCover || shared.generating}
           loading={shared.generating}
+          title={!canGenerateCover ? "请先完成视频生成" : ""}
         >
           ✨ 自动生成封面
         </Button>
         <Button buttonType="ghost" onClick={() => shared.setShowCoverSettings(true)}>
           ⚙️ 封面模板
         </Button>
-        <Button buttonType="ghost" onClick={shared.handleUploadClick}>
+        <Button
+          buttonType="ghost"
+          onClick={shared.handleUploadClick}
+          disabled={uploadingLocalCover}
+          loading={uploadingLocalCover}
+        >
           📷 本地上传
         </Button>
         <input
@@ -351,18 +469,7 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
           type="file"
           accept="image/*"
           style={{ display: "none" }}
-          onChange={(e) => {
-            const file = e.target.files?.[0]
-            e.target.value = ""
-            if (!file) return
-            const url = URL.createObjectURL(file)
-            props.onCoverSettingsChange({
-              ...props.coverSettings,
-              upload_url: url,
-              thumbnail_url: url,
-              mode: "upload",
-            })
-          }}
+          onChange={shared.handleFileInputChange}
         />
         <input
           ref={batchUploadRef}

apps/web/src/pages/generate/components/cover-settings/CoverEditorModal.tsx

@@ -7,7 +7,7 @@ import type {
   TextDirection,
   StrokeStyle,
 } from "../../types/cover"
-import { DEFAULT_EDITOR_CONFIG, PRESET_FONTS, SYSTEM_FONTS, ALL_FONTS } from "../../types/cover"
+import { DEFAULT_EDITOR_CONFIG, ALL_FONTS } from "../../types/cover"
 import Modal from "@/components/ui/Modal"
 import Button from "@/components/ui/Button"
 import "@/components/cover/cover.css"
@@ -16,6 +16,19 @@ import "@/components/cover/cover.css"
 const mergeEditorConfig = (partial?: Partial<CoverEditorConfig> | null): CoverEditorConfig => {
   const def = DEFAULT_EDITOR_CONFIG
   const src = partial || {}
+  /** 兼容老模板：老版本 background 有 posX/posY/rotation，新版改为 offsetY（相对文字位置偏移）。
+   *  老模板黑底默认 posY 通常是 50（与文字对齐）或 80（副标题偏下），统一归一为 offsetY=0，
+   *  因为新版背景位置已自动跟随文字位置，offsetY 仅做相对微调。 */
+  const normalizeBg = (bg: Record<string, unknown> | undefined) => {
+    if (!bg) return {}
+    // 兼容老模板字段：posX/posY/rotation 在新版中已改为 offsetY（背景位置自动跟随文字）
+    const normalized = { ...bg }
+    delete (normalized as Record<string, unknown>).posX
+    delete (normalized as Record<string, unknown>).posY
+    delete (normalized as Record<string, unknown>).rotation
+    if (normalized.offsetY == null) normalized.offsetY = 0
+    return normalized
+  }
   const mergeText = (
     base: TextStyleConfig,
     patch?: Partial<TextStyleConfig> | null,
@@ -23,7 +36,10 @@ const mergeEditorConfig = (partial?: Partial<CoverEditorConfig> | null): CoverEd
     ...base,
     ...(patch || {}),
     position: { ...base.position, ...(patch?.position || {}) },
-    background: { ...base.background, ...(patch?.background || {}) },
+    background: {
+      ...base.background,
+      ...normalizeBg(patch?.background as Record<string, unknown> | undefined),
+    },
     shadows: Array.isArray(patch?.shadows) ? [...patch!.shadows] : [...base.shadows],
   })
   return {
@@ -93,27 +109,23 @@ const PositionPair: React.FC<{
   </div>
 )
 
-/* ── Font Select options ── */
-const fontOptions = [
-  ...PRESET_FONTS.map((f) => ({
-    label: (
-      <span>
-        <span className="xx-ce-font-dot xx-ce-font-dot--preset" />
-        <span style={{ fontFamily: f.family }}>{f.name}</span>
-      </span>
-    ),
-    value: f.name,
-  })),
-  ...SYSTEM_FONTS.map((f) => ({
-    label: (
-      <span>
-        <span className="xx-ce-font-dot xx-ce-font-dot--system" />
-        <span style={{ fontFamily: f.family }}>{f.name}</span>
-      </span>
-    ),
-    value: f.name,
-  })),
-]
+/* ── Font Select options（合并预设+系统，用圆点颜色区分 tag） ── */
+const fontDotClass = (tag?: string) => {
+  if (tag === "preset") return "xx-ce-font-dot xx-ce-font-dot--preset"
+  if (tag === "hand") return "xx-ce-font-dot xx-ce-font-dot--hand"
+  if (tag === "serif") return "xx-ce-font-dot xx-ce-font-dot--serif"
+  if (tag === "mono") return "xx-ce-font-dot xx-ce-font-dot--mono"
+  return "xx-ce-font-dot xx-ce-font-dot--system"
+}
+const fontOptions = ALL_FONTS.map((f) => ({
+  label: (
+    <span>
+      <span className={fontDotClass(f.tag)} />
+      <span style={{ fontFamily: f.family }}>{f.name}</span>
+    </span>
+  ),
+  value: f.name,
+}))
 
 /* ── Find font family string from name ── */
 const getFontFamily = (name: string): string => {
@@ -294,6 +306,122 @@ const TextStylePanel: React.FC<{
           onChange={(v) => upd("rotation", v)}
         />
       </div>
+
+      {/* 文字背景（剪映样式） */}
+      <div className="xx-ce-switch-item">
+        <div className="xx-ce-switch-row">
+          <span>文字背景</span>
+          <Switch
+            size="small"
+            checked={config.background?.enabled ?? false}
+            onChange={(v) => upd("background", { ...config.background, enabled: v })}
+          />
+        </div>
+        {config.background?.enabled && (
+          <div style={{ marginTop: 8, paddingLeft: 4 }}>
+            <div className="xx-ce-row">
+              <label className="xx-ce-label">形状</label>
+              <div className="xx-ce-radio-group">
+                <button
+                  type="button"
+                  className={`xx-ce-radio-btn ${config.background.shape === "rectangle" ? "active" : ""}`}
+                  onClick={() =>
+                    upd("background", {
+                      ...config.background,
+                      shape: "rectangle" as const,
+                    })
+                  }
+                >
+                  矩形
+                </button>
+                <button
+                  type="button"
+                  className={`xx-ce-radio-btn ${config.background.shape === "polygon" ? "active" : ""}`}
+                  onClick={() =>
+                    upd("background", {
+                      ...config.background,
+                      shape: "polygon" as const,
+                    })
+                  }
+                >
+                  圆角
+                </button>
+              </div>
+            </div>
+            <div className="xx-ce-row">
+              <label className="xx-ce-label">背景颜色</label>
+              <ColorPicker
+                value={config.background.color || "#000000"}
+                onChange={(v) => upd("background", { ...config.background, color: v })}
+              />
+            </div>
+            <div className="xx-ce-row">
+              <label className="xx-ce-label">不透明度: {config.background.opacity}%</label>
+              <Slider
+                min={0}
+                max={100}
+                step={1}
+                value={config.background.opacity}
+                onChange={(v) => upd("background", { ...config.background, opacity: v })}
+              />
+            </div>
+            <div className="xx-ce-row">
+              <label className="xx-ce-label">
+                圆角:{" "}
+                {config.background.shape === "rectangle"
+                  ? 0
+                  : Math.round((config.background.height ?? 20) / 2)}
+                px
+              </label>
+              <Slider
+                min={0}
+                max={50}
+                step={1}
+                value={
+                  config.background.shape === "rectangle"
+                    ? 0
+                    : Math.round((config.background.height ?? 20) / 2)
+                }
+                disabled={config.background.shape === "rectangle"}
+                onChange={(v) => {
+                  // 圆角近似：通过 height 控制
+                  void v
+                }}
+              />
+            </div>
+            <div className="xx-ce-row">
+              <label className="xx-ce-label">宽度: {config.background.width}%</label>
+              <Slider
+                min={20}
+                max={200}
+                step={2}
+                value={config.background.width}
+                onChange={(v) => upd("background", { ...config.background, width: v })}
+              />
+            </div>
+            <div className="xx-ce-row">
+              <label className="xx-ce-label">高度: {config.background.height}%</label>
+              <Slider
+                min={5}
+                max={80}
+                step={1}
+                value={config.background.height}
+                onChange={(v) => upd("background", { ...config.background, height: v })}
+              />
+            </div>
+            <div className="xx-ce-row">
+              <label className="xx-ce-label">上下偏移: {config.background.offsetY ?? 0}%</label>
+              <Slider
+                min={-30}
+                max={30}
+                step={1}
+                value={config.background.offsetY ?? 0}
+                onChange={(v) => upd("background", { ...config.background, offsetY: v })}
+              />
+            </div>
+          </div>
+        )}
+      </div>
     </div>
   )
 }
@@ -316,6 +444,59 @@ const CoverEditorModal: React.FC<CoverEditorModalProps> = ({ open, onClose, temp
   const portraitFileRef = useRef<HTMLInputElement>(null)
   const [bgImageUrl, setBgImageUrl] = useState<string>(initCfg.backgroundImage || "")
   const [portraitImageUrl, setPortraitImageUrl] = useState<string>(initCfg.portraitImage || "")
+  /* ── 文字拖拽状态 ── */
+  const canvasRef = useRef<HTMLDivElement | null>(null)
+  const dragRef = useRef<null | {
+    target: "title" | "subtitle"
+    startX: number
+    startY: number
+    startPosX: number
+    startPosY: number
+  }>(null)
+
+  const handleTextMouseDown = (
+    e: React.MouseEvent<HTMLDivElement>,
+    target: "title" | "subtitle",
+  ) => {
+    e.preventDefault()
+    e.stopPropagation()
+    const tc = target === "title" ? cfg.title : cfg.subtitle
+    if (!tc) return
+    dragRef.current = {
+      target,
+      startX: e.clientX,
+      startY: e.clientY,
+      startPosX: tc.position.x,
+      startPosY: tc.position.y,
+    }
+    const onMove = (ev: MouseEvent) => {
+      const d = dragRef.current
+      if (!d || !canvasRef.current) return
+      const rect = canvasRef.current.getBoundingClientRect()
+      const dx = ((ev.clientX - d.startX) / rect.width) * 100
+      const dy = ((ev.clientY - d.startY) / rect.height) * 100
+      const newX = Math.max(0, Math.min(100, d.startPosX + dx))
+      const newY = Math.max(0, Math.min(100, d.startPosY + dy))
+      if (d.target === "title") {
+        setCfg((prev) => ({
+          ...prev,
+          title: { ...prev.title, position: { x: newX, y: newY } },
+        }))
+      } else {
+        setCfg((prev) => ({
+          ...prev,
+          subtitle: { ...prev.subtitle, position: { x: newX, y: newY } },
+        }))
+      }
+    }
+    const onUp = () => {
+      dragRef.current = null
+      window.removeEventListener("mousemove", onMove)
+      window.removeEventListener("mouseup", onUp)
+    }
+    window.addEventListener("mousemove", onMove)
+    window.addEventListener("mouseup", onUp)
+  }
 
   // reset state when modal opens with a new template
   useEffect(() => {
@@ -394,19 +575,6 @@ const CoverEditorModal: React.FC<CoverEditorModalProps> = ({ open, onClose, temp
 
   const renderTextStyle = (tc: TextStyleConfig | undefined | null): React.CSSProperties => {
     if (!tc) return {}
-    // wrap text by charsPerLine
-    const rawText = tc.text || ""
-    const lines: string[] = []
-    if (tc.direction === "vertical") {
-      lines.push(rawText)
-    } else {
-      for (let i = 0; i < rawText.length; i += Math.max(1, tc.charsPerLine)) {
-        lines.push(rawText.slice(i, i + Math.max(1, tc.charsPerLine)))
-      }
-    }
-    // store rendered as lines via data attribute; for JSX we'll render outside style
-    void lines
-
     const style: React.CSSProperties = {
       position: "absolute",
       left: `${tc.position.x}%`,
@@ -422,9 +590,12 @@ const CoverEditorModal: React.FC<CoverEditorModalProps> = ({ open, onClose, temp
         tc.strokeWidth > 0 ? `${Math.max(0.5, s(tc.strokeWidth))}px ${tc.strokeColor}` : undefined,
       whiteSpace: tc.direction === "vertical" ? "pre-wrap" : "pre",
       writingMode: tc.direction === "vertical" ? "vertical-rl" : undefined,
-      zIndex: 3,
+      zIndex: 4,
       textAlign: "center",
       userSelect: "none",
+      cursor: "grab",
+      padding: 0,
+      pointerEvents: "auto",
     }
     if (tc.shadows.length > 0) {
       style.textShadow = tc.shadows
@@ -434,6 +605,39 @@ const CoverEditorModal: React.FC<CoverEditorModalProps> = ({ open, onClose, temp
     return style
   }
 
+  const renderTextBgStyle = (tc: TextStyleConfig | undefined | null): React.CSSProperties => {
+    if (!tc?.background?.enabled) return { display: "none" }
+    const bg = tc.background
+    // 背景位置跟随文字：left/top 对齐文字中心，用 offsetY（-50~50% 相对文字位置）做上下微调
+    // 这样文字拖拽时背景会自动跟随，不需要独立的位置控制
+    const radius = bg.shape === "polygon" ? `${Math.max(4, Math.round(bg.height / 4))}px` : "0"
+    const alpha = Math.max(0, Math.min(1, bg.opacity / 100))
+    const hex = (bg.color || "#000000").replace("#", "")
+    let r = 0,
+      g = 0,
+      b = 0
+    if (hex.length === 6) {
+      r = parseInt(hex.substring(0, 2), 16)
+      g = parseInt(hex.substring(2, 4), 16)
+      b = parseInt(hex.substring(4, 6), 16)
+    }
+    const rgba = `rgba(${r}, ${g}, ${b}, ${alpha})`
+    // bg.offsetY 是相对文字位置的上下偏移（-50~50，单位%画布高度），默认 0 表示与文字中心对齐
+    const offsetY = typeof bg.offsetY === "number" ? bg.offsetY : 0
+    return {
+      position: "absolute",
+      left: `${tc.position.x}%`,
+      top: `calc(${tc.position.y}% + ${offsetY}%)`,
+      width: `${bg.width}%`,
+      height: `${bg.height}%`,
+      transform: "translate(-50%, -50%)",
+      background: rgba,
+      borderRadius: radius,
+      zIndex: 3,
+      pointerEvents: "none",
+    }
+  }
+
   const renderTextLines = (tc: TextStyleConfig | undefined | null): string => {
     if (!tc) return ""
     const raw = tc.text || ""
@@ -857,7 +1061,7 @@ const CoverEditorModal: React.FC<CoverEditorModalProps> = ({ open, onClose, temp
             <span className="xx-ce-anchor-dot" style={{ top: "50%", right: "-12px" }} />
             <span className="xx-ce-anchor-dot" style={{ bottom: "10%", left: "-12px" }} />
 
-            <div className="xx-ce-canvas">
+            <div className="xx-ce-canvas" ref={canvasRef}>
               {/* base background layer */}
               <div
                 className="xx-ce-canvas-base"
@@ -914,14 +1118,29 @@ const CoverEditorModal: React.FC<CoverEditorModalProps> = ({ open, onClose, temp
                 />
               )}
 
-              {/* Title */}
+              {/* Title bg */}
+              {cfg.title?.background?.enabled && <div style={renderTextBgStyle(cfg.title)} />}
+              {/* Subtitle bg */}
+              {cfg.subtitle?.background?.enabled && <div style={renderTextBgStyle(cfg.subtitle)} />}
+
+              {/* Title (draggable) */}
               {cfg.title && (
-                <div style={renderTextStyle(cfg.title)}>{renderTextLines(cfg.title)}</div>
+                <div
+                  style={renderTextStyle(cfg.title)}
+                  onMouseDown={(e) => handleTextMouseDown(e, "title")}
+                >
+                  {renderTextLines(cfg.title)}
+                </div>
               )}
 
-              {/* Subtitle */}
+              {/* Subtitle (draggable) */}
               {cfg.subtitle && (
-                <div style={renderTextStyle(cfg.subtitle)}>{renderTextLines(cfg.subtitle)}</div>
+                <div
+                  style={renderTextStyle(cfg.subtitle)}
+                  onMouseDown={(e) => handleTextMouseDown(e, "subtitle")}
+                >
+                  {renderTextLines(cfg.subtitle)}
+                </div>
               )}
 
               {/* Mask overlay */}

apps/web/src/pages/generate/components/cover-settings/CoverSettingsModal.tsx

@@ -1,4 +1,4 @@
-import React from "react"
+import React, { useMemo, useState } from "react"
 import type { CoverTemplate } from "../../types/cover"
 import Modal from "@/components/ui/Modal"
 import Button from "@/components/ui/Button"
@@ -17,15 +17,58 @@ interface CoverSettingsModalProps {
   onCreateNew: () => void
 }
 
-const GRADIENT_MAP: Record<string, string> = {
-  default: "linear-gradient(135deg, #e0e0e0, #c0c0c0)",
-  "bold-red": "linear-gradient(135deg, #ef4444, #b91c1c)",
-  "elegant-black": "linear-gradient(135deg, #374151, #111827)",
-  "gradient-blue": "linear-gradient(135deg, #3b82f6, #1d4ed8)",
-  "gradient-purple": "linear-gradient(135deg, #8b5cf6, #6d28d9)",
-  "warm-orange": "linear-gradient(135deg, #f97316, #ea580c)",
-  "fresh-green": "linear-gradient(135deg, #22c55e, #15803d)",
-  "tech-blue": "linear-gradient(135deg, #06b6d4, #0e7490)",
+/** 模板缩略图：优先渲染 thumbnail_url；加载失败/无图时展示占位 */
+const TemplateThumb: React.FC<{ tpl: CoverTemplate; isSelected: boolean }> = ({
+  tpl,
+  isSelected,
+}) => {
+  const [errored, setErrored] = useState(false)
+  const url = tpl.thumbnail_url && !errored ? tpl.thumbnail_url : ""
+  // 随机柔和渐变做占位，保证卡片不会灰成一片
+  const placeholderBg = useMemo(() => {
+    const palettes = [
+      ["#e0e0e0", "#c0c0c0"],
+      ["#ef4444", "#b91c1c"],
+      ["#374151", "#111827"],
+      ["#3b82f6", "#1d4ed8"],
+      ["#8b5cf6", "#6d28d9"],
+      ["#f97316", "#ea580c"],
+      ["#22c55e", "#15803d"],
+      ["#06b6d4", "#0e7490"],
+    ]
+    let h = 0
+    for (const ch of tpl.id || tpl.name || "") h = (h * 31 + ch.charCodeAt(0)) >>> 0
+    const [a, b] = palettes[h % palettes.length]
+    return `linear-gradient(135deg, ${a}, ${b})`
+  }, [tpl.id, tpl.name])
+
+  return (
+    <div
+      className="xx-cover-template-thumb"
+      style={{
+        background: url ? "#000" : placeholderBg,
+        position: "relative",
+        overflow: "hidden",
+      }}
+    >
+      {isSelected && <span className="xx-cover-template-check">✓</span>}
+      {url ? (
+        <img
+          src={url}
+          alt={tpl.name}
+          onError={() => setErrored(true)}
+          style={{
+            width: "100%",
+            height: "100%",
+            objectFit: "cover",
+            display: "block",
+          }}
+        />
+      ) : (
+        <span style={{ fontSize: 28, opacity: 0.5 }}>🖼️</span>
+      )}
+    </div>
+  )
 }
 
 const CoverSettingsModal: React.FC<CoverSettingsModalProps> = ({
@@ -97,13 +140,7 @@ const CoverSettingsModal: React.FC<CoverSettingsModalProps> = ({
                 className={`xx-cover-template-card${isSelected ? " selected" : ""}`}
                 onClick={() => onSelectTemplate(tpl.id)}
               >
-                <div
-                  className="xx-cover-template-thumb"
-                  style={{ background: GRADIENT_MAP[tpl.id] || GRADIENT_MAP.default }}
-                >
-                  {isSelected && <span className="xx-cover-template-check">✓</span>}
-                  🖼️
-                </div>
+                <TemplateThumb tpl={tpl} isSelected={isSelected} />
                 <div className="xx-cover-template-info">
                   <div className="xx-cover-template-name">
                     {tpl.name}
@@ -116,7 +153,7 @@ const CoverSettingsModal: React.FC<CoverSettingsModalProps> = ({
                       onClick={() => onEditTemplate(tpl)}
                       title={tpl.is_system ? "基于此模板新建自定义模板" : "编辑模板"}
                     >
-                      {tpl.is_system ? "复制" : "编辑"}
+                      编辑
                     </Button>
                     {!tpl.is_system && (
                       <Button

apps/web/src/pages/generate/components/title/TitleMiniPreview.tsx

@@ -1,230 +1 @@
-/**
- * 标题迷你 Canvas 预览（#2001）
- *
- * 渲染一张指定宽度的小 Canvas 预览标题效果，用于：
- * - 预设卡片缩略图
- * - 样式面板顶部的实时预览
- *
- * 与 titleCanvas.ts 渲染逻辑保持一致，但：
- * - 固定分辨率（width × 宽高比约 2:1）
- * - 不调用 ffmpeg，只做视觉预览
- * - 支持背景色块、描边宽度/颜色、阴影参数化、行距、自动换行
- */
-import React, { useEffect, useRef } from "react"
-import type { TitleSettings } from "../../types"
-import { getFontFamily } from "@/components/title/constants"
-
-interface Props {
-  settings: TitleSettings
-  width?: number
-  sampleText?: string
-  /** 背景（预览用，默认深色渐变模拟视频底），transparent=true 时忽略 */
-  background?: string
-  /** 高度（可选，默认按 portrait 选比例） */
-  height?: number
-  /** 透明背景（卡片/编辑器预览叠加在图片上时使用） */
-  transparent?: boolean
-  /** 纵向竖屏预览（9:16），true 时 aspect=16/9 适配手机视频比例 */
-  portrait?: boolean
-}
-
-/** 按 maxCharsPerLine 自动换行 */
-function wrapLines(text: string, maxChars: number): string[] {
-  const manual = text
-    .split(/[/／\n]/)
-    .map((l) => l.trim())
-    .filter(Boolean)
-  if (!maxChars || maxChars <= 0) return manual
-  const out: string[] = []
-  for (const line of manual) {
-    if (line.length <= maxChars) {
-      out.push(line)
-      continue
-    }
-    let cur = ""
-    for (const ch of line) {
-      cur += ch
-      if (cur.length >= maxChars) {
-        out.push(cur)
-        cur = ""
-      }
-    }
-    if (cur) out.push(cur)
-  }
-  return out
-}
-
-const TitleMiniPreview: React.FC<Props> = ({
-  settings,
-  width = 200,
-  sampleText,
-  background = "linear-gradient(135deg,#1f2937,#111827)",
-  height,
-  transparent = false,
-  portrait = false,
-}) => {
-  const canvasRef = useRef<HTMLCanvasElement>(null)
-  const h = height ?? Math.round(width * (portrait ? 16 / 9 : 1 / 1.8))
-  const text = (sampleText || settings.title || "预览标题").trim() || "预览标题"
-
-  useEffect(() => {
-    const cvs = canvasRef.current
-    if (!cvs) return
-    const dpr = window.devicePixelRatio || 1
-    cvs.width = width * dpr
-    cvs.height = h * dpr
-    cvs.style.width = `${width}px`
-    cvs.style.height = `${h}px`
-    const ctx = cvs.getContext("2d")
-    if (!ctx) return
-    ctx.scale(dpr, dpr)
-    ctx.clearRect(0, 0, width, h)
-
-    // 背景（transparent 时跳过，用于叠加在图片上）
-    if (!transparent) {
-      ctx.fillStyle = "#111827"
-      ctx.fillRect(0, 0, width, h)
-    }
-
-    // 分辨率缩放：以 360 宽为基准（对应 720p 的一半）
-    const scale = width / 360
-    const r = (v: number) => Math.round(v * scale)
-
-    // 字体
-    const size = r(settings.size)
-    const ff = getFontFamily(settings.font)
-    const parts: string[] = []
-    if (settings.italic) parts.push("italic")
-    if (settings.bold) parts.push("bold")
-    parts.push(`${size}px`, ff)
-    ctx.font = parts.join(" ")
-    ctx.textAlign = "center"
-    ctx.textBaseline = "middle"
-    ctx.fillStyle = settings.color
-    ctx.lineJoin = "round"
-
-    // 阴影
-    const shadowEnabled = !!settings.shadow
-    const prevShadow = {
-      c: ctx.shadowColor,
-      b: ctx.shadowBlur,
-      ox: ctx.shadowOffsetX,
-      oy: ctx.shadowOffsetY,
-    }
-    if (shadowEnabled) {
-      ctx.shadowColor = settings.shadowColor ?? "rgba(0,0,0,0.8)"
-      ctx.shadowBlur = r(settings.shadowBlur ?? 4)
-      ctx.shadowOffsetX = r(settings.shadowOffsetX ?? 2)
-      ctx.shadowOffsetY = r(settings.shadowOffsetY ?? 2)
-    }
-
-    // 换行
-    const lines = wrapLines(text, settings.maxCharsPerLine ?? 0)
-    const lineH = size * (settings.lineHeight ?? 1.2)
-    const totalH = lines.length * lineH
-    let startY: number
-    if (settings.position === "top") {
-      startY = size / 2 + r(settings.marginTop ?? 24)
-    } else if (settings.position === "center") {
-      startY = h / 2 - totalH / 2 + size / 2
-    } else {
-      // bottom
-      const botMargin = portrait ? r(24) : r(16)
-      startY = h - totalH - botMargin + size / 2
-    }
-    let centerX = width / 2
-    if (settings.position === "custom" && settings.posX != null) {
-      centerX = (settings.posX / 100) * width
-    }
-
-    // 背景块
-    if (settings.bgEnabled) {
-      const pad = r(settings.bgPadding ?? 12)
-      const rad = r(settings.bgRadius ?? 8)
-      let maxLineW = 0
-      for (const l of lines) {
-        const m = ctx.measureText(l)
-        if (m.width > maxLineW) maxLineW = m.width
-      }
-      const bw = maxLineW + pad * 2
-      const bh = totalH + pad * 2
-      const bx = centerX - bw / 2
-      const by = startY - size / 2 - pad + (size - lineH) / 2
-      ctx.shadowColor = "rgba(0,0,0,0)"
-      ctx.shadowBlur = 0
-      ctx.fillStyle = settings.bgColor ?? "rgba(0,0,0,0.5)"
-      roundRect(ctx, bx, by, bw, bh, rad)
-      ctx.fill()
-      // 恢复阴影
-      if (shadowEnabled) {
-        ctx.shadowColor = settings.shadowColor ?? "rgba(0,0,0,0.8)"
-        ctx.shadowBlur = r(settings.shadowBlur ?? 4)
-        ctx.shadowOffsetX = r(settings.shadowOffsetX ?? 2)
-        ctx.shadowOffsetY = r(settings.shadowOffsetY ?? 2)
-      }
-    }
-
-    // 描边（先画，再画填充）
-    const strokeEnabled = !!settings.stroke && (settings.strokeWidth ?? 0) > 0
-    lines.forEach((line, i) => {
-      const y = startY + i * lineH
-      if (strokeEnabled) {
-        ctx.shadowColor = "rgba(0,0,0,0)"
-        ctx.shadowBlur = 0
-        ctx.lineWidth = r(settings.strokeWidth ?? 4)
-        ctx.strokeStyle = settings.strokeColor ?? "#000000"
-        ctx.strokeText(line, centerX, y)
-        // 恢复阴影
-        if (shadowEnabled) {
-          ctx.shadowColor = settings.shadowColor ?? "rgba(0,0,0,0.8)"
-          ctx.shadowBlur = r(settings.shadowBlur ?? 4)
-          ctx.shadowOffsetX = r(settings.shadowOffsetX ?? 2)
-          ctx.shadowOffsetY = r(settings.shadowOffsetY ?? 2)
-        }
-      }
-      ctx.fillText(line, centerX, y)
-    })
-
-    // 恢复
-    ctx.shadowColor = prevShadow.c
-    ctx.shadowBlur = prevShadow.b
-    ctx.shadowOffsetX = prevShadow.ox
-    ctx.shadowOffsetY = prevShadow.oy
-  }, [settings, width, h, text, transparent, portrait, background])
-
-  return (
-    <canvas
-      ref={canvasRef}
-      style={{
-        borderRadius: 6,
-        display: "block",
-        maxWidth: "100%",
-        background: transparent ? "transparent" : background,
-      }}
-    />
-  )
-}
-
-function roundRect(
-  ctx: CanvasRenderingContext2D,
-  x: number,
-  y: number,
-  w: number,
-  h: number,
-  r: number,
-) {
-  const rr = Math.min(r, w / 2, h / 2)
-  ctx.beginPath()
-  ctx.moveTo(x + rr, y)
-  ctx.lineTo(x + w - rr, y)
-  ctx.quadraticCurveTo(x + w, y, x + w, y + rr)
-  ctx.lineTo(x + w, y + h - rr)
-  ctx.quadraticCurveTo(x + w, y + h, x + w - rr, y + h)
-  ctx.lineTo(x + rr, y + h)
-  ctx.quadraticCurveTo(x, y + h, x, y + h - rr)
-  ctx.lineTo(x, y + rr)
-  ctx.quadraticCurveTo(x, y, x + rr, y)
-  ctx.closePath()
-}
-
-export default TitleMiniPreview
+export { default } from "@/components/title/TitleMiniPreview"

apps/web/src/pages/generate/components/title/TitleStylePanel.tsx

@@ -31,7 +31,7 @@ import {
 } from "@/components/title/constants"
 import { buildPresetPreviewSettings } from "@/components/title/utils"
 
-import TitleMiniPreview from "./TitleMiniPreview"
+import TitleMiniPreview from "@/components/title/TitleMiniPreview"
 import TitleTemplateEditor from "@/components/title/TitleTemplateEditor"
 import { useTitleTemplates } from "@/components/title/useTitleTemplates"
 import {
@@ -177,7 +177,7 @@ const ColorPicker: React.FC<{
 
 /* ── 卡片预览：用 ref 测量容器宽度后再渲染透明 Canvas，保证文字清晰 ── */
 const FillPreview: React.FC<{
-  settings: TitleSettings
+  settings: import("@/components/title/settings").TitleStyleSettings
   sampleText: string
   portrait?: boolean
 }> = ({ settings, sampleText, portrait }) => {

apps/web/src/pages/generate/constants.ts

@@ -46,13 +46,9 @@ export const CLIP_COUNT_STEP = 1
 export const MAX_PREVIEW_COUNT = 10
 export const MIN_PREVIEW_COUNT = 1
 
-/* ── 标题位置选项 ── */
-export const POSITION_OPTIONS = [
-  { value: "top", label: "顶部" },
-  { value: "center", label: "居中" },
-  { value: "bottom", label: "底部" },
-  { value: "custom", label: "自定义" },
-]
+/* ── 标题位置选项（统一从公共层重导出） ── */
+export { POSITION_OPTIONS } from "@/components/title/position-options"
+export type { PositionOption } from "@/components/title/position-options"
 
 /* ── 标题字体：统一使用公共层定义（#2001） ── */
 export { getFontFamily } from "@/components/title/constants"

apps/web/src/pages/generate/generate.css

@@ -3540,10 +3540,19 @@
   vertical-align: middle;
 }
 .xx-ce-font-dot--preset {
-  background: #10b981;
+  background: #10b981; /* 绿：预置爆款中文字体 */
+}
+.xx-ce-font-dot--hand {
+  background: #f59e0b; /* 橙：手写/书法字体 */
+}
+.xx-ce-font-dot--serif {
+  background: #8b5cf6; /* 紫：衬线字体 */
+}
+.xx-ce-font-dot--mono {
+  background: #6b7280; /* 灰：等宽字体 */
 }
 .xx-ce-font-dot--system {
-  background: #3b82f6;
+  background: #3b82f6; /* 蓝：系统无衬线 */
 }
 
 /* Shadow actions */
@@ -3780,7 +3789,12 @@
   align-items: center;
 }
 
-/* Canvas text elements — ensure proper stacking */
-.xx-ce-canvas > div {
+/* Canvas 装饰层（背景/装饰/遮罩/底色/人物/文字背景色块）不接收鼠标事件，
+   但拖拽的标题/副标题文字（内联 cursor:grab）需要接收 mousedown。
+   已通过 renderTextStyle 显式设 pointer-events 以外的样式，因此此处只关掉纯装饰层。 */
+.xx-ce-canvas-base,
+.xx-ce-el-bg,
+.xx-ce-el-portrait,
+.xx-ce-el-mask {
   pointer-events: none;
 }

apps/web/src/pages/generate/hooks/useBatchCovers.ts

@@ -107,54 +107,57 @@ export function useBatchCovers({
       addBusy(index)
       try {
         const titleText = titles[index] || ""
-        const response = await generateCover(selectedTemplate || "default", {
-          generated_video_id: target.id,
-          video_url: target.file_url || target.download_url || "",
-          cover_type: "ai_frame",
-          ...(titleText
-            ? {
-                title_config: {
-                  text: titleText,
-                  font: titleStyle.font,
-                  font_size: titleStyle.size,
-                  font_color: titleStyle.color,
-                  position: titleStyle.position,
-                  bold: titleStyle.bold,
-                  italic: titleStyle.italic,
-                  stroke: titleStyle.stroke
-                    ? {
-                        enabled: true,
-                        width: titleStyle.strokeWidth ?? 4,
-                        color: titleStyle.strokeColor ?? "#000000",
-                      }
-                    : { enabled: false },
-                  shadow: titleStyle.shadow
-                    ? {
-                        enabled: true,
-                        offset_x: titleStyle.shadowOffsetX ?? 2,
-                        offset_y: titleStyle.shadowOffsetY ?? 2,
-                        blur: titleStyle.shadowBlur ?? 4,
-                        color: titleStyle.shadowColor ?? "rgba(0,0,0,0.8)",
-                      }
-                    : { enabled: false },
-                  line_height: titleStyle.lineHeight ?? 1.2,
-                  margin_top: titleStyle.marginTop ?? 24,
-                  max_chars_per_line: titleStyle.maxCharsPerLine ?? 0,
-                  background: titleStyle.bgEnabled
-                    ? {
-                        enabled: true,
-                        color: titleStyle.bgColor,
-                        padding: titleStyle.bgPadding,
-                        radius: titleStyle.bgRadius,
-                      }
-                    : { enabled: false },
-                  line_overrides: (titleStyle.lineOverrides ?? []) as Array<
-                    Record<string, unknown>
-                  >,
-                },
-              }
-            : {}),
-        })
+        const response = await generateCover(
+          selectedTemplate && selectedTemplate !== "default" ? selectedTemplate : undefined,
+          {
+            generated_video_id: target.id,
+            video_url: target.file_url || target.download_url || "",
+            cover_type: "ai_frame",
+            ...(titleText
+              ? {
+                  title_config: {
+                    text: titleText,
+                    font: titleStyle.font,
+                    font_size: titleStyle.size,
+                    font_color: titleStyle.color,
+                    position: titleStyle.position,
+                    bold: titleStyle.bold,
+                    italic: titleStyle.italic,
+                    stroke: titleStyle.stroke
+                      ? {
+                          enabled: true,
+                          width: titleStyle.strokeWidth ?? 4,
+                          color: titleStyle.strokeColor ?? "#000000",
+                        }
+                      : { enabled: false },
+                    shadow: titleStyle.shadow
+                      ? {
+                          enabled: true,
+                          offset_x: titleStyle.shadowOffsetX ?? 2,
+                          offset_y: titleStyle.shadowOffsetY ?? 2,
+                          blur: titleStyle.shadowBlur ?? 4,
+                          color: titleStyle.shadowColor ?? "rgba(0,0,0,0.8)",
+                        }
+                      : { enabled: false },
+                    line_height: titleStyle.lineHeight ?? 1.2,
+                    margin_top: titleStyle.marginTop ?? 24,
+                    max_chars_per_line: titleStyle.maxCharsPerLine ?? 0,
+                    background: titleStyle.bgEnabled
+                      ? {
+                          enabled: true,
+                          color: titleStyle.bgColor,
+                          padding: titleStyle.bgPadding,
+                          radius: titleStyle.bgRadius,
+                        }
+                      : { enabled: false },
+                    line_overrides: (titleStyle.lineOverrides ?? []) as Array<
+                      Record<string, unknown>
+                    >,
+                  },
+                }
+              : {}),
+          },
+        )
         const url = response.cover?.image_url || response.cover?.thumbnail_url || ""
         if (url) {
           patchCover(index, url)

apps/web/src/pages/generate/hooks/useGenerateVideo.ts

@@ -22,6 +22,8 @@ export function useGenerateVideo(props: UseGenerateVideoProps) {
   const [generated, setGenerated] = useState(false)
   const [generateError, setGenerateError] = useState<string | null>(null)
   const [generatedVideos, setGeneratedVideos] = useState<GeneratedVideo[]>([])
+  /** 单视频模式：当前任务 ID（封面 finalize 需要） */
+  const [currentTaskId, setCurrentTaskId] = useState<string>("")
   /** 批量模式：每个正式生成任务的独立状态（第5步逐卡片展示） */
   const [batchTasks, setBatchTasks] = useState<BatchTaskState[]>([])
 
@@ -120,6 +122,8 @@ export function useGenerateVideo(props: UseGenerateVideoProps) {
     setGenerated(false)
     setGenerateError(null)
     setBatchTasks([])
+    setGeneratedVideos([])
+    setCurrentTaskId("")
     clearTimer()
 
     try {
@@ -341,8 +345,10 @@ export function useGenerateVideo(props: UseGenerateVideoProps) {
         }
         if (taskIds.length > 1) {
           // 批量：任务按创建顺序与勾选变体一一对应（后端按 count 顺序创建）
+          setCurrentTaskId("")
           startPollingBatch(taskIds.map((taskId, i) => ({ taskId, variantIndex: indexes[i] ?? i })))
         } else {
+          setCurrentTaskId(taskIds[0])
           startPolling(taskIds[0])
         }
       } catch (err) {
@@ -417,6 +423,7 @@ export function useGenerateVideo(props: UseGenerateVideoProps) {
     generated,
     generateError,
     generatedVideos,
+    currentTaskId,
     generate,
     retry,
     retryBatchTask,

apps/web/src/pages/generate/hooks/useStepNavigation.ts

@@ -4,7 +4,7 @@
  *
  * - 步骤1（选择模式）：下一步分支由外层弹窗处理（VoiceSelectModal / ScriptSelectModal），
  *   本 hook 的 goNext 仅在未选模式时拦截；外层 Modal onConfirm 里主动 setCurrentStep(2)。
- * - 步骤2（选择素材）：弹数量选择弹窗（PreviewCountModal），确认后跳步骤3。
+ * - 步骤2（选择素材）：直接进入步骤3，数组长度对齐由 onBeforeEnterStep3 保证。
  * - 步骤3 底部按钮是「确认生成视频」（由 GenerateStepActions 调 onConfirmGenerate），
  *   创建成功后跳步骤4；本 hook 的 goNext 只负责 2→3 和 4→5 的「下一步」。
  * - 步骤4（确认生成进度页）：全部渲染完成后「下一步」解锁进封面。
@@ -23,10 +23,10 @@ export interface UseStepNavigationOptions {
   titleSettings: TitleSettings
   /** 是否已完成视频生成（步骤4全部渲染完成后才能进入封面） */
   generated: boolean
-  /** 点素材下一步时弹出数量选择弹窗 */
-  onOpenCountModal: () => void
   /** 步骤1下一步：根据 editMode 打开对应弹窗（随机→配音 / 叙事→文案） */
   onOpenStep1Modal: () => void
+  /** 进入步骤3前自动对齐数组（previewTitles/voiceLibraryIds/previewCovers/selectedVariantIds）长度到 previewCount */
+  onBeforeEnterStep3?: () => void
 }
 
 export interface UseStepNavigationReturn {
@@ -42,8 +42,8 @@ export const useStepNavigation = (options: UseStepNavigationOptions): UseStepNav
     selectedMaterials,
     smartSelectedIds,
     generated,
-    onOpenCountModal,
     onOpenStep1Modal,
+    onBeforeEnterStep3,
   } = options
 
   const goNext = () => {
@@ -62,8 +62,9 @@ export const useStepNavigation = (options: UseStepNavigationOptions): UseStepNav
         message.warning("请先进行智能匹配并选择素材")
         return
       }
-      // 弹数量选择弹窗
-      onOpenCountModal()
+      // 直接进入步骤3（生成数量在 Step1 已设置）；对齐数组长度
+      onBeforeEnterStep3?.()
+      setCurrentStep(3)
       return
     }
     // 步骤4（确认生成）：全部渲染完成后才能下一步进封面

apps/web/src/pages/generate/types/cover.ts

@@ -63,9 +63,8 @@ export interface TextBackground {
   shape: TextBgShape
   width: number
   height: number
-  posX: number
-  posY: number
-  rotation: number
+  /** 相对文字的上下偏移（百分比），背景自动跟随文字位置 */
+  offsetY: number
 }
 
 /** 文字样式配置（主标题/副标题共用） */
@@ -154,9 +153,7 @@ export const DEFAULT_TITLE_CONFIG: TextStyleConfig = {
     shape: "polygon",
     width: 30,
     height: 10,
-    posX: 50,
-    posY: 50,
-    rotation: 0,
+    offsetY: 0,
   },
 }
 
@@ -184,9 +181,7 @@ export const DEFAULT_SUBTITLE_CONFIG: TextStyleConfig = {
     shape: "rectangle",
     width: 100,
     height: 20,
-    posX: 50,
-    posY: 80,
-    rotation: 0,
+    offsetY: 8,
   },
 }
 
@@ -222,46 +217,89 @@ export const DEFAULT_EDITOR_CONFIG: CoverEditorConfig = {
   maskShape: "矩形",
 }
 
-/** 预置字体 */
-export const PRESET_FONTS = [
-  { name: "思源黑体", family: "'Noto Sans SC', sans-serif" },
-  { name: "斗鱼追光体2.0", family: "'DouYu ZhuangGuangTi', sans-serif" },
-  { name: "抖音美好体", family: "'DouYin MeiHaoTi', sans-serif" },
+/** 预置字体（已与 @/components/title/constants 字体表保持一致；自定义商业字体兜底 Google Fonts 开源中文字体） */
+// 封面编辑器预置字体：与标题样式字体列表保持一致（从 @/components/title/constants 同步），
+// 并补全西文常用系统字体，保证在中英文环境下都有可用字体。
+// 注：需要配合 index.html 引入的 Google Fonts（Noto Sans SC / ZCOOL / Ma Shan Zheng 等）。
+export interface CoverFont {
+  name: string
+  family: string
+  tag?: "preset" | "hand" | "serif" | "sans" | "mono"
+}
+
+/** 预置中文字体（爆款/常用） */
+export const PRESET_FONTS: CoverFont[] = [
+  {
+    name: "优设标题黑",
+    family:
+      '"YouSheBiaoTiHei","ZCOOL QingKe HuangYou","Noto Sans SC","PingFang SC","Microsoft YaHei",sans-serif',
+    tag: "preset",
+  },
+  {
+    name: "阿里普惠体Bold",
+    family:
+      '"Alibaba PuHuiTi","Alibaba Sans","Noto Sans SC","PingFang SC","Microsoft YaHei",sans-serif',
+    tag: "preset",
+  },
+  {
+    name: "抖音美好体",
+    family:
+      '"Douyin Sans","ZCOOL KuaiLe","Noto Sans SC","PingFang SC","Microsoft YaHei",sans-serif',
+    tag: "preset",
+  },
+  {
+    name: "思源黑体Heavy",
+    family: '"Noto Sans SC","Source Han Sans SC Heavy","PingFang SC","Microsoft YaHei",sans-serif',
+    tag: "preset",
+  },
+  {
+    name: "思源黑体",
+    family: '"Noto Sans SC","Source Han Sans SC","PingFang SC","Microsoft YaHei",sans-serif',
+    tag: "preset",
+  },
+  {
+    name: "思源宋体",
+    family: '"Noto Serif SC","Source Han Serif SC","Songti SC","SimSun",serif',
+    tag: "serif",
+  },
+  { name: "站酷小薇体", family: '"ZCOOL XiaoWei","Noto Serif SC",serif', tag: "preset" },
+  { name: "马善政毛笔", family: '"Ma Shan Zheng","STXingkai","KaiTi",cursive', tag: "hand" },
+  { name: "龙藏体", family: '"Long Cang","STXingkai",cursive', tag: "hand" },
+  { name: "楷体", family: '"KaiTi","STKaiti","DFKai-SB",serif', tag: "serif" },
+  {
+    name: "苹方",
+    family: '"PingFang SC",-apple-system,"Helvetica Neue",sans-serif',
+    tag: "sans",
+  },
+  {
+    name: "微软雅黑",
+    family: '"Microsoft YaHei","PingFang SC","Noto Sans SC",sans-serif',
+    tag: "sans",
+  },
 ]
 
-/** 系统字体 */
-export const SYSTEM_FONTS = [
-  { name: "Arial", family: "Arial, sans-serif" },
-  { name: "Helvetica", family: "Helvetica, sans-serif" },
-  { name: "Times New Roman", family: "'Times New Roman', serif" },
-  { name: "Georgia", family: "Georgia, serif" },
-  { name: "Verdana", family: "Verdana, sans-serif" },
-  { name: "Tahoma", family: "Tahoma, sans-serif" },
-  { name: "Impact", family: "Impact, sans-serif" },
-  { name: "Comic Sans MS", family: "'Comic Sans MS', cursive" },
-  { name: "Courier New", family: "'Courier New', monospace" },
-  { name: "微软雅黑", family: "'Microsoft YaHei', sans-serif" },
-  { name: "宋体", family: "SimSun, serif" },
-  { name: "黑体", family: "SimHei, sans-serif" },
-  { name: "楷体", family: "KaiTi, serif" },
-  { name: "仿宋", family: "FangSong, serif" },
-  { name: "Trebuchet MS", family: "'Trebuchet MS', sans-serif" },
-  { name: "Lucida Console", family: "'Lucida Console', monospace" },
-  { name: "Palatino", family: "Palatino, serif" },
-  { name: "Garamond", family: "Garamond, serif" },
-  { name: "Bookman", family: "Bookman, serif" },
-  { name: "Avant Garde", family: "'Avant Garde', sans-serif" },
-  { name: "Calibri", family: "Calibri, sans-serif" },
-  { name: "Cambria", family: "Cambria, serif" },
-  { name: "Candara", family: "Candara, sans-serif" },
-  { name: "Consolas", family: "Consolas, monospace" },
-  { name: "Constantia", family: "Constantia, serif" },
-  { name: "Corbel", family: "Corbel, sans-serif" },
-  { name: "Franklin Gothic", family: "'Franklin Gothic', sans-serif" },
-  { name: "Gill Sans", family: "'Gill Sans', sans-serif" },
-  { name: "Optima", family: "Optima, sans-serif" },
-  { name: "Futura", family: "Futura, sans-serif" },
-  { name: "Rockwell", family: "Rockwell, serif" },
+/** 系统字体（西文 + 通用中文） */
+export const SYSTEM_FONTS: CoverFont[] = [
+  { name: "Arial", family: "Arial, Helvetica, sans-serif", tag: "sans" },
+  { name: "Helvetica", family: "Helvetica, Arial, sans-serif", tag: "sans" },
+  { name: "Times New Roman", family: '"Times New Roman", Times, serif', tag: "serif" },
+  { name: "Georgia", family: "Georgia, serif", tag: "serif" },
+  { name: "Verdana", family: "Verdana, Geneva, sans-serif", tag: "sans" },
+  { name: "Tahoma", family: "Tahoma, Geneva, sans-serif", tag: "sans" },
+  { name: "Impact", family: 'Impact, "Arial Black", sans-serif', tag: "sans" },
+  { name: "Comic Sans MS", family: '"Comic Sans MS", cursive', tag: "hand" },
+  { name: "Courier New", family: '"Courier New", Courier, monospace', tag: "mono" },
+  { name: "宋体", family: "SimSun, 'Noto Serif SC', serif", tag: "serif" },
+  { name: "黑体", family: "SimHei, 'Noto Sans SC', sans-serif", tag: "sans" },
+  { name: "仿宋", family: "FangSong, 'Noto Serif SC', serif", tag: "serif" },
+  { name: "Trebuchet MS", family: '"Trebuchet MS", sans-serif', tag: "sans" },
+  { name: "Lucida Console", family: '"Lucida Console", Monaco, monospace', tag: "mono" },
+  { name: "Palatino", family: 'Palatino, "Palatino Linotype", serif', tag: "serif" },
+  { name: "Garamond", family: "Garamond, serif", tag: "serif" },
+  { name: "Calibri", family: "Calibri, sans-serif", tag: "sans" },
+  { name: "Cambria", family: "Cambria, serif", tag: "serif" },
+  { name: "Candara", family: "Candara, sans-serif", tag: "sans" },
+  { name: "Consolas", family: "Consolas, monospace", tag: "mono" },
 ]
 
 /** 所有字体列表 */

apps/web/src/test/components/title/titleUtils.test.ts

@@ -0,0 +1,190 @@
+/**
+ * 标题工具函数单测 — 提升覆盖率到 50% 阈值以上
+ */
+import { describe, it, expect } from "vitest"
+import {
+  titleStyleConfigToCamel,
+  camelToTitleStyleConfig,
+  buildPresetPreviewSettings,
+  templateToPreviewSettings,
+} from "@/components/title/utils"
+import {
+  getFontFamily,
+  getTitlePreset,
+  TITLE_PRESETS,
+  FONT_OPTIONS,
+} from "@/components/title/constants"
+import { DEFAULT_TITLE_SETTINGS_FULL } from "@/pages/generate/types"
+import type { TitleStyleConfig } from "@/components/title/types"
+import type { TitleTemplate } from "@/components/title/template-types"
+
+describe("getFontFamily", () => {
+  it("已知字体名返回对应 family 栈", () => {
+    const f = getFontFamily("思源黑体")
+    expect(f).toContain("Noto Sans SC")
+  })
+
+  it("未知字体名回退到思源黑体", () => {
+    const f = getFontFamily("not-exist-font")
+    expect(f).toBe(FONT_OPTIONS[4].family)
+  })
+
+  it("新增书法字体能查到", () => {
+    expect(getFontFamily("马善政毛笔")).toContain("Ma Shan Zheng")
+    expect(getFontFamily("站酷小薇体")).toContain("ZCOOL XiaoWei")
+  })
+})
+
+describe("getTitlePreset", () => {
+  it("合法 key 返回对应 preset", () => {
+    const p = getTitlePreset(TITLE_PRESETS[0].key)
+    expect(p).toBeDefined()
+    expect(p?.key).toBe(TITLE_PRESETS[0].key)
+  })
+
+  it("不存在的 key 返回 undefined", () => {
+    expect(getTitlePreset("__not_exist__")).toBeUndefined()
+  })
+})
+
+describe("titleStyleConfigToCamel", () => {
+  it("snake_case 字段映射到 camelCase", () => {
+    const cfg: Partial<TitleStyleConfig> = {
+      font: "思源黑体",
+      size: 48,
+      pos_x: 10,
+      pos_y: 20,
+      line_height: 1.4,
+      margin_top: 30,
+      max_chars_per_line: 8,
+      stroke_width: 4,
+      stroke_color: "#000",
+      shadow_offset_x: 2,
+      bg_enabled: true,
+      bg_padding: 12,
+      bg_radius: 6,
+    }
+    const out = titleStyleConfigToCamel(cfg)
+    expect(out.font).toBe("思源黑体")
+    expect(out.size).toBe(48)
+    expect(out.posX).toBe(10)
+    expect(out.posY).toBe(20)
+    expect(out.lineHeight).toBe(1.4)
+    expect(out.marginTop).toBe(30)
+    expect(out.maxCharsPerLine).toBe(8)
+    expect(out.strokeWidth).toBe(4)
+    expect(out.strokeColor).toBe("#000")
+    expect(out.shadowOffsetX).toBe(2)
+    expect(out.bgEnabled).toBe(true)
+    expect(out.bgPadding).toBe(12)
+    expect(out.bgRadius).toBe(6)
+  })
+
+  it("空对象返回空对象", () => {
+    expect(titleStyleConfigToCamel({})).toEqual({})
+  })
+})
+
+describe("camelToTitleStyleConfig", () => {
+  it("camelCase 字段映射到 snake_case", () => {
+    const out = camelToTitleStyleConfig({
+      font: "思源宋体",
+      size: 36,
+      posX: 5,
+      posY: 15,
+      strokeWidth: 2,
+      shadowBlur: 8,
+      bgEnabled: false,
+    })
+    expect(out.font).toBe("思源宋体")
+    expect(out.pos_x).toBe(5)
+    expect(out.pos_y).toBe(15)
+    expect(out.stroke_width).toBe(2)
+    expect(out.shadow_blur).toBe(8)
+    expect(out.bg_enabled).toBe(false)
+  })
+
+  it("两种转换在已知字段上往返一致", () => {
+    const camel = {
+      font: "优设标题黑",
+      size: 56,
+      color: "#ffffff",
+      stroke: true,
+      strokeWidth: 6,
+      bold: true,
+      shadow: true,
+      shadowOffsetX: 3,
+      shadowOffsetY: 3,
+      shadowBlur: 10,
+      bgEnabled: true,
+      bgColor: "#000000",
+      bgPadding: 16,
+      bgRadius: 8,
+    } as const
+    const snake = camelToTitleStyleConfig({ ...camel })
+    const back = titleStyleConfigToCamel(snake)
+    for (const k of Object.keys(camel) as (keyof typeof camel)[]) {
+      expect(back[k]).toBe(camel[k])
+    }
+  })
+})
+
+describe("buildPresetPreviewSettings", () => {
+  it("未知 preset key 返回 base", () => {
+    const base = { ...DEFAULT_TITLE_SETTINGS_FULL, size: 32 }
+    const out = buildPresetPreviewSettings(base, "__no_such_preset__")
+    expect(out).toBe(base)
+  })
+
+  it("合法 preset 返回固定字号并缩放描边/阴影/padding", () => {
+    const key = TITLE_PRESETS[0].key
+    const out = buildPresetPreviewSettings(DEFAULT_TITLE_SETTINGS_FULL, key, 56)
+    expect(out.size).toBe(56)
+    expect(Array.isArray(out.lineOverrides)).toBe(true)
+  })
+})
+
+describe("templateToPreviewSettings", () => {
+  it("按模板 style 合并默认值，固定字号并缩放装饰尺寸", () => {
+    const tpl: TitleTemplate = {
+      id: "tpl-test",
+      name: "测试模板",
+      category: "test",
+      thumbnail_url: "",
+      is_system: true,
+      style: {
+        font: "思源黑体",
+        size: 72,
+        color: "#ffd700",
+        stroke: true,
+        stroke_width: 8,
+        shadow: true,
+        shadow_offset_x: 4,
+        shadow_offset_y: 4,
+        shadow_blur: 12,
+        bg_enabled: false,
+        bg_padding: 24,
+        bg_radius: 0,
+      },
+    }
+    const out = templateToPreviewSettings(tpl, 48)
+    expect(out.size).toBe(48)
+    expect(out.color).toBe("#ffd700")
+    expect(out.strokeWidth).toBe(Math.max(1, Math.round((48 / 72) * 8)))
+    expect(out.shadowBlur).toBe(Math.round((48 / 72) * 12))
+    expect(Array.isArray(out.lineOverrides)).toBe(true)
+  })
+
+  it("模板未指定 size 时使用默认 size（不触发缩放）", () => {
+    const tpl: TitleTemplate = {
+      id: "tpl-no-size",
+      name: "无字号模板",
+      category: "test",
+      thumbnail_url: "",
+      is_system: false,
+      style: { font: "思源黑体" },
+    }
+    const out = templateToPreviewSettings(tpl, 48)
+    expect(out.size).toBeDefined()
+  })
+})

apps/web/src/test/pages/generate/smoke.test.tsx

@@ -20,7 +20,6 @@ import "@/pages/generate/components/Step4TitleSettings"
 import "@/pages/generate/components/Step5VoiceSelect"
 import "@/pages/generate/components/Step3VoiceWithMode"
 import "@/pages/generate/components/BatchGenerationGrid"
-import "@/pages/generate/components/PreviewCountModal"
 import "@/pages/generate/components/GenerateStepContent"
 import "@/pages/generate/components/voice/VoiceRecommendSection"
 import "@/pages/generate/components/voice/VoiceChoiceCard"

apps/worker/video_processing/oss_helpers.py

@@ -337,3 +337,24 @@ def resolve_asset_ids_to_paths(
         if local_path:
             result[aid] = local_path
     return result
+
+
+def delete_from_oss(storage_key_or_url: str) -> bool:
+    """从 OSS 删除对象（best-effort 清理临时文件，失败不抛异常）。
+
+    Args:
+        storage_key_or_url: 存储键或完整 URL
+
+    Returns:
+        True 删除成功，False 删除失败或未配置。
+    """
+    bucket = oss_bucket()
+    if bucket is None:
+        return False
+    try:
+        key = normalize_storage_key(storage_key_or_url)
+        bucket.delete_object(key)
+        return True
+    except Exception:
+        logger.exception("删除OSS对象失败: %s", storage_key_or_url[:80])
+        return False

apps/worker/video_processing/thumbnail_generator.py

@@ -221,7 +221,7 @@ def _extract_frames_via_mediakit(
     """
     import uuid
 
-    from video_processing.oss_helpers import upload_to_oss
+    from video_processing.oss_helpers import get_signed_download_url, upload_to_oss
 
     from packages.shared.mediakit_client import get_mediakit_client
 
@@ -230,14 +230,17 @@ def _extract_frames_via_mediakit(
         logger.info("[thumbnail] MediaKit 未配置，跳过智能抽帧")
         return None
 
-    # 1. 上传视频到 OSS 获取 URL
+    video_storage_key: str = ""
+    # 1. 上传视频到 OSS，并生成预签名下载 URL（bucket 私有读，公网 URL 会 403）
     try:
         video_storage_key = f"temp/{plan_id}/{uuid.uuid4().hex[:8]}_{Path(video_path).name}"
-        video_url = upload_to_oss(video_path, video_storage_key)
-        if not video_url:
+        public_url = upload_to_oss(video_path, video_storage_key)
+        if not public_url:
             logger.warning("[thumbnail] 视频上传 OSS 失败，无法使用 MediaKit")
             return None
-        logger.info("[thumbnail] 视频已上传 OSS: %s", video_url[:80])
+        # MediaKit 从公网拉取视频，必须使用预签名 URL；签名 1h 足够完成抽帧
+        video_url = get_signed_download_url(video_storage_key, expires_seconds=3600) or public_url
+        logger.info("[thumbnail] 视频已上传 OSS 并生成签名 URL: key=%s", video_storage_key[:80])
     except Exception as e:
         logger.warning("[thumbnail] 视频上传 OSS 异常: %s，降级到 ffmpeg", e)
         return None

apps/worker/video_processing/unified_render_service.py

@@ -63,6 +63,7 @@ from packages.domain.render_layer_utils import clip_playback_speed as _clip_play
 from packages.domain.render_layer_utils import estimate_total_duration as _estimate_total_duration_pure
 from packages.domain.render_layer_utils import resolve_layer_role as _resolve_layer_role_pure
 from packages.domain.tts_config import TtsConfig
+from packages.shared.gpu_encoder import GpuEncodeError, get_gpu_encoder
 
 logger = logging.getLogger(__name__)
 
@@ -1621,20 +1622,27 @@ class UnifiedRenderService:
             effective_duration,
             has_audio,
         )
-        try:
-            run_ffmpeg(command)
-        except subprocess.CalledProcessError as e:
-            stderr_text = (e.stderr or "").strip()
-            stderr_tail = stderr_text[-1500:] if len(stderr_text) > 1500 else stderr_text
-            logger.error(
-                "直通渲染失败: plan_id=%s clip=%s exit_code=%d\nvf=%s\nstderr(last 1500):\n%s",
-                self.plan.id,
-                clip.clip_id,
-                e.returncode,
-                vf_str[:2000],
-                stderr_tail,
-            )
-            raise
+        # 尝试 GPU NVENC 加速
+        gpu_ok = False
+        if self._gpu_encode_available():
+            mezz_path = output_path.parent / f".{output_path.stem}.mezz{output_path.suffix}"
+            gpu_ok = self._ffmpeg_output_to_mezzanine(command, mezz_path, output_path)
+
+        if not gpu_ok:
+            try:
+                run_ffmpeg(command)
+            except subprocess.CalledProcessError as e:
+                stderr_text = (e.stderr or "").strip()
+                stderr_tail = stderr_text[-1500:] if len(stderr_text) > 1500 else stderr_text
+                logger.error(
+                    "直通渲染失败: plan_id=%s clip=%s exit_code=%d\nvf=%s\nstderr(last 1500):\n%s",
+                    self.plan.id,
+                    clip.clip_id,
+                    e.returncode,
+                    vf_str[:2000],
+                    stderr_tail,
+                )
+                raise
 
         return has_audio
 
@@ -2170,6 +2178,124 @@ class UnifiedRenderService:
         filter_complex = ";".join(filter_parts)
         return filter_complex, input_args
 
+    # ── GPU NVENC 加速 ────────────────────────────────────────────────────
+
+    def _gpu_encode_available(self) -> bool:
+        """GPU 编码客户端是否已配置且健康（缓存健康状态，单任务内只探测一次）。"""
+        if not getattr(self, "_gpu_health_ok", None):
+            client = get_gpu_encoder()
+            if client is None:
+                self._gpu_health_ok = False
+                return False
+            try:
+                health = client.check_health()
+                if health.ready:
+                    logger.info(
+                        "[gpu-encoder] healthy endpoint=%s gpu=%s",
+                        client.endpoint,
+                        health.gpu_name,
+                    )
+                    self._gpu_health_ok = True
+                else:
+                    logger.warning(
+                        "[gpu-encoder] not ready: %s (endpoint=%s)",
+                        health.error,
+                        client.endpoint,
+                    )
+                    self._gpu_health_ok = False
+            except Exception as e:  # noqa: BLE001
+                logger.warning("[gpu-encoder] health probe error (CPU fallback): %s", e)
+                self._gpu_health_ok = False
+        return self._gpu_health_ok
+
+    def _ffmpeg_output_to_mezzanine(
+        self,
+        base_command: list[str],
+        mezzanine_path: Path,
+        output_path: Path,
+    ) -> bool:
+        """用 CPU ultrafast 把滤镜链输出到 mezzanine_path，然后调 GPU 做最终编码。
+
+        base_command: 原本要执行的完整 ffmpeg 命令（含 -c:v libx264 -crf X -preset Y ... output_path）
+        我们把最后一个参数（output_path）替换成 mezzanine_path，并把编码参数改成 ultrafast，
+        成功后调用 gpu_encoder 做 nvenc 编码到 output_path。
+
+        任何失败返回 False，调用方走原始 CPU 路径。
+        """
+        client = get_gpu_encoder()
+        if client is None:
+            return False
+
+        # 构造 mezzanine 命令：替换编码参数和输出路径
+        mezz_cmd = list(base_command)
+        # 找到编码参数位置并替换
+        try:
+            i_crf = mezz_cmd.index("-crf")
+            mezz_cmd[i_crf + 1] = "20"
+            i_preset = mezz_cmd.index("-preset")
+            mezz_cmd[i_preset + 1] = "ultrafast"
+        except ValueError:
+            logger.warning("[gpu-encoder] could not find -crf/-preset in command, skip gpu")
+            return False
+
+        # 如果命令有音频编码 -c:a aac，我们保留音频让 GPU 侧不用单独处理
+        # （P4000 的 ffmpeg_args 可以直接 copy 音频？这里简单起见：把音频编码留在 mezzanine，
+        # 然后 GPU 侧直接 -c:a copy，避免重编码损失）
+        has_audio = "-c:a" in mezz_cmd
+
+        # 替换输出路径（最后一个参数）
+        mezz_cmd[-1] = str(mezzanine_path)
+
+        # 1) 跑 mezzanine
+        mezzanine_path.parent.mkdir(parents=True, exist_ok=True)
+        t0 = time.time()
+        try:
+            run_ffmpeg(mezz_cmd)
+        except subprocess.CalledProcessError as e:
+            logger.warning("[gpu-encoder] mezzanine encode failed (CPU fallback): %s", e)
+            return False
+        logger.info(
+            "[gpu-encoder] mezzanine ready: %s (%.1fs, %d bytes), dispatching to P4000 nvenc...",
+            mezzanine_path.name,
+            time.time() - t0,
+            mezzanine_path.stat().st_size if mezzanine_path.exists() else 0,
+        )
+
+        # 2) GPU nvenc encode（含上传 mezzanine → OSS → P4000 下载+编码 → relay 回传）
+        try:
+            # GPU 侧：-i in.mp4 -c:v h264_nvenc ... 音频 copy（mezzanine 里音频已是 aac）
+            audio_args = ["-c:a", "copy"] if has_audio else None
+            client.encode_mezzanine_to_output(
+                mezzanine_path,
+                output_path,
+                audio_args=audio_args,
+            )
+            logger.info(
+                "[gpu-encoder] GPU nvenc encode done: %s (total %.1fs)",
+                output_path.name,
+                time.time() - t0,
+            )
+            return True
+        except GpuEncodeError as e:
+            logger.warning("[gpu-encoder] GPU encode failed (CPU fallback): %s", e)
+            # 删除可能残留的不完整 output
+            try:
+                if output_path.exists():
+                    output_path.unlink()
+            except OSError:
+                pass
+            return False
+        except Exception as e:  # noqa: BLE001
+            logger.warning("[gpu-encoder] GPU encode unexpected error (CPU fallback): %s", e)
+            return False
+        finally:
+            # 清理 mezzanine
+            try:
+                if mezzanine_path.exists():
+                    mezzanine_path.unlink()
+            except OSError:
+                pass
+
     def _execute_ffmpeg(
         self,
         filter_complex: str,
@@ -2209,20 +2335,28 @@ class UnifiedRenderService:
             input_args.count("-i"),
             output_path,
         )
-        try:
-            run_ffmpeg(command)
-        except subprocess.CalledProcessError as e:
-            # 额外记录 filter_complex + stderr，方便排查滤镜链构建问题
-            stderr_text = (e.stderr or "").strip()
-            stderr_tail = stderr_text[-1500:] if len(stderr_text) > 1500 else stderr_text
-            logger.error(
-                "渲染失败: plan_id=%s exit_code=%d\nfilter_complex:\n%s\nstderr(last 1500):\n%s",
-                self.plan.id,
-                e.returncode,
-                filter_complex[:5000],
-                stderr_tail,
-            )
-            raise
+
+        # 尝试 GPU NVENC 加速：先出 ultrafast mezzanine，再交给 P4000 做最终编码
+        gpu_ok = False
+        if self._gpu_encode_available():
+            mezz_path = output_path.parent / f".{output_path.stem}.mezz{output_path.suffix}"
+            gpu_ok = self._ffmpeg_output_to_mezzanine(command, mezz_path, output_path)
+
+        if not gpu_ok:
+            try:
+                run_ffmpeg(command)
+            except subprocess.CalledProcessError as e:
+                # 额外记录 filter_complex + stderr，方便排查滤镜链构建问题
+                stderr_text = (e.stderr or "").strip()
+                stderr_tail = stderr_text[-1500:] if len(stderr_text) > 1500 else stderr_text
+                logger.error(
+                    "渲染失败: plan_id=%s exit_code=%d\nfilter_complex:\n%s\nstderr(last 1500):\n%s",
+                    self.plan.id,
+                    e.returncode,
+                    filter_complex[:5000],
+                    stderr_tail,
+                )
+                raise
 
     def _build_sticker_filters(self, input_label: str, output_label: str) -> tuple[str, list[str]]:
         """构建贴纸叠加滤镜链.

apps/worker/worker_app/celery_app.py

@@ -76,4 +76,10 @@ celery_app.conf.beat_schedule = {
         "schedule": 600.0,  # 每 10 分钟（秒）
         "options": {"expires": 540},
     },
+    # 音色克隆卡死巡检：worker 重启/消息丢失后 processing 卡 10 分钟标 failed，用户可点重试
+    "cleanup-stale-voice-clones": {
+        "task": "worker.cleanup_stale_voice_clones",
+        "schedule": 300.0,  # 每 5 分钟
+        "options": {"expires": 240},
+    },
 }

apps/worker/worker_app/tasks/_startup.py

@@ -287,3 +287,80 @@ def _recover_stuck_ingest_jobs_on_ready(sender, **kwargs):  # pragma: no cover
         logger.info("Worker 启动 ingest 恢复完成，共重新派单 %d 个卡死任务", recovered)
     except Exception as e:  # noqa: BLE001 — 启动恢复失败不能阻断 worker 起服
         logger.error("启动 ingest 恢复扫描失败（beat 巡检仍会兜底标 failed）: %s", e, exc_info=True)
+
+
+def recover_stale_voice_clones_on_startup(timeout_minutes: int = 10) -> int:
+    """Worker 启动时恢复卡死在 processing 的音色克隆任务。
+
+    容器重启/进程 OOM 时 worker 中正在轮询的克隆任务会丢失，
+    voice_clone_profiles 永久卡在 processing 无兜底。启动时扫描
+    updated_at 超过 timeout_minutes 的 processing 记录，直接标记
+    为 failed（错误信息指引用户重试）。选择标 failed 而非重新派单，
+    因为 CosyVoice 侧的 voice_id 无法在无上下文下恢复轮询，重试需
+    用户确认后显式触发。
+
+    Args:
+        timeout_minutes: 判定卡死的阈值，默认 10 分钟
+
+    Returns:
+        恢复的记录数
+    """
+    from packages.adapters.sqlalchemy_impl.voice_clone_profile_repository import (
+        SQLAlchemyVoiceCloneProfileRepository,
+    )
+
+    try:
+        session = SessionLocal()
+        try:
+            repo = SQLAlchemyVoiceCloneProfileRepository(session)
+            count = repo.cleanup_stale_processing(timeout_minutes)
+        finally:
+            session.close()
+        if count > 0:
+            logger.warning("启动时恢复了 %d 个卡死在 processing 的音色克隆（超时 %d 分钟）", count, timeout_minutes)
+        else:
+            logger.info("无卡死 processing 音色克隆需要恢复")
+        return count
+    except Exception as e:
+        logger.error("启动时音色克隆恢复扫描失败（beat 巡检仍会兜底）: %s", e, exc_info=True)
+        return 0
+
+
+@worker_ready.connect
+def _recover_stuck_voice_clones_on_ready(sender, **kwargs):
+    """Worker 启动完成后恢复卡死的音色克隆任务。"""
+    try:
+        recovered = recover_stale_voice_clones_on_startup()
+        logger.info("Worker 启动音色克隆恢复完成，共标记 %d 个卡死任务为 failed", recovered)
+    except Exception as e:
+        logger.error("启动音色克隆恢复失败（beat 巡检仍会兜底标 failed）: %s", e, exc_info=True)
+
+
+@worker_ready.connect
+def _probe_gpu_encoder_on_ready(sender, **kwargs):
+    """Worker 启动完成后探测 P4000 GPU NVENC 节点状态，打日志。"""
+    try:
+        from packages.shared.gpu_encoder import get_gpu_encoder
+
+        client = get_gpu_encoder()
+        if client is None:
+            logger.info(
+                "[gpu-encoder] disabled (ENABLE_GPU_ENCODE=false or endpoint not configured), using CPU libx264"
+            )
+            return
+        health = client.check_health()
+        if health.ready:
+            logger.info(
+                "[gpu-encoder] NVENC enabled: endpoint=%s gpu=%s worker=%s",
+                client.endpoint,
+                health.gpu_name,
+                health.worker,
+            )
+        else:
+            logger.warning(
+                "[gpu-encoder] configured but NOT ready: %s (endpoint=%s) — falling back to CPU",
+                health.error,
+                client.endpoint,
+            )
+    except Exception as e:  # noqa: BLE001
+        logger.warning("[gpu-encoder] startup probe error (will retry on first job, CPU fallback): %s", e)

apps/worker/worker_app/tasks/cleanup.py

@@ -22,6 +22,10 @@ from packages.application.ingest_orphan_cleanup import (
     INGEST_PROCESSING_TIMEOUT_MINUTES,
 )
 
+# 音色克隆 processing 超时：正常克隆轮询最多 5 分钟，10 分钟无更新视为卡死
+VOICE_CLONE_PROCESSING_TIMEOUT_MINUTES = 10
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -125,3 +129,40 @@ def scheduled_cleanup_stale_ingest_jobs(
             purged,
         )
     return {"stale_jobs": total_jobs, "assets_to_error": total_assets, "purged_messages": purged}
+
+
+@shared_task(name="worker.cleanup_stale_voice_clones")
+def scheduled_cleanup_stale_voice_clones(
+    processing_timeout_minutes: int = VOICE_CLONE_PROCESSING_TIMEOUT_MINUTES,
+) -> dict:
+    """Celery Beat: 清理卡死在 processing 的音色克隆档案。
+
+    每 5 分钟执行一次。worker 重启/Celery 消息丢失/进程 OOM 时，
+    已 prefetch 的克隆任务消息丢失，voice_clone_profile 永久卡在 processing。
+    超过 processing_timeout_minutes 未更新的记录标记为 failed，
+    错误信息指引用户点击重试。
+    """
+    from worker_app.db import SessionLocal
+
+    from packages.adapters.sqlalchemy_impl.voice_clone_profile_repository import (
+        SQLAlchemyVoiceCloneProfileRepository,
+    )
+
+    session = None
+    try:
+        session = SessionLocal()
+        repo = SQLAlchemyVoiceCloneProfileRepository(session)
+        count = repo.cleanup_stale_processing(processing_timeout_minutes)
+        if count > 0:
+            logger.warning(
+                "[Beat] 清理了 %d 个卡死 processing 的音色克隆（超时 %d 分钟）",
+                count,
+                processing_timeout_minutes,
+            )
+        return {"cleaned": count}
+    except Exception as e:
+        logger.error("[Beat] 清理卡死音色克隆失败: %s", e, exc_info=True)
+        return {"cleaned": 0, "error": str(e)}
+    finally:
+        if session is not None:
+            session.close()

apps/worker/worker_app/tasks/generation.py

@@ -1051,20 +1051,15 @@ def generate_video(self, task_id: str) -> dict:
                         )
                         if _meta_model:
                             meta = dict(_meta_model.extra_meta or {})
+                            # #2024/P0 finalize-400: 直接展开 _precompute_render_metadata 返回的
+                            # 完整 dict（含 file_url/fingerprint_dict/fingerprint_chunks/is_duplicate
+                            # /duplicate_of/...），避免手写字段白名单漏传字段导致 finalize 读不到数据。
                             meta["rendered_output"] = {
+                                **dict(rendered_output or {}),
+                                # file_url/duration 由外层调用方拿到的实际上传结果，优先覆盖预计算值
                                 "file_url": file_url,
                                 "file_size": file_size,
                                 "duration": duration,
-                                "width": rendered_output.get("width", 1280),
-                                "height": rendered_output.get("height", 720),
-                                "fps": rendered_output.get("fps", 25.0),
-                                "name": rendered_output.get("name", ""),
-                                "thumbnail_url": rendered_output.get("thumbnail_url", ""),
-                                "mode": rendered_output.get("mode", editing_mode.value),
-                                "fingerprint_dict": rendered_output.get("fingerprint_dict"),
-                                "batch_id": batch_id,
-                                "project_id": project_id,
-                                "user_id": user_id,
                             }
                             _meta_model.extra_meta = meta
                             _finalize_meta_session.commit()

apps/worker/worker_app/tasks/voice_clone.py

@@ -44,6 +44,7 @@ def process_voice_clone(self: Task, profile_id: str) -> dict:
     # P2-2 修复：session 初始化为 None，避免 SessionLocal() 抛异常时
     # finally 块中 session.close() 触发 UnboundLocalError
     session = None
+    logger.info(f"Voice clone task started: profile_id={profile_id}")
     try:
         session = SessionLocal()
         repo = SQLAlchemyVoiceCloneProfileRepository(session)

deploy/configs/.env.staging

@@ -280,3 +280,18 @@ USE_GPU_LIPSYNC=true
 GPU_LIPSYNC_POLL_INTERVAL=5
 GPU_LIPSYNC_WAIT_TIMEOUT=1200
 GPU_WORKER_STALE_SECONDS=300
+
+# ==================== P4000 NVENC 硬件编码（GPU mezzanine relay）====================
+# 注意：这些值必须写死在模板里（不是 CI Secret），否则每次 CI 重新渲染 .env 都会被丢弃，
+# 导致 staging 发版后 GPU 编码静默降级到 CPU（P0 防复发）。
+ENABLE_GPU_ENCODE=true
+GPU_ENCODE_ENDPOINT=http://100.105.75.67:8900
+GPU_ENCODE_RELAY_BASE_URL=http://100.125.116.43:8092
+GPU_ENCODE_RELAY_INTERNAL_BASE_URL=http://xiaoxia-api-staging:8000
+GPU_ENCODE_RELAY_SECRET=0e1a8f0626438564a8b3fa92f3f2aac29e3c69bc02f2f85c
+GPU_ENCODE_VCODEC=h264_nvenc
+GPU_ENCODE_PRESET=p4
+GPU_ENCODE_CRF=23
+GPU_ENCODE_FALLBACK_CPU=true
+GPU_ENCODE_MEZZANINE_TRANSPORT=relay
+GPU_ENCODE_OSS_TMP_PREFIX=tmp/gpu-mezzanine/

infra/docker/compose.yml

@@ -56,7 +56,6 @@ services:
     
     environment:
       APP_ENV: ${APP_ENV:-staging}
-      APP_VERSION: ${APP_VERSION:-unknown}
       GENERATED_FILES_DIR: /app/generated
       GENERATED_FILES_URL_PREFIX: /generated-files
       PUBLIC_API_BASE_URL: ${PUBLIC_API_BASE_URL:-https://api.xiaoxiajianji.com}
@@ -113,7 +112,6 @@ services:
     
     environment:
       APP_ENV: ${APP_ENV:-staging}
-      APP_VERSION: ${APP_VERSION:-unknown}
       WORKER_CONCURRENCY: ${WORKER_CONCURRENCY:-4}
       WORKER_MAX_TASKS_PER_CHILD: ${WORKER_MAX_TASKS_PER_CHILD:-100}
       # #1714 队列隔离：generation 队列独占 worker（默认并发 2），其余并发给转码

infra/nginx/gpu-relay-staging.conf

@@ -0,0 +1,31 @@
+# Staging GPU relay plain-HTTP vhost (P4000 NVENC 编码回传入口)
+# - 监听 8092 端口纯 HTTP（绕开 HTTPS 证书与 P4000 httpx SSL 问题）
+# - 代理到本机 staging API 的 /api/ 路径（127.0.0.1:8000 是 docker 映射端口）
+# - P4000 通过 Tailscale 直连宿主机 100.69.73.60:8092 PUT 编码结果
+# - Worker 通过 Docker DNS (xiaoxia-api-staging:8000) 直接 GET/DELETE，
+#   不经宿主机 nginx，避免 UFW FORWARD DROP 阻断
+#
+# 部署：cp infra/nginx/gpu-relay-staging.conf /etc/nginx/conf.d/ && nginx -t && systemctl reload nginx
+
+server {
+    listen 8092;
+    server_name _;
+
+    client_max_body_size 2048m;
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:8000/api/;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_request_buffering off;
+        proxy_read_timeout 600s;
+        proxy_send_timeout 600s;
+    }
+
+    location = /health {
+        proxy_pass http://127.0.0.1:8000/health;
+    }
+}

packages/adapters/sqlalchemy_impl/generation_task_repository.py

@@ -43,6 +43,7 @@ def _to_domain(model: GenerationTaskModel) -> GenerationTask:
         output_height=getattr(model, "output_height", 720) or 720,
         cover_url=getattr(model, "cover_url", "") or "",
         title_config=dict(getattr(model, "title_config", {}) or {}),
+        extra_meta=dict(getattr(model, "extra_meta", {}) or {}),
         logs=model.logs or "[]",
         created_at=model.created_at,
         updated_at=model.updated_at,
@@ -88,6 +89,7 @@ class SQLAlchemyGenerationTaskRepository:
             output_height=task.output_height,
             cover_url=task.cover_url or "",
             title_config=dict(task.title_config) if task.title_config else {},
+            extra_meta=dict(task.extra_meta) if task.extra_meta else {},
             logs=task.logs,
             created_at=task.created_at,
             updated_at=task.updated_at,
@@ -322,6 +324,7 @@ class SQLAlchemyGenerationTaskRepository:
         model.output_height = task.output_height
         model.cover_url = task.cover_url or ""
         model.title_config = dict(task.title_config) if task.title_config else {}
+        model.extra_meta = dict(task.extra_meta) if task.extra_meta else {}
         model.logs = task.logs
         self.session.commit()
         return task

packages/adapters/sqlalchemy_impl/voice_clone_profile_repository.py

@@ -136,6 +136,39 @@ class SQLAlchemyVoiceCloneProfileRepository:
         )
         return {voice_id: profile_id for voice_id, profile_id in rows}
 
+    def cleanup_stale_processing(self, timeout_minutes: int = 10) -> int:
+        """清理超时卡在 processing 的克隆档案。
+
+        worker 重启、Celery 任务丢失或 OOM 被杀时，processing 档案会永久卡住。
+        updated_at < NOW() - timeout_minutes 的 processing 记录，标记为 failed
+        并附带明确错误信息，用户可在前端点击「重试」。
+
+        Args:
+            timeout_minutes: 超时分钟数，默认 10 分钟（正常克隆 < 5 分钟）
+
+        Returns:
+            清理的记录数
+        """
+        from datetime import UTC, datetime, timedelta
+
+        cutoff = datetime.now(UTC) - timedelta(minutes=timeout_minutes)
+        models = (
+            self.session.query(VoiceCloneProfileModel)
+            .filter(
+                VoiceCloneProfileModel.status == "processing",
+                VoiceCloneProfileModel.updated_at < cutoff,
+            )
+            .all()
+        )
+        count = 0
+        for model in models:
+            model.status = "failed"
+            model.error_message = f"克隆任务执行超时（超过 {timeout_minutes} 分钟未更新，可能因服务重启中断），请重试"
+            count += 1
+        if count > 0:
+            self.session.commit()
+        return count
+
     @staticmethod
     def _model_to_entity(model: VoiceCloneProfileModel) -> VoiceCloneProfile:
         return VoiceCloneProfile(

packages/application/generated_video_finalize.py

@@ -52,6 +52,18 @@ class RenderedOutput:
     def from_dict(cls, data: dict[str, Any]) -> "RenderedOutput":
         if not isinstance(data, dict):
             raise ValueError("rendered_output must be a dict")
+        # fingerprint_chunks 历史上有两种位置：
+        #   1) 顶层 ``fingerprint_chunks``（由 compute_render_fingerprint_and_dedup 直接返回）
+        #   2) 嵌套在 ``fingerprint_dict["chunks"]``（VideoFingerprint.to_dict() 序列化的结构）
+        # 顶层优先；顶层为空时回退到嵌套位置，兼容旧数据。
+        fp_dict = data.get("fingerprint_dict") or {}
+        chunks_raw = data.get("fingerprint_chunks")
+        if not chunks_raw and isinstance(fp_dict, dict):
+            chunks_raw = fp_dict.get("chunks")
+        # md5 同样可能在顶层或嵌套在 fingerprint_dict 内（历史数据兼容）
+        md5_value = data.get("video_fingerprint_md5")
+        if not md5_value and isinstance(fp_dict, dict):
+            md5_value = fp_dict.get("md5")
         return cls(
             file_url=str(data.get("file_url") or ""),
             file_size=int(data.get("file_size") or 0),
@@ -65,14 +77,14 @@ class RenderedOutput:
             batch_id=str(data.get("batch_id") or ""),
             project_id=str(data.get("project_id") or ""),
             user_id=str(data.get("user_id") or ""),
-            fingerprint_dict=data.get("fingerprint_dict"),
-            fingerprint_chunks=data.get("fingerprint_chunks"),
+            fingerprint_dict=fp_dict or None,
+            fingerprint_chunks=chunks_raw if isinstance(chunks_raw, list) else None,
             is_duplicate=bool(data.get("is_duplicate", False)),
             duplicate_of=data.get("duplicate_of"),
             duplicate_rate=_safe_float(data.get("duplicate_rate")),
             match_count=_safe_int(data.get("match_count")),
             visual_similarity=_safe_float(data.get("visual_similarity")),
-            video_fingerprint_md5=str(data.get("video_fingerprint_md5") or ""),
+            video_fingerprint_md5=str(md5_value or ""),
         )
 
 

packages/config/base.py

@@ -129,6 +129,72 @@ class SharedSettings(BaseSettings):
     # 判断 Worker 可用的心跳新鲜度窗口（秒）—— last_heartbeat_at 在窗口内视为在线
     gpu_worker_stale_seconds: int = 300
 
+    # ── P4000 NVENC 硬件编码 ────────────────────────────────────────────
+    # GPU 编码总开关；关闭或 endpoint 为空时始终走本机 CPU libx264
+    enable_gpu_encode: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("ENABLE_GPU_ENCODE", "enable_gpu_encode"),
+    )
+    # P4000 编码节点地址（Tailscale 内网），例如 http://100.105.75.67:8900
+    gpu_encode_endpoint: str = Field(
+        default="",
+        validation_alias=AliasChoices("GPU_ENCODE_ENDPOINT", "gpu_encode_endpoint"),
+    )
+    # GPU 回传临时文件走公网/内网 nginx（/gpu-relay/ 已加 location）；
+    # 形如 http://100.69.73.60/gpu-relay （不带尾斜杠）
+    gpu_encode_relay_base_url: str = Field(
+        default="",
+        validation_alias=AliasChoices("GPU_ENCODE_RELAY_BASE_URL", "gpu_encode_relay_base_url"),
+        description="P4000 回传结果用的外部 URL（worker 通过该 URL 提供给 P4000 PUT），如 http://100.69.73.60:8092",
+    )
+    # Worker→API 内网直连 URL（Docker DNS），用于 worker 自己下载/清理 relay 文件。
+    # 未配置时回退到 relay_base_url（本地开发/单节点）。
+    gpu_encode_relay_internal_base_url: str = Field(
+        default="",
+        validation_alias=AliasChoices("GPU_ENCODE_RELAY_INTERNAL_BASE_URL", "gpu_encode_relay_internal_base_url"),
+    )
+    # 同步调用超时（秒）：含编码+上传回传，5 分钟足够短视频
+    gpu_encode_sync_timeout: int = 300
+    # 异步轮询总超时（秒）：长视频走 async + 轮询
+    gpu_encode_async_timeout: int = 1800
+    # 轮询间隔（秒）
+    gpu_encode_poll_interval: float = 3.0
+    # 启动探测超时（秒）
+    gpu_encode_health_timeout: float = 3.0
+    # NVENC 默认编码参数（可被调用方覆盖）
+    gpu_encode_vcodec: str = "h264_nvenc"
+    gpu_encode_preset: str = "p4"  # NVENC preset: p1(最快)~p7(最好)，p4 为均衡
+    gpu_encode_crf: int = 23
+    gpu_encode_bitrate: str = ""  # 空则用 crf；非空则用 -b:v 模式
+    # GPU 编码失败时是否自动降级到 CPU（默认 True）；设为 False 可在 CI/测试中暴露错误
+    gpu_encode_fallback_cpu: bool = Field(
+        default=True,
+        validation_alias=AliasChoices("GPU_ENCODE_FALLBACK_CPU", "gpu_encode_fallback_cpu"),
+    )
+    # P4000 → relay 回传鉴权 token（query 参数 token=xxx）。
+    # 生产环境必须设置；未设置且非 production 时自动生成随机值（写日志方便排查）。
+    gpu_encode_relay_secret: str = Field(
+        default="",
+        validation_alias=AliasChoices("GPU_ENCODE_RELAY_SECRET", "gpu_encode_relay_secret"),
+    )
+    # Mezzanine 传输方式：relay=走Tailscale/Docker内网relay PUT（推荐，省公网OSS往返18-20s）；oss=走旧公网OSS路径
+    gpu_encode_mezzanine_transport: str = Field(
+        default="relay",
+        validation_alias=AliasChoices("GPU_ENCODE_MEZZANINE_TRANSPORT", "gpu_encode_mezzanine_transport"),
+    )
+    # GPU 中间片在 OSS 的临时前缀（mezzanine_transport=oss 时或 relay 失败 fallback 时使用）
+    gpu_encode_oss_tmp_prefix: str = Field(
+        default="tmp/gpu-mezzanine/",
+        validation_alias=AliasChoices("GPU_ENCODE_OSS_TMP_PREFIX", "gpu_encode_oss_tmp_prefix"),
+    )
+    # relay 写入目录（相对于 generated-files 根目录）
+    gpu_encode_relay_dir: str = Field(
+        default="gpu_relay",
+        validation_alias=AliasChoices("GPU_ENCODE_RELAY_DIR", "gpu_encode_relay_dir"),
+    )
+    # relay 文件保留时间（秒），worker 下载完成后会主动删除，此为兜底清理 TTL
+    gpu_encode_relay_ttl: int = 3600
+
     @property
     def effective_database_url(self) -> str:
         """返回实际使用的数据库 URL。

packages/shared/ffmpeg_utils.py

@@ -25,9 +25,9 @@ FFPROBE_BIN: str = shutil.which("ffprobe") or "ffprobe"
 DEFAULT_FFMPEG_TIMEOUT = 1800
 
 # ── 编码参数（集中配置，支持环境变量覆盖）────────────────────────────────────
-# preset 从 medium → fast，渲染速度提升 30%+，画质几乎无损（CRF 相同时 PSNR 差异 <0.1dB）
-# 可通过环境变量 FFMPEG_ENCODE_PRESET 覆盖（如 ultrafast 追求极致速度，veryslow 追求极致压缩）
-FFMPEG_ENCODE_PRESET: str = os.environ.get("FFMPEG_ENCODE_PRESET", "fast")
+# preset 默认 veryfast，相比 fast 再提速 ~40%（4 核 Xeon 60s 720p: 32s→20s），CRF=23 画质可接受
+# 可通过环境变量 FFMPEG_ENCODE_PRESET 覆盖（如 fast/medium 追求质量，ultrafast 追求极致速度）
+FFMPEG_ENCODE_PRESET: str = os.environ.get("FFMPEG_ENCODE_PRESET", "veryfast")
 # CRF 保持 23（libx264 默认质量），可通过 FFMPEG_ENCODE_CRF 覆盖
 FFMPEG_ENCODE_CRF: str = os.environ.get("FFMPEG_ENCODE_CRF", "23")
 # 编码线程数：0 = 自动检测 CPU 核心数，充分利用多核

packages/shared/gpu_encoder.py

@@ -0,0 +1,569 @@
+"""P4000 NVENC 远程编码客户端。
+
+完整链路（encode_video_file）：
+  1. CPU 滤镜已在本地生成 mezzanine 中间片（libx264 ultrafast）
+  2. 通过 HTTP PUT 把 mezzanine 上传到 relay（走 Tailscale/Docker 内网，~1s 完成）
+     - 失败则 fallback 到 OSS 上传（旧路径，兼容没有 :8092 内网可达的环境）
+  3. 生成 relay 一次性 key，构造两个带 token 的 URL：
+     - put_url：给 P4000 回传结果，走 relay_base_url（Tailscale host:8092）
+     - get/del_url：worker 自己下载+清理用，走 relay_internal_base_url（Docker DNS 直连 API）
+  4. 【冷启动防护】距上次成功通信 >60s 时，先 GET /health 预热 Tailscale 链路（短超时快速失败）
+  5. POST P4000 /api/render/sync：inputs={"in.mp4": "<mezzanine-get-url>"}, output_url="<put_url>"
+     ffmpeg_args: -i in.mp4 [-vf <vf>] -c:v h264_nvenc ... -an/-c:a aac -f mp4 pipe:1
+     - 首字节用短超时(默认20s)，避免链路卡死空等上百秒；首字节到达后放宽到 ffmpeg_timeout+60s
+  6. P4000 从 relay GET mezzanine → h264_nvenc 编码 → PUT 最终 mp4 到 put_url
+  7. 本客户端通过 get_url（Docker 内网）下载最终文件到 output_path，然后 DELETE 清理
+  8. 删除 relay 上的 mezzanine 临时文件（以及 OSS fallback 的 key）
+
+任何环节失败抛 GpuEncodeError，调用方应 fallback 到 CPU libx264。
+
+冷启动/链路卡顿背景（2026-09-27 实测）：P4000 与 staging 之间走 Tailscale，长时间空闲
+（>7h）后首次请求曾出现 150s 延迟才真正开始下载 mezzanine，期间 ffmpeg 尚未启动、GPU 空闲。
+根因在服务端/网络层（可能是 Tailscale DERP 打洞或 httpx 连接池重建），本客户端通过
+pre_warm + 首字节短超时做兜底：预热打通链路 + 20s 内收不到首字节就快速失败让 CPU fallback，
+不再让用户等满 150s+。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class GpuEncodeError(RuntimeError):
+    """GPU 编码失败（网络/超时/ffmpeg/upload/download 任一环节）。调用方应 fallback 到 CPU。"""
+
+
+@dataclass
+class GpuHealth:
+    healthy: bool
+    worker: str = ""
+    gpu_name: str = ""
+    nvenc_h264: bool = False
+    nvenc_hevc: bool = False
+    error: str = ""
+
+    @property
+    def ready(self) -> bool:
+        return self.healthy and self.nvenc_h264
+
+
+class GpuEncoderClient:
+    def __init__(
+        self,
+        endpoint: str,
+        relay_base_url: str,
+        *,
+        relay_internal_base_url: str = "",
+        # Mezzanine 上传：默认走 relay（Tailscale/Docker 内网）；设为 "oss" 强制走旧 OSS 路径
+        mezzanine_transport: str = "relay",
+        sync_timeout: int = 300,
+        health_timeout: float = 3.0,
+        # 提交编码任务前先发一次 /health 预热 Tailscale 链路，避免长时间空闲后首次请求
+        # 因 DERP 打洞/NAT 映射过期/Tailscale 连接重建而阻塞上百秒。
+        pre_warm: bool = True,
+        # POST 首次响应超时：P4000 已收到请求后应该在数秒内开始下载 inputs；
+        # 如果超过这个值还没收到任何响应字节，说明链路/服务卡住，快速失败让调用方 fallback CPU。
+        # 注意：ffmpeg 编码本身靠 body.timeout 控制（300s），不应该被这个超时影响。
+        post_first_byte_timeout: float = 20.0,
+        vcodec: str = "h264_nvenc",
+        preset: str = "p4",
+        crf: int = 23,
+        bitrate: str = "",
+        relay_secret: str = "",
+        oss_tmp_prefix: str = "tmp/gpu-mezzanine/",
+    ) -> None:
+        self.endpoint = endpoint.rstrip("/")
+        self.relay_base_url = relay_base_url.rstrip("/")
+        # Worker→API 内网访问地址（Docker DNS 直连，如 http://xiaoxia-api-staging:8000）。
+        # 未配置时回退到 relay_base_url（本地开发/单节点）。
+        self.relay_internal_base_url = (
+            relay_internal_base_url.rstrip("/") if relay_internal_base_url else self.relay_base_url
+        )
+        self.mezzanine_transport = mezzanine_transport.lower()  # "relay" | "oss"
+        self.sync_timeout = sync_timeout
+        self.health_timeout = health_timeout
+        self.pre_warm = pre_warm
+        self.post_first_byte_timeout = post_first_byte_timeout
+        self.vcodec = vcodec
+        self.preset = preset
+        self.crf = crf
+        self.bitrate = bitrate
+        self._relay_secret = relay_secret
+        self.oss_tmp_prefix = oss_tmp_prefix.rstrip("/") + "/" if oss_tmp_prefix else "tmp/gpu-mezzanine/"
+        # 上次与 P4000 成功通信的时间戳（用于判断是否需要 pre_warm 预热）
+        self._last_ok_ts: float = 0.0
+
+    RELAY_PATH_PREFIX = "/api/v1/internal/gpu-relay"
+
+    # ------------------------------------------------------------------
+    # URL builders
+    # ------------------------------------------------------------------
+    def _relay_url_from_base(self, base_url: str, path: str, key: str, secret: str) -> str:
+        return f"{base_url}{self.RELAY_PATH_PREFIX}{path}/{key}?token={urllib.parse.quote(secret, safe='')}"
+
+    def _relay_result_url(self, base_url: str, key: str, secret: str) -> str:
+        return self._relay_url_from_base(base_url, "", key, secret)
+
+    def _relay_mezz_url(self, base_url: str, key: str, secret: str) -> str:
+        return self._relay_url_from_base(base_url, "/mezzanine", key, secret)
+
+    def _result_put_url(self, key: str, secret: str) -> str:
+        """P4000 回传编码结果 PUT URL（外部/Tailscale 可达）。"""
+        return self._relay_result_url(self.relay_base_url, key, secret)
+
+    def _result_get_url(self, key: str, secret: str) -> str:
+        """Worker 下载最终结果 GET URL（Docker 内网）。"""
+        return self._relay_result_url(self.relay_internal_base_url, key, secret)
+
+    def _mezz_put_url(self, key: str, secret: str) -> str:
+        """Worker 上传 mezzanine PUT URL（Docker 内网，快）。"""
+        return self._relay_mezz_url(self.relay_internal_base_url, key, secret)
+
+    def _mezz_get_url_for_p4000(self, key: str, secret: str) -> str:
+        """P4000 下载 mezzanine GET URL（必须是 P4000 可达地址，Tailscale host:8092）。"""
+        return self._relay_mezz_url(self.relay_base_url, key, secret)
+
+    # ------------------------------------------------------------------
+    # Health
+    # ------------------------------------------------------------------
+    def check_health(self) -> GpuHealth:
+        url = f"{self.endpoint}/health"
+        try:
+            with urllib.request.urlopen(url, timeout=self.health_timeout) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except (urllib.error.URLError, socket.timeout, TimeoutError, json.JSONDecodeError, ConnectionError) as e:
+            return GpuHealth(healthy=False, error=f"health probe failed: {e}")
+        try:
+            h = GpuHealth(
+                healthy=data.get("status") == "healthy",
+                worker=str(data.get("worker", "")),
+                gpu_name=(data.get("gpu") or {}).get("name", ""),
+                nvenc_h264=bool((data.get("nvenc") or {}).get("h264_nvenc")),
+                nvenc_hevc=bool((data.get("nvenc") or {}).get("hevc_nvenc")),
+            )
+            if h.healthy:
+                self._last_ok_ts = time.time()
+            return h
+        except Exception as e:  # noqa: BLE001
+            return GpuHealth(healthy=False, error=f"malformed health response: {e}")
+
+    # ------------------------------------------------------------------
+    # High-level: encode a mezzanine file to final output
+    # ------------------------------------------------------------------
+    def encode_mezzanine_to_output(
+        self,
+        mezzanine_path: Path,
+        output_path: Path,
+        *,
+        extra_video_args: Optional[list[str]] = None,
+        audio_args: Optional[list[str]] = None,
+        timeout: Optional[int] = None,
+    ) -> dict[str, Any]:
+        """把 mezzanine（CPU 滤镜已完成）交给 P4000 NVENC 编码，结果写到 output_path。
+
+        传输：默认通过 relay PUT/GET（Tailscale 内网，省去公网 OSS 往返 18-20s）；
+        若 relay PUT 失败且配置可用，自动 fallback 到 OSS。
+        """
+        if not mezzanine_path.exists():
+            raise GpuEncodeError(f"mezzanine file not found: {mezzanine_path}")
+        if not self.relay_base_url:
+            raise GpuEncodeError("gpu_encode_relay_base_url not configured")
+
+        timeout = timeout or self.sync_timeout
+        t_total = time.time()
+        oss_key: Optional[str] = None
+        mezz_key: Optional[str] = None
+        result_key: Optional[str] = None
+        input_url: str = ""
+        used_transport = self.mezzanine_transport
+
+        try:
+            secret = self._get_relay_secret()
+
+            # 1. 上传 mezzanine 到 relay（或 OSS fallback）
+            mezz_size = mezzanine_path.stat().st_size
+            if used_transport == "relay":
+                mezz_key = uuid.uuid4().hex
+                mezz_put = self._mezz_put_url(mezz_key, secret)
+                mezz_get_for_p4000 = self._mezz_get_url_for_p4000(mezz_key, secret)
+                t_up = time.time()
+                try:
+                    self._upload_file_put(mezz_put, mezzanine_path, "video/mp4")
+                    input_url = mezz_get_for_p4000
+                    logger.info(
+                        "[gpu-encoder] mezzanine uploaded to relay: key=%s size=%d took=%.2fs",
+                        mezz_key,
+                        mezz_size,
+                        time.time() - t_up,
+                    )
+                except (GpuEncodeError, OSError, urllib.error.URLError) as e:
+                    logger.warning(
+                        "[gpu-encoder] relay mezz upload failed (%s), fallback to OSS",
+                        e,
+                    )
+                    used_transport = "oss"
+                    # relay 上传失败的部分文件 best-effort 清理
+                    if mezz_key:
+                        try:
+                            self._relay_delete(self._relay_mezz_url(self.relay_internal_base_url, mezz_key, secret))
+                        except Exception:  # noqa: BLE001
+                            pass
+                        mezz_key = None
+
+            if used_transport == "oss" or not input_url:
+                input_url, oss_key = self._upload_mezzanine_to_oss(mezzanine_path)
+                logger.debug("[gpu-encoder] mezzanine uploaded to OSS: oss_key=%s", oss_key)
+
+            # 2. prepare result relay URLs
+            result_key = uuid.uuid4().hex
+            put_url = self._result_put_url(result_key, secret)
+            get_url = self._result_get_url(result_key, secret)
+            del_result_url = get_url
+
+            # 3. build ffmpeg args
+            ffmpeg_args = ["-y", "-i", "in.mp4"]
+            if extra_video_args:
+                ffmpeg_args.extend(extra_video_args)
+            ffmpeg_args.extend(["-c:v", self.vcodec, "-preset", self.preset])
+            if self.bitrate:
+                ffmpeg_args.extend(["-b:v", self.bitrate])
+            else:
+                ffmpeg_args.extend(["-cq", str(self.crf)])
+            ffmpeg_args.extend(["-pix_fmt", "yuv420p", "-movflags", "+faststart"])
+            if audio_args:
+                ffmpeg_args.extend(audio_args)
+            else:
+                ffmpeg_args.append("-an")
+            ffmpeg_args.extend(["-f", "mp4", "pipe:1"])
+
+            # 4. pre-warm then call P4000 sync render
+            self._warm_up_if_needed()
+            body = {
+                "inputs": {"in.mp4": input_url},
+                "ffmpeg_args": ffmpeg_args,
+                "output_url": put_url,
+                "timeout": int(timeout),
+            }
+            job = self._post_sync(body)
+            self._last_ok_ts = time.time()
+            logger.info(
+                "[gpu-encoder] P4000 done: job_id=%s rc=%s size=%s dur=%ss transport=%s",
+                job.get("job_id"),
+                job.get("ffmpeg_rc"),
+                job.get("size"),
+                job.get("duration"),
+                used_transport,
+            )
+
+            # 5. download result from relay to output_path
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            size = self._download_to_file(get_url, output_path)
+
+            # 6. cleanup relay result
+            self._relay_delete(del_result_url)
+
+            logger.info(
+                "[gpu-encoder] encode ok: %s → %s (%d bytes) total=%.2fs transport=%s",
+                mezzanine_path.name,
+                output_path.name,
+                size,
+                time.time() - t_total,
+                used_transport,
+            )
+            return {
+                "job": job,
+                "output_size": size,
+                "output_path": str(output_path),
+                "transport": used_transport,
+            }
+
+        except GpuEncodeError:
+            raise
+        except Exception as e:  # noqa: BLE001
+            raise GpuEncodeError(f"unexpected: {e}") from e
+        finally:
+            # cleanup relay mezzanine (best-effort)
+            if mezz_key:
+                try:
+                    secret = self._get_relay_secret()
+                    self._relay_delete(self._relay_mezz_url(self.relay_internal_base_url, mezz_key, secret))
+                except Exception as e:  # noqa: BLE001
+                    logger.warning("[gpu-encoder] failed to delete relay mezzanine %s: %s", mezz_key, e)
+            # cleanup OSS mezzanine (best-effort)
+            if oss_key:
+                try:
+                    self._delete_oss(oss_key)
+                except Exception as e:  # noqa: BLE001
+                    logger.warning("[gpu-encoder] failed to delete OSS mezzanine %s: %s", oss_key, e)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+    def _get_relay_secret(self) -> str:
+        if self._relay_secret:
+            return self._relay_secret
+        env = (os.getenv("APP_ENV", os.getenv("ENV", "development"))).lower()
+        secret = (os.getenv("GPU_ENCODE_RELAY_SECRET", "") or "").strip()
+        if not secret:
+            if env in ("production", "prod"):
+                raise GpuEncodeError("GPU_ENCODE_RELAY_SECRET must be set in production")
+            raise GpuEncodeError("GPU_ENCODE_RELAY_SECRET not set")
+        return secret
+
+    def _warm_up_if_needed(self) -> None:
+        """POST 前预热：如果距上次成功通信超过 idle 阈值，先打 /health 打通 Tailscale 链路。
+
+        背景：Tailscale 在长时间空闲（几小时）后，到对端的直连 NAT 映射可能过期，
+        首次请求会走 DERP 中继打洞；极少数情况下打洞/重连会卡住上百秒（曾观测到 150s 延迟）。
+        预热请求本身走短超时快速失败，不会阻塞主流程；预热成功后再发 POST。
+        """
+        if not self.pre_warm:
+            return
+        idle = time.time() - self._last_ok_ts
+        # 空闲超过 60s 才预热（正常流水线里相邻任务间隔通常 <10s，没必要每次都打）
+        if idle < 60:
+            return
+        url = f"{self.endpoint}/health"
+        t0 = time.time()
+        try:
+            with urllib.request.urlopen(url, timeout=min(self.health_timeout, 3.0)) as resp:
+                resp.read()
+            self._last_ok_ts = time.time()
+            logger.debug("[gpu-encoder] pre-warm ok: took=%.2fs idle=%.0fs", time.time() - t0, idle)
+        except (urllib.error.URLError, socket.timeout, TimeoutError, ConnectionError, OSError) as e:
+            # 预热失败不致命——主 POST 会带自己的超时，再失败就抛 GpuEncodeError 让调用方 fallback
+            logger.warning("[gpu-encoder] pre-warm probe failed (will try POST anyway): %s", e)
+
+    def _post_sync(self, body: dict[str, Any]) -> dict[str, Any]:
+        url = f"{self.endpoint}/api/render/sync"
+        ffmpeg_timeout = body.get("timeout", self.sync_timeout)
+        # 连接 + 首字节用短超时（防链路卡死数百秒）；首字节到达后给 ffmpeg 留足编码+上传时间
+        # Python urllib 的 timeout 是整个请求总超时，所以用"两段式"：
+        #   阶段1：先 read(1) 拿首字节，用短超时；
+        #   阶段2：再 read() 读完整 body，用 ffmpeg_timeout+60。
+        connect_timeout = min(max(self.post_first_byte_timeout, 5.0), 30.0)
+        payload = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        t0 = time.time()
+        first_byte_ok = False
+        resp = None
+        try:
+            resp = urllib.request.urlopen(req, timeout=connect_timeout)
+            # 读首字节 —— 如果 P4000/链路卡死，这里会在 connect_timeout 内抛超时
+            first_chunk = resp.read(1)
+            first_byte_ok = True
+            logger.debug(
+                "[gpu-encoder] P4000 first byte in %.2fs (connect_timeout=%.1fs)",
+                time.time() - t0,
+                connect_timeout,
+            )
+            # 剩余用长超时（给底层socket放宽时限；如果是mock/不支持，则跳过）
+            try:
+                resp.fp._sock.settimeout(ffmpeg_timeout + 60)
+            except (AttributeError, OSError):
+                pass
+            rest = resp.read()
+            raw = (first_chunk + rest).decode("utf-8")
+            resp.close()
+            resp = None
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", errors="replace")[:1000]
+            raise GpuEncodeError(f"P4000 HTTP {e.code}: {detail}") from e
+        except (urllib.error.URLError, socket.timeout, TimeoutError, ConnectionError, OSError) as e:
+            waited = time.time() - t0
+            hint = "first-byte" if not first_byte_ok else "ffmpeg/upload"
+            # 统一以 "connection error" 开头，便于上层 fallback 逻辑用关键词识别；
+            # 末尾再附带具体错误（timed out / refused ...）供排障
+            raise GpuEncodeError(
+                f"P4000 {hint} connection error after {waited:.1f}s "
+                f"(connect_timeout={connect_timeout:.0f}s, ffmpeg_timeout={ffmpeg_timeout}s): {e}"
+            ) from e
+        finally:
+            if resp is not None:
+                try:
+                    resp.close()
+                except Exception:
+                    pass
+        try:
+            result = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise GpuEncodeError(f"P4000 bad JSON: {raw[:500]}") from e
+        dt = time.time() - t0
+
+        status = result.get("status")
+        ffmpeg_rc = result.get("ffmpeg_rc")
+        uploaded = result.get("uploaded")
+        if status != "completed" or ffmpeg_rc != 0:
+            err = result.get("message") or result.get("error") or "unknown"
+            raise GpuEncodeError(f"P4000 job failed: status={status} rc={ffmpeg_rc} err={err!s:.500}")
+        if not uploaded:
+            logger.warning("[gpu-encoder] P4000 reports uploaded=false (will verify via download)")
+        result["_roundtrip"] = dt
+        return result
+
+    def _download_to_file(self, url: str, output_path: Path) -> int:
+        """GET url → write to output_path. Returns bytes written."""
+        tmp = output_path.with_suffix(output_path.suffix + ".gpu_tmp")
+        size = 0
+        try:
+            with urllib.request.urlopen(url, timeout=self.sync_timeout) as resp:
+                if resp.status != 200:
+                    raise GpuEncodeError(f"relay GET returned HTTP {resp.status}")
+                with open(tmp, "wb") as f:
+                    while True:
+                        chunk = resp.read(1024 * 256)
+                        if not chunk:
+                            break
+                        f.write(chunk)
+                        size += len(chunk)
+            if size == 0:
+                raise GpuEncodeError("relay returned empty file")
+            os.replace(tmp, output_path)
+            return size
+        except (urllib.error.URLError, socket.timeout, TimeoutError, ConnectionError) as e:
+            if tmp.exists():
+                try:
+                    tmp.unlink()
+                except OSError:
+                    pass
+            raise GpuEncodeError(f"failed to download from relay: {e}") from e
+
+    def _relay_delete(self, url: str) -> None:
+        try:
+            req = urllib.request.Request(url, method="DELETE")
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                resp.read()
+        except Exception as e:  # noqa: BLE001
+            logger.debug("[gpu-encoder] relay cleanup delete failed: %s", e)
+
+    def _upload_file_put(self, url: str, path: Path, content_type: str) -> None:
+        """HTTP PUT 流式上传文件到指定 URL（mezzanine 上传到 relay 用，Tailscale/Docker 内网）。"""
+
+        file_size = path.stat().st_size
+        # 使用生成器/文件对象流式上传，避免一次性载入大 mezzanine 文件到内存
+        with open(path, "rb") as f:
+            req = urllib.request.Request(
+                url,
+                data=f,  # 文件对象支持read()，urllib会流式发送（但需要Content-Length）
+                method="PUT",
+                headers={
+                    "Content-Type": content_type,
+                    "Content-Length": str(file_size),
+                },
+            )
+            # 超时：按 ~20MB/s 内网速度估算 + 30s 保底
+            put_timeout = max(60, int(file_size / (20 * 1024 * 1024)) + 30)
+            with urllib.request.urlopen(req, timeout=put_timeout) as resp:
+                if resp.status not in (200, 201, 204):
+                    body = resp.read().decode("utf-8", errors="replace")[:500]
+                    raise GpuEncodeError(f"relay PUT failed: HTTP {resp.status} {body}")
+                resp.read()
+
+    # ------------------------------------------------------------------
+    # OSS helpers (fallback)
+    # ------------------------------------------------------------------
+    def _upload_mezzanine_to_oss(self, path: Path) -> tuple[str, str]:
+        """Upload mezzanine to OSS tmp prefix, return (signed_get_url, oss_key)."""
+        try:
+            from packages.shared.storage import get_storage_service
+        except ImportError as e:
+            raise GpuEncodeError(f"storage service unavailable: {e}") from e
+        storage = get_storage_service()
+        if storage is None or storage.bucket is None:
+            raise GpuEncodeError("OSS storage not configured; cannot upload mezzanine")
+        key = f"{self.oss_tmp_prefix}{uuid.uuid4().hex}.mp4"
+        try:
+            storage.upload_file(str(path), key, content_type="video/mp4")
+        except Exception as e:  # noqa: BLE001
+            raise GpuEncodeError(f"failed to upload mezzanine to OSS: {e}") from e
+        signed = storage.get_download_url(key, expires_seconds=3600)
+        return signed, key
+
+    def _delete_oss(self, key: str) -> None:
+        try:
+            from packages.shared.storage import get_storage_service
+
+            storage = get_storage_service()
+            if storage is not None and storage.bucket is not None:
+                storage.delete_file(key)
+        except Exception as e:  # noqa: BLE001
+            logger.debug("[gpu-encoder] OSS delete %s failed: %s", key, e)
+
+
+# ── Singleton factory ────────────────────────────────────────────────────
+
+_default_client: Optional[GpuEncoderClient] = None
+_default_client_initialized: bool = False
+
+
+def _build_client_from_settings() -> Optional[GpuEncoderClient]:
+    try:
+        from packages.config import get_shared_settings
+
+        settings = get_shared_settings()
+    except Exception:  # noqa: BLE001
+        return None
+    if not getattr(settings, "enable_gpu_encode", False):
+        return None
+    endpoint = (getattr(settings, "gpu_encode_endpoint", "") or "").strip()
+    relay = (getattr(settings, "gpu_encode_relay_base_url", "") or "").strip()
+    relay_internal = (getattr(settings, "gpu_encode_relay_internal_base_url", "") or "").strip()
+    if not endpoint or not relay:
+        return None
+    return GpuEncoderClient(
+        endpoint=endpoint,
+        relay_base_url=relay,
+        relay_internal_base_url=relay_internal,
+        mezzanine_transport=getattr(settings, "gpu_encode_mezzanine_transport", "relay") or "relay",
+        sync_timeout=getattr(settings, "gpu_encode_sync_timeout", 300),
+        health_timeout=getattr(settings, "gpu_encode_health_timeout", 3.0),
+        pre_warm=getattr(settings, "gpu_encode_pre_warm", True),
+        post_first_byte_timeout=getattr(settings, "gpu_encode_post_first_byte_timeout", 20.0),
+        vcodec=getattr(settings, "gpu_encode_vcodec", "h264_nvenc"),
+        preset=getattr(settings, "gpu_encode_preset", "p4"),
+        crf=getattr(settings, "gpu_encode_crf", 23),
+        bitrate=getattr(settings, "gpu_encode_bitrate", "") or "",
+        relay_secret=getattr(settings, "gpu_encode_relay_secret", "") or "",
+        oss_tmp_prefix=getattr(settings, "gpu_encode_oss_tmp_prefix", "tmp/gpu-mezzanine/"),
+    )
+
+
+def get_gpu_encoder() -> Optional[GpuEncoderClient]:
+    """返回进程级单例；未启用或未配置返回 None。"""
+    global _default_client, _default_client_initialized
+    if not _default_client_initialized:
+        _default_client_initialized = True
+        try:
+            _default_client = _build_client_from_settings()
+        except Exception as e:  # noqa: BLE001
+            logger.warning("[gpu-encoder] failed to init client (CPU fallback): %s", e)
+            _default_client = None
+    return _default_client
+
+
+def reset_gpu_encoder_for_tests() -> None:
+    global _default_client, _default_client_initialized
+    _default_client = None
+    _default_client_initialized = False
+
+
+def is_gpu_encode_enabled() -> bool:
+    return get_gpu_encoder() is not None

scripts/ci_staging_healthcheck.sh

@@ -17,7 +17,7 @@
 #   SKIP_NOTIFY           - 跳过通知 (true/false, 默认 false)
 #   CI_NOTIFY_WEBHOOK     - 通知 Webhook URL
 #
-#   STAGING_SSH_HOST      - Staging 服务器 SSH 地址 (默认 127.0.0.1，CI runner 在 staging 本机)
+#   STAGING_SSH_HOST      - Staging 服务器 SSH 地址 (默认 116.62.226.203（staging业务机公网IP）)
 #   STAGING_SSH_USER      - SSH 用户名 (默认 root)
 #   STAGING_SSH_PORT      - SSH 端口 (默认 22)
 #   STAGING_SSH_KEY       - SSH 私钥内容
@@ -40,7 +40,7 @@ HEALTH_CHECK_TIMEOUT="${HEALTH_CHECK_TIMEOUT:-120}"
 SKIP_ROLLBACK="${SKIP_ROLLBACK:-false}"
 SKIP_NOTIFY="${SKIP_NOTIFY:-false}"
 
-STAGING_SSH_HOST="${STAGING_SSH_HOST:-127.0.0.1}"
+STAGING_SSH_HOST="${STAGING_SSH_HOST:-116.62.226.203}"
 STAGING_SSH_USER="${STAGING_SSH_USER:-root}"
 STAGING_SSH_PORT="${STAGING_SSH_PORT:-22}"
 

tests/unit/test_1280_preview_speedup.py

@@ -2,7 +2,7 @@
 
 验证点：
 1. UnifiedRenderService 不再有 is_preview 参数
-2. 所有渲染统一使用 fast preset + CRF 23（#1758 优化：medium→fast）
+2. 所有渲染统一使用 veryfast preset + CRF 23（#2063 优化：fast→veryfast）
 3. RenderAdapter 统一执行校验和缩略图生成
 4. generation.py 并行下载逻辑（保留）
 """
@@ -51,7 +51,7 @@ class TestUnifiedRenderServiceNoPreviewParam:
 
 
 class TestUnifiedFFmpegPreset:
-    """所有渲染统一使用 fast preset + CRF 23（#1758 渲染加速优化）。"""
+    """所有渲染统一使用 veryfast preset + CRF 23（#2063 渲染加速优化）。"""
 
     def _make_clip(self):
         from video_processing.unified_render_service import ResolvedClip
@@ -71,7 +71,7 @@ class TestUnifiedFFmpegPreset:
         )
 
     @patch("video_processing.unified_render_service.run_ffmpeg")
-    def test_execute_ffmpeg_uses_fast_crf23(self, mock_run):
+    def test_execute_ffmpeg_uses_veryfast_crf23(self, mock_run):
         from video_processing.unified_render_service import (
             RenderLayer,
             UnifiedRenderService,
@@ -100,9 +100,9 @@ class TestUnifiedFFmpegPreset:
         mock_run.assert_called_once()
         cmd = mock_run.call_args[0][0]
 
-        # Check preset is fast (#1758: changed from medium to fast for rendering speed)
+        # Check preset is veryfast (#2063: changed from fast to veryfast for 38% speedup)
         preset_idx = cmd.index("-preset")
-        assert cmd[preset_idx + 1] == "fast", f"Expected fast, got {cmd[preset_idx + 1]}"
+        assert cmd[preset_idx + 1] == "veryfast", f"Expected veryfast, got {cmd[preset_idx + 1]}"
 
         # Check crf is 23 (no conditional)
         crf_idx = cmd.index("-crf")

tests/unit/test_ffmpeg_encoding_optimization.py

@@ -4,7 +4,7 @@
 1. 集中编码常量正确定义，支持环境变量覆盖
 2. 所有渲染路径（_execute_ffmpeg / _render_pass_through / normalize_video / processor）
    使用统一的编码参数
-3. preset 从 medium → fast，确保渲染速度提升
+3. preset 从 medium → veryfast（#2063 优化 fast→veryfast，再提速 38%）
 4. threads=0 自动检测 CPU 核心数
 """
 
@@ -27,7 +27,7 @@ class TestEncodingConstants:
         """默认 preset 应为 fast（非 medium），确保速度提升."""
         from shared.ffmpeg_utils import FFMPEG_ENCODE_PRESET
 
-        assert FFMPEG_ENCODE_PRESET == "fast"
+        assert FFMPEG_ENCODE_PRESET == "veryfast"
 
     def test_default_crf_is_23(self):
         """默认 CRF 保持 23，画质不变."""
@@ -96,7 +96,7 @@ class TestWorkerReExport:
         """worker ffmpeg_utils 应 re-export FFMPEG_ENCODE_PRESET."""
         from video_processing.ffmpeg_utils import FFMPEG_ENCODE_PRESET
 
-        assert FFMPEG_ENCODE_PRESET == "fast"
+        assert FFMPEG_ENCODE_PRESET == "veryfast"
 
     def test_worker_reexports_crf(self):
         """worker ffmpeg_utils 应 re-export FFMPEG_ENCODE_CRF."""
@@ -142,11 +142,11 @@ class TestExecuteFfmpegEncoding:
 
         return captured_cmd
 
-    def test_execute_uses_fast_preset(self):
-        """_execute_ffmpeg 应使用 fast preset."""
+    def test_execute_uses_veryfast_preset(self):
+        """_execute_ffmpeg 应使用 veryfast preset."""
         cmd = self._get_execute_command()
         idx = cmd.index("-preset")
-        assert cmd[idx + 1] == "fast"
+        assert cmd[idx + 1] == "veryfast"
 
     def test_execute_uses_crf_23(self):
         """_execute_ffmpeg 应使用 CRF 23."""
@@ -172,8 +172,8 @@ class TestExecuteFfmpegEncoding:
 class TestRenderPassThroughEncoding:
     """测试 _render_pass_through 方法使用正确的编码参数."""
 
-    def test_passthrough_command_contains_fast_preset(self):
-        """_render_pass_through 命令应包含 fast preset."""
+    def test_passthrough_command_contains_veryfast_preset(self):
+        """_render_pass_through 命令应包含 veryfast preset."""
         # 通过源码检查确认参数已替换
         import inspect
 
@@ -200,8 +200,8 @@ class TestRenderPassThroughEncoding:
 class TestNormalizeVideoEncoding:
     """测试 normalize_video 使用正确的编码参数."""
 
-    def test_normalize_uses_fast_preset(self):
-        """normalize_video 应使用 fast preset."""
+    def test_normalize_uses_veryfast_preset(self):
+        """normalize_video 应使用 veryfast preset."""
         import inspect
 
         from video_processing.ffmpeg_utils import normalize_video

tests/unit/test_gpu_encoder.py

@@ -0,0 +1,712 @@
+"""GpuEncoderClient 单元测试：mock HTTP，覆盖 health/sync/fallback/singleton 等完整路径。"""
+
+from __future__ import annotations
+
+import json
+import socket
+import sys
+import urllib.error
+import urllib.request
+from http.client import HTTPResponse
+from io import BytesIO
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+from packages.shared.gpu_encoder import (
+    GpuEncodeError,
+    GpuEncoderClient,
+    GpuHealth,
+    _build_client_from_settings,
+    get_gpu_encoder,
+    is_gpu_encode_enabled,
+    reset_gpu_encoder_for_tests,
+)
+
+
+@pytest.fixture(autouse=True)
+def _reset_singleton():
+    reset_gpu_encoder_for_tests()
+    yield
+    reset_gpu_encoder_for_tests()
+
+
+@pytest.fixture
+def client():
+    return GpuEncoderClient(
+        endpoint="http://gpu.example.com:8900",
+        relay_base_url="http://api.example.com",
+        relay_internal_base_url="http://api-internal:8000",
+        mezzanine_transport="oss",  # 旧测试只 mock OSS 上传，走 OSS 路径
+        sync_timeout=60,
+        health_timeout=2,
+        relay_secret="test-secret",
+    )
+
+
+def _fake_response(status: int = 200, body: dict | bytes | None = None, headers=None):
+    if isinstance(body, dict):
+        data = json.dumps(body).encode("utf-8")
+    elif body is None:
+        data = b""
+    else:
+        data = body
+    bio = BytesIO(data)
+    resp = mock.MagicMock(spec=HTTPResponse)
+    resp.status = status
+    resp.read.side_effect = lambda n=-1: bio.read(n)
+    resp.__enter__ = mock.MagicMock(return_value=resp)
+    resp.__exit__ = mock.MagicMock(return_value=False)
+    return resp
+
+
+# ── Health check ────────────────────────────────────────────────────
+class TestHealthCheck:
+    def test_healthy_nvenc_available(self, client):
+        body = {
+            "status": "healthy",
+            "worker": "w1",
+            "gpu": {"name": "Quadro P4000"},
+            "nvenc": {"h264_nvenc": True, "hevc_nvenc": True},
+        }
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(body=body)):
+            h = client.check_health()
+        assert h.healthy and h.nvenc_h264 and h.ready
+        assert h.gpu_name == "Quadro P4000"
+
+    def test_connection_error_returns_unhealthy(self, client):
+        with mock.patch("urllib.request.urlopen", side_effect=urllib.error.URLError("timeout")):
+            h = client.check_health()
+        assert not h.healthy
+        assert "health probe failed" in h.error
+
+    def test_bad_json_returns_unhealthy(self, client):
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(body=b"not json")):
+            h = client.check_health()
+        assert not h.healthy
+
+    def test_nvenc_unavailable(self, client):
+        body = {"status": "healthy", "gpu": {"name": "t"}, "nvenc": {"h264_nvenc": False}}
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(body=body)):
+            h = client.check_health()
+        assert h.healthy and not h.ready
+
+    def test_malformed_response_inner_exception(self, client):
+        """data 是合法 JSON 但 gpu 字段类型错（字符串）触发内部 except."""
+        body = {"status": "healthy", "gpu": "not-a-dict", "nvenc": {}}
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(body=body)):
+            h = client.check_health()
+        assert not h.healthy
+        assert "malformed" in h.error
+
+
+# ── _post_sync ──────────────────────────────────────────────────────
+class TestPostSync:
+    def test_completed_job_returns_dict(self, client):
+        result_body = {
+            "job_id": "j1",
+            "status": "completed",
+            "ffmpeg_rc": 0,
+            "uploaded": True,
+            "duration": 5.1,
+            "size": 123456,
+        }
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(body=result_body)) as m:
+            res = client._post_sync(
+                {
+                    "inputs": {"in.mp4": "http://x"},
+                    "ffmpeg_args": ["-i", "in.mp4"],
+                    "output_url": "http://relay/k?token=s",
+                    "timeout": 30,
+                },
+            )
+        assert res["status"] == "completed" and res["ffmpeg_rc"] == 0
+        req = m.call_args[0][0]
+        assert req.full_url == "http://gpu.example.com:8900/api/render/sync"
+
+    def test_ffmpeg_failure_raises(self, client):
+        body = {"status": "failed", "ffmpeg_rc": 1, "message": "Invalid data"}
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(body=body)):
+            with pytest.raises(GpuEncodeError, match="rc=1"):
+                client._post_sync({"inputs": {}, "ffmpeg_args": [], "output_url": "", "timeout": 10})
+
+    def test_http_4xx_raises(self, client):
+        err = urllib.error.HTTPError(
+            url="http://gpu/render/sync", code=422, msg="Unprocessable", hdrs={}, fp=BytesIO(b"bad request")
+        )
+        with mock.patch("urllib.request.urlopen", side_effect=err):
+            with pytest.raises(GpuEncodeError, match="HTTP 422"):
+                client._post_sync({"inputs": {}, "ffmpeg_args": [], "output_url": "", "timeout": 10})
+
+    def test_connection_error_raises(self, client):
+        with mock.patch("urllib.request.urlopen", side_effect=urllib.error.URLError("conn refused")):
+            with pytest.raises(GpuEncodeError, match="connection error"):
+                client._post_sync({"inputs": {}, "ffmpeg_args": [], "output_url": "", "timeout": 10})
+
+    def test_timeout_error_raises(self, client):
+        with mock.patch("urllib.request.urlopen", side_effect=socket.timeout("timed out")):
+            with pytest.raises(GpuEncodeError, match="connection error"):
+                client._post_sync({"inputs": {}, "ffmpeg_args": [], "output_url": "", "timeout": 10})
+
+    def test_bad_json_raises(self, client):
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(body=b"not-json")):
+            with pytest.raises(GpuEncodeError, match="bad JSON"):
+                client._post_sync({"inputs": {}, "ffmpeg_args": [], "output_url": "", "timeout": 10})
+
+    def test_uploaded_false_logs_warning_but_succeeds(self, client, caplog):
+        body = {"status": "completed", "ffmpeg_rc": 0, "uploaded": False, "job_id": "j"}
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(body=body)), caplog.at_level("WARNING"):
+            res = client._post_sync({"inputs": {}, "ffmpeg_args": [], "output_url": "", "timeout": 10})
+        assert res["status"] == "completed"
+        assert "uploaded=false" in caplog.text
+
+
+# ── Relay URL builders ──────────────────────────────────────────────
+class TestRelayUrl:
+    def test_result_put_url_uses_external_base(self, client):
+        """P4000 回传编码结果的 PUT URL 应走外部 base（Tailscale 可达）。"""
+        url = client._result_put_url("abc123", "secret!")
+        assert "abc123" in url
+        assert "token=secret%21" in url
+        assert url.startswith("http://api.example.com/api/v1/internal/gpu-relay/")
+        assert "/mezzanine/" not in url
+
+    def test_result_get_url_uses_internal_base(self, client):
+        """Worker 下载结果使用 internal base（Docker DNS 直连）。"""
+        url = client._result_get_url("abc123", "s")
+        assert url.startswith("http://api-internal:8000/api/v1/internal/gpu-relay/abc123")
+        assert "/mezzanine/" not in url
+
+    def test_result_get_url_falls_back_to_external_when_not_set(self):
+        c = GpuEncoderClient(
+            endpoint="http://gpu",
+            relay_base_url="http://api.example.com",
+            relay_secret="s",
+            mezzanine_transport="oss",
+        )
+        put = c._result_put_url("k", "s")
+        get = c._result_get_url("k", "s")
+        assert put.startswith("http://api.example.com/")
+        assert get == put
+
+    def test_encode_uses_different_put_and_get_urls(self, client):
+        put_url = client._result_put_url("k", "test-secret")
+        get_url = client._result_get_url("k", "test-secret")
+        assert "api.example.com" in put_url and "api-internal:8000" in get_url and put_url != get_url
+
+    def test_mezz_put_url_uses_internal_base(self, client):
+        """Worker 上传 mezzanine 的 PUT URL 应走 internal base（Docker 内网快）。"""
+        url = client._mezz_put_url("m1", "test-secret")
+        assert url.startswith("http://api-internal:8000/api/v1/internal/gpu-relay/mezzanine/m1")
+
+    def test_mezz_get_url_for_p4000_uses_external_base(self, client):
+        """P4000 下载 mezzanine 的 GET URL 必须是 P4000 可达的（Tailscale 外部 base）。"""
+        url = client._mezz_get_url_for_p4000("m1", "test-secret")
+        assert url.startswith("http://api.example.com/api/v1/internal/gpu-relay/mezzanine/m1")
+
+    def test_mezz_put_get_use_different_bases(self, client):
+        """worker 上传 mezzanine 用 internal，P4000 下载 mezzanine 用 external。"""
+        put = client._mezz_put_url("m", "test-secret")
+        get = client._mezz_get_url_for_p4000("m", "test-secret")
+        assert "api-internal:8000" in put and "api.example.com" in get and put != get
+
+
+# ── _get_relay_secret ──────────────────────────────────────────────
+class TestGetRelaySecret:
+    def test_explicit_secret_used(self, client):
+        assert client._get_relay_secret() == "test-secret"
+
+    def test_env_secret_used_when_not_explicit(self, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "from-env")
+        monkeypatch.setenv("APP_ENV", "staging")
+        c = GpuEncoderClient(endpoint="http://gpu", relay_base_url="http://api")
+        assert c._get_relay_secret() == "from-env"
+
+    def test_prod_without_secret_raises(self, monkeypatch):
+        monkeypatch.delenv("GPU_ENCODE_RELAY_SECRET", raising=False)
+        monkeypatch.setenv("APP_ENV", "production")
+        c = GpuEncoderClient(endpoint="http://gpu", relay_base_url="http://api")
+        with pytest.raises(GpuEncodeError, match="GPU_ENCODE_RELAY_SECRET"):
+            c._get_relay_secret()
+
+    def test_dev_without_secret_raises(self, monkeypatch):
+        """未设置 secret 且非 production 也 raise（worker 必须显式配置）。"""
+        monkeypatch.delenv("GPU_ENCODE_RELAY_SECRET", raising=False)
+        monkeypatch.setenv("APP_ENV", "development")
+        c = GpuEncoderClient(endpoint="http://gpu", relay_base_url="http://api")
+        with pytest.raises(GpuEncodeError, match="GPU_ENCODE_RELAY_SECRET not set"):
+            c._get_relay_secret()
+
+
+# ── _download_to_file ──────────────────────────────────────────────
+class TestDownloadToFile:
+    def test_writes_file(self, client, tmp_path):
+        data = b"hello" * 1000
+        out = tmp_path / "out.mp4"
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(body=data)):
+            size = client._download_to_file("http://relay/k?token=s", out)
+        assert size == len(data) and out.read_bytes() == data
+
+    def test_empty_file_raises(self, client, tmp_path):
+        out = tmp_path / "out.mp4"
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(body=b"")):
+            with pytest.raises(GpuEncodeError, match="empty file"):
+                client._download_to_file("http://relay/k", out)
+        assert not out.exists()
+
+    def test_non_200_status_raises(self, client, tmp_path):
+        out = tmp_path / "o.mp4"
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(status=404, body=b"")):
+            with pytest.raises(GpuEncodeError, match="HTTP 404"):
+                client._download_to_file("http://relay/k", out)
+
+    def test_url_error_cleans_up_tmp(self, client, tmp_path):
+        out = tmp_path / "o.mp4"
+        tmp_file = out.with_suffix(out.suffix + ".gpu_tmp")
+        tmp_file.write_bytes(b"partial")
+        assert tmp_file.exists()
+        with mock.patch("urllib.request.urlopen", side_effect=urllib.error.URLError("net down")):
+            with pytest.raises(GpuEncodeError, match="failed to download"):
+                client._download_to_file("http://relay/k", out)
+        assert not tmp_file.exists()
+
+
+# ── encode_mezzanine_to_output ─────────────────────────────────────
+class TestEncodeMezzanine:
+    def test_happy_path_with_audio(self, client, tmp_path):
+        mezz = tmp_path / "mezz.mp4"
+        mezz.write_bytes(b"M" * 100)
+        out = tmp_path / "out" / "final.mp4"
+        with (
+            mock.patch.object(client, "_upload_mezzanine_to_oss", return_value=("http://oss/signed", "osskey1")),
+            mock.patch.object(
+                client,
+                "_post_sync",
+                return_value={
+                    "job_id": "j1",
+                    "status": "completed",
+                    "ffmpeg_rc": 0,
+                    "uploaded": True,
+                    "size": 5000,
+                    "duration": 1.2,
+                },
+            ) as m_post,
+            mock.patch.object(client, "_download_to_file", return_value=5000) as m_dl,
+            mock.patch.object(client, "_relay_delete") as m_del,
+            mock.patch.object(client, "_delete_oss") as m_ossdel,
+        ):
+            result = client.encode_mezzanine_to_output(mezz, out, audio_args=["-c:a", "aac"])
+        assert result["output_size"] == 5000 and str(out) == result["output_path"]
+        body = m_post.call_args[0][0]
+        assert "-c:a" in body["ffmpeg_args"] and "aac" in body["ffmpeg_args"]
+        assert "-an" not in body["ffmpeg_args"]
+        assert body["output_url"].startswith("http://api.example.com/")
+        assert "api-internal:8000" in m_dl.call_args[0][0]
+        m_del.assert_called_once()
+        m_ossdel.assert_called_once_with("osskey1")
+
+    def test_happy_path_no_audio_uses_an_and_cq(self, client, tmp_path):
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"M")
+        out = tmp_path / "o.mp4"
+        with (
+            mock.patch.object(client, "_upload_mezzanine_to_oss", return_value=("http://oss/u", "k")),
+            mock.patch.object(
+                client,
+                "_post_sync",
+                return_value={"status": "completed", "ffmpeg_rc": 0, "uploaded": True, "job_id": "j"},
+            ) as m_post,
+            mock.patch.object(client, "_download_to_file", return_value=100),
+            mock.patch.object(client, "_relay_delete"),
+            mock.patch.object(client, "_delete_oss"),
+        ):
+            client.encode_mezzanine_to_output(mezz, out)
+            body = m_post.call_args[0][0]
+            assert "-an" in body["ffmpeg_args"] and "-cq" in body["ffmpeg_args"]
+            assert str(client.crf) in body["ffmpeg_args"]
+
+    def test_bitrate_set_uses_bv_instead_of_cq(self, tmp_path):
+        c = GpuEncoderClient(
+            endpoint="http://gpu",
+            relay_base_url="http://api",
+            relay_internal_base_url="http://api-int:8000",
+            relay_secret="s",
+            bitrate="2M",
+        )
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"x")
+        out = tmp_path / "o.mp4"
+        with (
+            mock.patch.object(c, "_upload_mezzanine_to_oss", return_value=("http://oss/u", "k")),
+            mock.patch.object(
+                c, "_post_sync", return_value={"status": "completed", "ffmpeg_rc": 0, "uploaded": True, "job_id": "j"}
+            ) as m_post,
+            mock.patch.object(c, "_download_to_file", return_value=10),
+            mock.patch.object(c, "_relay_delete"),
+            mock.patch.object(c, "_delete_oss"),
+        ):
+            c.encode_mezzanine_to_output(mezz, out, extra_video_args=["-vf", "scale=1280:-2"])
+            body = m_post.call_args[0][0]
+            assert "-b:v" in body["ffmpeg_args"] and "2M" in body["ffmpeg_args"]
+            assert "-cq" not in body["ffmpeg_args"]
+            assert "-vf" in body["ffmpeg_args"]
+
+    def test_mezzanine_not_found_raises(self, client, tmp_path):
+        with pytest.raises(GpuEncodeError, match="mezzanine file not found"):
+            client.encode_mezzanine_to_output(tmp_path / "nope.mp4", tmp_path / "o.mp4")
+
+    def test_relay_base_not_configured_raises(self, tmp_path):
+        c = GpuEncoderClient(endpoint="http://gpu", relay_base_url="", relay_secret="s")
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"x")
+        with pytest.raises(GpuEncodeError, match="relay_base_url"):
+            c.encode_mezzanine_to_output(mezz, tmp_path / "o.mp4")
+
+    def test_unexpected_exception_is_wrapped(self, client, tmp_path):
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"x")
+        with (
+            mock.patch.object(client, "_upload_mezzanine_to_oss", return_value=("http://oss/u", "k")),
+            mock.patch.object(client, "_post_sync", side_effect=RuntimeError("boom")),
+            mock.patch.object(client, "_delete_oss"),
+        ):
+            with pytest.raises(GpuEncodeError, match="unexpected: boom"):
+                client.encode_mezzanine_to_output(mezz, tmp_path / "o.mp4")
+
+    def test_gpu_encode_error_re_raised_directly(self, client, tmp_path):
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"x")
+        with (
+            mock.patch.object(client, "_upload_mezzanine_to_oss", return_value=("http://oss/u", "k")),
+            mock.patch.object(client, "_post_sync", side_effect=GpuEncodeError("direct fail")),
+            mock.patch.object(client, "_delete_oss"),
+        ):
+            with pytest.raises(GpuEncodeError, match="direct fail"):
+                client.encode_mezzanine_to_output(mezz, tmp_path / "o.mp4")
+
+    def test_oss_cleanup_runs_on_failure(self, client, tmp_path, caplog):
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"x")
+        with (
+            mock.patch.object(client, "_upload_mezzanine_to_oss", return_value=("http://oss/u", "ossk")),
+            mock.patch.object(client, "_post_sync", side_effect=GpuEncodeError("enc fail")),
+            mock.patch.object(client, "_delete_oss", side_effect=Exception("oss down")) as m_ossdel,
+            caplog.at_level("WARNING"),
+        ):
+            with pytest.raises(GpuEncodeError):
+                client.encode_mezzanine_to_output(mezz, tmp_path / "o.mp4")
+            m_ossdel.assert_called_once_with("ossk")
+
+
+# ── _relay_delete ──────────────────────────────────────────────────
+class TestRelayDelete:
+    def test_exception_is_swallowed(self, client, caplog):
+        with mock.patch("urllib.request.urlopen", side_effect=RuntimeError("boom")), caplog.at_level("DEBUG"):
+            client._relay_delete("http://relay/k?token=s")
+        assert "cleanup delete failed" in caplog.text
+
+    def test_success_issues_delete(self, client):
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(status=204, body=b"")) as m:
+            client._relay_delete("http://relay/k?token=s")
+        assert m.call_args[0][0].get_method() == "DELETE"
+
+
+# ── OSS helpers ────────────────────────────────────────────────────
+class TestOssHelpers:
+    def test_upload_storage_import_error(self, client, tmp_path):
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"x")
+        # 删除 sys.modules 中 packages.shared.storage 使导入失败
+        saved = sys.modules.pop("packages.shared.storage", None)
+        try:
+            real_import = __builtins__.__import__ if hasattr(__builtins__, "__import__") else __import__
+
+            def fake_import(name, *a, **kw):
+                if name == "packages.shared.storage" or name.startswith("packages.shared.storage."):
+                    raise ImportError("no storage")
+                return real_import(name, *a, **kw)
+
+            with mock.patch("builtins.__import__", side_effect=fake_import):
+                with pytest.raises(GpuEncodeError, match="storage service unavailable"):
+                    client._upload_mezzanine_to_oss(mezz)
+        finally:
+            if saved is not None:
+                sys.modules["packages.shared.storage"] = saved
+
+    def test_upload_storage_none(self, client, tmp_path):
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"x")
+        fake_mod = mock.MagicMock()
+        fake_mod.get_storage_service.return_value = None
+        with mock.patch.dict("sys.modules", {"packages.shared.storage": fake_mod}):
+            with pytest.raises(GpuEncodeError, match="OSS storage not configured"):
+                client._upload_mezzanine_to_oss(mezz)
+
+    def test_upload_bucket_none(self, client, tmp_path):
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"x")
+        svc = mock.MagicMock()
+        svc.bucket = None
+        fake_mod = mock.MagicMock()
+        fake_mod.get_storage_service.return_value = svc
+        with mock.patch.dict("sys.modules", {"packages.shared.storage": fake_mod}):
+            with pytest.raises(GpuEncodeError, match="OSS storage not configured"):
+                client._upload_mezzanine_to_oss(mezz)
+
+    def test_upload_failure_raises(self, client, tmp_path):
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"x")
+        svc = mock.MagicMock()
+        svc.bucket = object()
+        svc.upload_file.side_effect = RuntimeError("oss err")
+        fake_mod = mock.MagicMock()
+        fake_mod.get_storage_service.return_value = svc
+        with mock.patch.dict("sys.modules", {"packages.shared.storage": fake_mod}):
+            with pytest.raises(GpuEncodeError, match="failed to upload mezzanine"):
+                client._upload_mezzanine_to_oss(mezz)
+
+    def test_upload_success(self, client, tmp_path):
+        mezz = tmp_path / "m.mp4"
+        mezz.write_bytes(b"x")
+        svc = mock.MagicMock()
+        svc.bucket = object()
+        svc.get_download_url.return_value = "https://oss/signed?sig=abc"
+        fake_mod = mock.MagicMock()
+        fake_mod.get_storage_service.return_value = svc
+        with mock.patch.dict("sys.modules", {"packages.shared.storage": fake_mod}):
+            url, key = client._upload_mezzanine_to_oss(mezz)
+        assert url.startswith("https://oss/signed")
+        assert key.startswith("tmp/gpu-mezzanine/") and key.endswith(".mp4")
+        svc.upload_file.assert_called_once()
+
+    def test_delete_oss_exception_swallowed(self, client, caplog):
+        fake_mod = mock.MagicMock()
+        fake_mod.get_storage_service.side_effect = RuntimeError("svc down")
+        with mock.patch.dict("sys.modules", {"packages.shared.storage": fake_mod}), caplog.at_level("DEBUG"):
+            client._delete_oss("somekey")
+        assert "OSS delete" in caplog.text
+
+    def test_delete_oss_bucket_none_noop(self, client):
+        svc = mock.MagicMock()
+        svc.bucket = None
+        fake_mod = mock.MagicMock()
+        fake_mod.get_storage_service.return_value = svc
+        with mock.patch.dict("sys.modules", {"packages.shared.storage": fake_mod}):
+            client._delete_oss("k")
+        svc.delete_file.assert_not_called()
+
+    def test_delete_oss_success(self, client):
+        svc = mock.MagicMock()
+        svc.bucket = object()
+        fake_mod = mock.MagicMock()
+        fake_mod.get_storage_service.return_value = svc
+        with mock.patch.dict("sys.modules", {"packages.shared.storage": fake_mod}):
+            client._delete_oss("k")
+        svc.delete_file.assert_called_once_with("k")
+
+
+# ── encode_mezzanine_to_output: relay transport (default path) ──────
+class TestEncodeMezzanineRelay:
+    def test_relay_happy_path_uploads_to_relay(self, tmp_path):
+        """默认 relay 模式：worker PUT mezzanine 到 internal relay；P4000 GET 用 external base。"""
+        c = GpuEncoderClient(
+            endpoint="http://gpu.example.com:8900",
+            relay_base_url="http://api.example.com",
+            relay_internal_base_url="http://api-internal:8000",
+            mezzanine_transport="relay",
+            sync_timeout=60,
+            relay_secret="test-secret",
+        )
+        mezz = tmp_path / "mezz.mp4"
+        mezz.write_bytes(b"X" * 200)
+        out = tmp_path / "out.mp4"
+        with (
+            mock.patch.object(c, "_upload_file_put") as m_put,
+            mock.patch.object(
+                c,
+                "_post_sync",
+                return_value={
+                    "job_id": "j",
+                    "status": "completed",
+                    "ffmpeg_rc": 0,
+                    "uploaded": True,
+                    "size": 100,
+                    "duration": 1.0,
+                },
+            ) as m_post,
+            mock.patch.object(c, "_download_to_file", return_value=100),
+            mock.patch.object(c, "_relay_delete") as m_del,
+            mock.patch.object(c, "_delete_oss") as m_ossdel,
+        ):
+            result = c.encode_mezzanine_to_output(mezz, out)
+        assert result["transport"] == "relay"
+        # _upload_file_put called once (mezz uploaded to relay)
+        m_put.assert_called_once()
+        put_url = m_put.call_args[0][0]
+        assert "/api/v1/internal/gpu-relay/mezzanine/" in put_url
+        assert "api-internal:8000" in put_url  # worker uses internal
+        # P4000 body.inputs["in.mp4"] must use external base (P4000 reachable)
+        body = m_post.call_args[0][0]
+        assert body["inputs"]["in.mp4"].startswith("http://api.example.com/api/v1/internal/gpu-relay/mezzanine/")
+        # No OSS involved
+        m_ossdel.assert_not_called()
+        # cleanup: one result delete + one mezz delete
+        assert m_del.call_count == 2
+
+    def test_relay_put_failure_falls_back_to_oss(self, tmp_path):
+        """relay PUT 失败时应自动 fallback 到 OSS，且 transport 标记为 oss。"""
+        c = GpuEncoderClient(
+            endpoint="http://gpu.example.com:8900",
+            relay_base_url="http://api.example.com",
+            relay_internal_base_url="http://api-internal:8000",
+            mezzanine_transport="relay",
+            sync_timeout=60,
+            relay_secret="test-secret",
+        )
+        mezz = tmp_path / "mezz.mp4"
+        mezz.write_bytes(b"X")
+        out = tmp_path / "out.mp4"
+        with (
+            mock.patch.object(c, "_upload_file_put", side_effect=GpuEncodeError("relay 500")),
+            mock.patch.object(c, "_upload_mezzanine_to_oss", return_value=("https://oss/signed", "ossk")),
+            mock.patch.object(
+                c,
+                "_post_sync",
+                return_value={"job_id": "j", "status": "completed", "ffmpeg_rc": 0, "uploaded": True},
+            ) as m_post,
+            mock.patch.object(c, "_download_to_file", return_value=50),
+            mock.patch.object(c, "_relay_delete"),
+            mock.patch.object(c, "_delete_oss") as m_ossdel,
+        ):
+            result = c.encode_mezzanine_to_output(mezz, out)
+        assert result["transport"] == "oss"
+        body = m_post.call_args[0][0]
+        assert body["inputs"]["in.mp4"] == "https://oss/signed"
+        m_ossdel.assert_called_once_with("ossk")
+
+    def test_upload_file_put_streaming_sends_content_length(self, client, tmp_path):
+        """_upload_file_put 应用 Content-Length 头发送文件。"""
+        f = tmp_path / "x.mp4"
+        f.write_bytes(b"ABCDEFGH")  # 8 bytes
+        captured = {}
+
+        def fake_urlopen(req, timeout=None):
+            captured["method"] = req.get_method()
+            captured["cl"] = req.get_header("Content-length")
+            captured["ct"] = req.get_header("Content-type")
+            captured["data"] = req.data.read()
+            return _fake_response(status=200, body=b"")
+
+        with mock.patch("urllib.request.urlopen", side_effect=fake_urlopen):
+            client._upload_file_put("http://relay/m?token=s", f, "video/mp4")
+        assert captured["method"] == "PUT"
+        assert captured["cl"] == "8"
+        assert captured["ct"] == "video/mp4"
+        assert captured["data"] == b"ABCDEFGH"
+
+    def test_upload_file_put_non_2xx_raises(self, client, tmp_path):
+        f = tmp_path / "x.mp4"
+        f.write_bytes(b"x")
+        with mock.patch("urllib.request.urlopen", return_value=_fake_response(status=500, body=b"err")):
+            with pytest.raises(GpuEncodeError, match="relay PUT failed"):
+                client._upload_file_put("http://relay/m", f, "video/mp4")
+
+
+# ── Singleton / factory ────────────────────────────────────────────
+class TestSingletonFactory:
+    def test_build_client_import_error_returns_none(self):
+        saved = sys.modules.get("packages.config")
+        sys.modules["packages.config"] = None
+        try:
+            with mock.patch("builtins.__import__", side_effect=RuntimeError("no cfg")):
+                assert _build_client_from_settings() is None
+        finally:
+            if saved is not None:
+                sys.modules["packages.config"] = saved
+
+    def test_build_client_not_enabled_returns_none(self):
+        s = mock.MagicMock()
+        s.enable_gpu_encode = False
+        fake_mod = mock.MagicMock()
+        fake_mod.get_shared_settings.return_value = s
+        with mock.patch.dict("sys.modules", {"packages.config": fake_mod}):
+            assert _build_client_from_settings() is None
+
+    def test_build_client_missing_endpoint(self):
+        s = mock.MagicMock()
+        s.enable_gpu_encode = True
+        s.gpu_encode_endpoint = ""
+        s.gpu_encode_relay_base_url = "http://api"
+        s.gpu_encode_relay_internal_base_url = ""
+        fake_mod = mock.MagicMock()
+        fake_mod.get_shared_settings.return_value = s
+        with mock.patch.dict("sys.modules", {"packages.config": fake_mod}):
+            assert _build_client_from_settings() is None
+
+    def test_build_client_missing_relay(self):
+        s = mock.MagicMock()
+        s.enable_gpu_encode = True
+        s.gpu_encode_endpoint = "http://gpu"
+        s.gpu_encode_relay_base_url = ""
+        s.gpu_encode_relay_internal_base_url = ""
+        fake_mod = mock.MagicMock()
+        fake_mod.get_shared_settings.return_value = s
+        with mock.patch.dict("sys.modules", {"packages.config": fake_mod}):
+            assert _build_client_from_settings() is None
+
+    def test_build_client_success(self):
+        s = mock.MagicMock()
+        s.enable_gpu_encode = True
+        s.gpu_encode_endpoint = "http://gpu"
+        s.gpu_encode_relay_base_url = "http://api/"
+        s.gpu_encode_relay_internal_base_url = "http://api-int:8000/"
+        s.gpu_encode_sync_timeout = 120
+        s.gpu_encode_health_timeout = 1.0
+        s.gpu_encode_vcodec = "h264_nvenc"
+        s.gpu_encode_preset = "p7"
+        s.gpu_encode_crf = 20
+        s.gpu_encode_bitrate = ""
+        s.gpu_encode_relay_secret = "s"
+        s.gpu_encode_oss_tmp_prefix = "tmp/x/"
+        s.gpu_encode_mezzanine_transport = "relay"
+        fake_mod = mock.MagicMock()
+        fake_mod.get_shared_settings.return_value = s
+        with mock.patch.dict("sys.modules", {"packages.config": fake_mod}):
+            c = _build_client_from_settings()
+        assert c is not None and c.endpoint == "http://gpu"
+        assert c.relay_base_url == "http://api"
+        assert c.relay_internal_base_url == "http://api-int:8000"
+        assert c.preset == "p7" and c.crf == 20
+        assert c.mezzanine_transport == "relay"
+
+    def test_get_gpu_encoder_init_failure_returns_none(self, caplog):
+        with (
+            mock.patch("packages.shared.gpu_encoder._build_client_from_settings", side_effect=RuntimeError("boom")),
+            caplog.at_level("WARNING"),
+        ):
+            assert get_gpu_encoder() is None
+        assert "failed to init client" in caplog.text
+
+    def test_get_gpu_encoder_returns_singleton_and_enabled(self):
+        c = GpuEncoderClient(endpoint="http://gpu", relay_base_url="http://api", relay_secret="s")
+        with mock.patch("packages.shared.gpu_encoder._build_client_from_settings", return_value=c):
+            assert get_gpu_encoder() is c and get_gpu_encoder() is c
+        assert is_gpu_encode_enabled() is True
+
+    def test_is_gpu_encode_enabled_when_none(self):
+        with mock.patch("packages.shared.gpu_encoder._build_client_from_settings", return_value=None):
+            assert is_gpu_encode_enabled() is False
+
+
+# ── Constructor edge cases ────────────────────────────────────────
+class TestConstructor:
+    def test_oss_tmp_prefix_empty_uses_default(self):
+        c = GpuEncoderClient(endpoint="http://gpu", relay_base_url="http://api", relay_secret="s", oss_tmp_prefix="")
+        assert c.oss_tmp_prefix == "tmp/gpu-mezzanine/"
+
+    def test_oss_tmp_prefix_strips_and_adds_slash(self):
+        c = GpuEncoderClient(
+            endpoint="http://gpu", relay_base_url="http://api", relay_secret="s", oss_tmp_prefix="tmp/foo"
+        )
+        assert c.oss_tmp_prefix == "tmp/foo/"

tests/unit/test_gpu_relay.py

@@ -0,0 +1,240 @@
+"""gpu_relay API 路由单元测试：覆盖 helper 函数 + PUT/GET/HEAD/DELETE handler。"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from unittest import mock
+
+import pytest
+from fastapi import HTTPException
+
+from apps.api.app.api.routes import gpu_relay
+
+
+# ── _relay_dir ────────────────────────────────────────────────────────
+class TestRelayDir:
+    def test_default_dir(self, tmp_path, monkeypatch):
+        monkeypatch.delenv("GENERATED_FILES_DIR", raising=False)
+        monkeypatch.delenv("GPU_ENCODE_RELAY_DIR", raising=False)
+        # 用 tmp_path 作 base
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        p = gpu_relay._relay_dir()
+        assert p == tmp_path / "gpu_relay"
+        assert p.exists()
+
+    def test_custom_subdir(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        monkeypatch.setenv("GPU_ENCODE_RELAY_DIR", "custom_relay")
+        p = gpu_relay._relay_dir()
+        assert p == tmp_path / "custom_relay"
+        assert p.exists()
+
+
+# ── _secret ──────────────────────────────────────────────────────────
+class TestSecret:
+    def test_explicit_secret_returned(self, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "topsecret")
+        gpu_relay._DEFAULT_SECRET_LOGGED = False
+        assert gpu_relay._secret() == "topsecret"
+
+    def test_prod_without_secret_raises(self, monkeypatch):
+        monkeypatch.delenv("GPU_ENCODE_RELAY_SECRET", raising=False)
+        monkeypatch.setenv("APP_ENV", "production")
+        with pytest.raises(RuntimeError, match="GPU_ENCODE_RELAY_SECRET must be set"):
+            gpu_relay._secret()
+
+    def test_dev_without_secret_generates_ephemeral(self, monkeypatch, caplog):
+        monkeypatch.delenv("GPU_ENCODE_RELAY_SECRET", raising=False)
+        monkeypatch.setenv("APP_ENV", "development")
+        gpu_relay._DEFAULT_SECRET_LOGGED = False
+        with caplog.at_level("WARNING"):
+            secret = gpu_relay._secret()
+        assert len(secret) > 16
+        assert "ephemeral dev token" in caplog.text
+        # 第二次调用不再 log（_DEFAULT_SECRET_LOGGED=True）
+        before = len(caplog.records)
+        secret2 = gpu_relay._secret()
+        assert secret2 == secret
+        assert len(caplog.records) == before
+        # 清理
+        monkeypatch.delenv("GPU_ENCODE_RELAY_SECRET", raising=False)
+
+
+# ── _safe_key ────────────────────────────────────────────────────────
+class TestSafeKey:
+    @pytest.mark.parametrize("bad", ["", "../etc", "a/b", "a\\b", ".", "..", "a b", "a%b"])
+    def test_invalid_keys_rejected(self, bad):
+        with pytest.raises(HTTPException) as ei:
+            gpu_relay._safe_key(bad)
+        assert ei.value.status_code == 400
+
+    @pytest.mark.parametrize("good", ["abc123", "ABC-Def_01", "a" * 32])
+    def test_valid_keys_accepted(self, good):
+        assert gpu_relay._safe_key(good) == good
+
+    def test_strips_whitespace(self):
+        assert gpu_relay._safe_key("  abc  ") == "abc"
+
+
+# ── _check_token ─────────────────────────────────────────────────────
+class TestCheckToken:
+    def test_missing_token_401(self):
+        with pytest.raises(HTTPException) as ei:
+            gpu_relay._check_token(None)
+        assert ei.value.status_code == 401
+
+    def test_wrong_token_401(self, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "correct")
+        with pytest.raises(HTTPException) as ei:
+            gpu_relay._check_token("wrong")
+        assert ei.value.status_code == 401
+
+    def test_correct_token_passes(self, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "correct")
+        assert gpu_relay._check_token("correct") is None
+
+
+# ── build_relay_* helpers ───────────────────────────────────────────
+class TestBuildRelayUrls:
+    def test_put_url(self):
+        url = gpu_relay.build_relay_put_url("http://api.example.com/", "k1", "s")
+        assert url == "http://api.example.com/api/v1/internal/gpu-relay/k1?token=s"
+
+    def test_get_url_same_as_put(self):
+        assert gpu_relay.build_relay_get_url("http://api", "k", "s") == gpu_relay.build_relay_put_url(
+            "http://api", "k", "s"
+        )
+
+    def test_generate_key_is_hex(self):
+        k = gpu_relay.generate_key()
+        assert len(k) == 32
+        int(k, 16)  # valid hex
+
+
+# ── PUT endpoint ────────────────────────────────────────────────────
+@pytest.mark.asyncio
+class TestPutObject:
+    async def test_put_writes_file(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "s")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+
+        # async request.stream 模拟
+        async def _stream():
+            yield b"chunk1"
+            yield b"chunk2"
+
+        req = mock.MagicMock()
+        req.stream = _stream
+        resp = await gpu_relay.put_object(key="abc123", request=req, token="s")
+        assert resp["ok"] is True
+        assert resp["size"] == len(b"chunk1") + len(b"chunk2")
+        p = tmp_path / "gpu_relay" / "abc123"
+        assert p.read_bytes() == b"chunk1chunk2"
+        # .part 临时文件应已 rename
+        assert not p.with_suffix(p.suffix + ".part").exists()
+
+    async def test_put_invalid_key_400(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "s")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        req = mock.MagicMock()
+        with pytest.raises(HTTPException) as ei:
+            await gpu_relay.put_object(key="../bad", request=req, token="s")
+        assert ei.value.status_code == 400
+
+    async def test_put_bad_token_401(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "correct")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        req = mock.MagicMock()
+        with pytest.raises(HTTPException) as ei:
+            await gpu_relay.put_object(key="abc", request=req, token="wrong")
+        assert ei.value.status_code == 401
+
+    async def test_put_write_error_cleans_tmp(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "s")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+
+        async def _bad_stream():
+            yield b"x"
+            raise OSError("disk full")
+
+        req = mock.MagicMock()
+        req.stream = _bad_stream
+        with pytest.raises(HTTPException) as ei:
+            await gpu_relay.put_object(key="abc", request=req, token="s")
+        assert ei.value.status_code == 500
+        # tmp 文件被清理
+        part = tmp_path / "gpu_relay" / "abc.part"
+        assert not part.exists()
+
+
+# ── GET endpoint ────────────────────────────────────────────────────
+@pytest.mark.asyncio
+class TestGetObject:
+    async def test_get_missing_404(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "s")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        with pytest.raises(HTTPException) as ei:
+            await gpu_relay.get_object(key="nope", token="s")
+        assert ei.value.status_code == 404
+
+    async def test_get_returns_file(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "s")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        p = tmp_path / "gpu_relay" / "exist"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(b"viddata")
+        resp = await gpu_relay.get_object(key="exist", token="s")
+        assert resp.media_type == "video/mp4"
+
+
+# ── HEAD endpoint ───────────────────────────────────────────────────
+@pytest.mark.asyncio
+class TestHeadObject:
+    async def test_head_missing_404(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "s")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        resp = await gpu_relay.head_object(key="nope", token="s")
+        assert resp.status_code == 404
+
+    async def test_head_returns_content_length(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "s")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        p = tmp_path / "gpu_relay" / "k"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(b"12345")
+        resp = await gpu_relay.head_object(key="k", token="s")
+        assert resp.status_code == 200
+        assert resp.headers["Content-Length"] == "5"
+
+
+# ── DELETE endpoint ──────────────────────────────────────────────────
+@pytest.mark.asyncio
+class TestDeleteObject:
+    async def test_delete_existing(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "s")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        p = tmp_path / "gpu_relay" / "k"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(b"x")
+        resp = await gpu_relay.delete_object(key="k", token="s")
+        assert resp["ok"] is True
+        assert not p.exists()
+
+    async def test_delete_missing_is_noop(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "s")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        # 不存在时不应 404，返回 ok
+        resp = await gpu_relay.delete_object(key="nope", token="s")
+        assert resp["ok"] is True
+
+    async def test_delete_unlink_error_500(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("GPU_ENCODE_RELAY_SECRET", "s")
+        monkeypatch.setenv("GENERATED_FILES_DIR", str(tmp_path))
+        p = tmp_path / "gpu_relay" / "k"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(b"x")
+        with mock.patch.object(Path, "unlink", side_effect=OSError("perm denied")):
+            with pytest.raises(HTTPException) as ei:
+                await gpu_relay.delete_object(key="k", token="s")
+        assert ei.value.status_code == 500

tests/unit/test_voice_clone_cleanup.py

@@ -0,0 +1,156 @@
+"""SQLAlchemyVoiceCloneProfileRepository.cleanup_stale_processing 单元测试。
+
+通过 monkeypatch sys.modules['packages.adapters.sqlalchemy_impl.models']，
+注入一个具备 SQLAlchemy 列比较语义（== / < 返回可链式 .all() 的 mock）的假模型类，
+不依赖真实 DB，也不会触发 SQLAlchemy 映射。
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import UTC, datetime, timedelta
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+
+class _Col:
+    """模拟 SQLAlchemy Column：比较运算返回 MagicMock，可被 filter 链式调用。"""
+
+    def __init__(self, name: str):
+        self._name = name
+
+    def __eq__(self, other):  # type: ignore[override]
+        return MagicMock(name=f"{self._name}=={other!r}")
+
+    def __ne__(self, other):  # type: ignore[override]
+        return MagicMock(name=f"{self._name}!={other!r}")
+
+    def __lt__(self, other):
+        return MagicMock(name=f"{self._name}<{other!r}")
+
+    def __gt__(self, other):
+        return MagicMock(name=f"{self._name}>{other!r}")
+
+    def __le__(self, other):
+        return MagicMock(name=f"{self._name}<={other!r}")
+
+    def __ge__(self, other):
+        return MagicMock(name=f"{self._name}>={other!r}")
+
+    def __hash__(self):
+        return id(self)
+
+
+class _FakeVoiceCloneProfileModel:
+    """假模型：类属性是 _Col；实例上可读写 status/error_message/updated_at。"""
+
+    status = _Col("status")
+    updated_at = _Col("updated_at")
+    id = _Col("id")
+    error_message = _Col("error_message")
+
+    def __init__(self, **kwargs):
+        self.__dict__.update(kwargs)
+
+
+# ── 预注入 mock 模型模块，避免真实 import 拉起 DB / SQLAlchemy 映射 ──
+_fake_models = SimpleNamespace(VoiceCloneProfileModel=_FakeVoiceCloneProfileModel)
+sys.modules.setdefault("packages.adapters.sqlalchemy_impl.models", _fake_models)
+if "packages.adapters.sqlalchemy_impl.voice_clone_profile_repository" in sys.modules:
+    mod = sys.modules["packages.adapters.sqlalchemy_impl.voice_clone_profile_repository"]
+    mod.VoiceCloneProfileModel = _FakeVoiceCloneProfileModel  # type: ignore[attr-defined]
+
+from packages.adapters.sqlalchemy_impl.voice_clone_profile_repository import (
+    SQLAlchemyVoiceCloneProfileRepository,
+)
+
+
+def _make_fake_row(
+    *,
+    status: str = "processing",
+    updated_at: datetime | None = None,
+    error_message: str = "",
+) -> _FakeVoiceCloneProfileModel:
+    return _FakeVoiceCloneProfileModel(
+        status=status,
+        error_message=error_message,
+        updated_at=updated_at or datetime.now(UTC),
+    )
+
+
+def _make_repo(fake_rows: list[_FakeVoiceCloneProfileModel]):
+    """构造 repo + mock session。
+
+    生产代码使用 .query(Model).filter(A, B).all()（一次 filter，两个表达式参数）。
+    """
+    session = MagicMock()
+    filtered = MagicMock()
+    filtered.all.return_value = list(fake_rows)
+    session.query.return_value.filter.return_value = filtered
+
+    repo = SQLAlchemyVoiceCloneProfileRepository.__new__(SQLAlchemyVoiceCloneProfileRepository)
+    repo.session = session
+    return repo, session
+
+
+class TestCleanupStaleProcessing:
+    """cleanup_stale_processing 行为测试。"""
+
+    def test_no_stale_records_returns_zero_and_no_commit(self):
+        """无卡死记录时返回 0，不调用 commit。"""
+        repo, session = _make_repo([])
+        assert repo.cleanup_stale_processing() == 0
+        session.commit.assert_not_called()
+
+    def test_stale_record_marked_failed_with_timeout_message(self):
+        """超时 processing 记录被标记为 failed，错误信息包含超时分钟数。"""
+        old = _make_fake_row(updated_at=datetime.now(UTC) - timedelta(minutes=15))
+        repo, session = _make_repo([old])
+
+        count = repo.cleanup_stale_processing(timeout_minutes=10)
+
+        assert count == 1
+        assert old.status == "failed"
+        assert "超时" in old.error_message
+        assert "10" in old.error_message
+        session.commit.assert_called_once()
+
+    def test_error_message_reflects_custom_timeout(self):
+        """自定义 timeout_minutes 会反映在错误信息里。"""
+        old = _make_fake_row(updated_at=datetime.now(UTC) - timedelta(hours=1))
+        repo, _session = _make_repo([old])
+
+        repo.cleanup_stale_processing(timeout_minutes=5)
+
+        assert old.status == "failed"
+        assert "5" in old.error_message
+
+    def test_multiple_stale_records_all_cleaned_in_single_commit(self):
+        """多条卡死记录都被清理，返回正确计数并只 commit 一次。"""
+        m1 = _make_fake_row(updated_at=datetime.now(UTC) - timedelta(minutes=20))
+        m2 = _make_fake_row(updated_at=datetime.now(UTC) - timedelta(minutes=11))
+        repo, session = _make_repo([m1, m2])
+
+        assert repo.cleanup_stale_processing(timeout_minutes=10) == 2
+        assert m1.status == "failed"
+        assert m2.status == "failed"
+        session.commit.assert_called_once()
+
+    def test_queries_model_with_status_and_updated_at_filters(self):
+        """query 被调用，filter 同时传入 status=='processing' 与 updated_at<cutoff 两个条件。
+
+        注：不同测试加载顺序下 sys.modules['packages...models'] 可能是真模型类
+        （因为其他测试文件已先 import），所以这里不断言模型类身份，
+        只断言 query/filter 被正确调用。
+        """
+        repo, session = _make_repo([])
+        repo.cleanup_stale_processing()
+
+        assert session.query.called, "session.query 应被调用"
+        # filter 被调用一次，且传入两个过滤表达式
+        q = session.query.return_value
+        assert q.filter.called, "query.filter 应被调用"
+        args_f, _kwargs = q.filter.call_args
+        assert len(args_f) == 2, f"filter 应接收 2 个位置参数（status + updated_at），实际 {len(args_f)}"

tests/unit/test_voice_clone_task.py

@@ -8,13 +8,14 @@
 Celery bind=True 任务的底层函数签名为 (self, profile_id)，
 CosyVoiceService 在 voice_clone.py 中被实例化传入 workflow，必须 mock 防止真实初始化。
 
-跨环境兼容：
-  Python 3.13 + Celery 5.4.0 → import 返回 Celery Proxy
-    → _get_current_object() 返回 Task 实例 → .run 是 bound method（self 已绑定）
-    → 调用方式：task.run(profile_id)，retry mock 在 task.run.retry
-  Python 3.10 + Celery 5.4.0 → import 返回原始函数（装饰器未生效）
-    → 签名 (self, profile_id)，需手动传 mock_self
-    → 调用方式：func(mock_self, profile_id)，retry mock 在 mock_self.retry
+跨环境兼容（_resolve_task）：
+  不同 Celery 版本 / Python 版本 / 是否有 active Celery app，task 对象形态不同：
+    1) Celery Proxy（LocalProxy/LazyProxy）：import 结果是代理对象，调用
+       _get_current_object() 可能抛 RuntimeError（无 active context），必须 try 保护。
+       成功取到真实 Task 实例后，使用 bound method .run。
+    2) Celery Task 实例（bind=True 时 @task 返回的典型形态）：直接有 .run/.retry。
+    3) 原始函数（某些环境装饰器未生效或 patch 时序问题）：需手动传 mock_self。
+  统一返回 (callable, mock_self, real_task)，调用方不需要重复解析。
 """
 
 from __future__ import annotations
@@ -58,24 +59,33 @@ def _make_mock_profile(
 
 
 def _resolve_task(task_obj):
-    """解析 Celery 任务对象，返回 (callable, mock_self_or_none)。
+    """解析 Celery 任务对象，兼容 Proxy / Task 实例 / 原始函数三种形态。
 
-    跨环境兼容 Celery Proxy / Task 实例 / 原始函数三种情况。
+    所有分支均做异常保护，避免因 Celery Proxy 在无 app context 时抛错导致测试挂掉。
 
     Returns:
-        tuple: (callable, mock_self)
-            - Proxy/Task: callable 是 bound method task.run，mock_self=None
-            - 原始函数: callable 是原始函数，mock_self 需由调用方提供
+        tuple: (callable, mock_self, real_task)
+            - callable: 最终执行用的可调用对象
+            - mock_self: 仅原始函数分支需要手动传入 mock self；其他分支为 None
+            - real_task: 真实 Task 实例（Proxy 分支为 _get_current_object() 结果；
+              Task 分支为 task_obj 本身；原始函数分支为 None）。用于 patch .retry。
     """
-    # Case 1: Celery Proxy → 提取 Task 实例的 .run（bound method）
+    # Case 1: Celery Proxy → 安全尝试 _get_current_object()
     if hasattr(task_obj, "_get_current_object"):
-        real_task = task_obj._get_current_object()
-        return real_task.run, None
+        try:
+            real_task = task_obj._get_current_object()
+            if real_task is not None and hasattr(real_task, "run"):
+                return real_task.run, None, real_task
+        except Exception:
+            # 无 active app context 或 Proxy 未绑定，退化为其他分支处理
+            pass
+
     # Case 2: Celery Task 实例（非 Proxy）
     if hasattr(task_obj, "run") and hasattr(task_obj, "retry"):
-        return task_obj.run, None
-    # Case 3: 原始函数（CI 环境中装饰器未生效）
-    return task_obj, MagicMock()
+        return task_obj.run, None, task_obj
+
+    # Case 3: 原始函数（装饰器未生效）
+    return task_obj, MagicMock(), None
 
 
 # ── 成功场景 ──────────────────────────────────────────────
@@ -110,8 +120,8 @@ class TestProcessVoiceCloneSuccess:
 
         from worker_app.tasks.voice_clone import process_voice_clone
 
-        func, mock_self = _resolve_task(process_voice_clone)
-        args = (mock_self, "profile-123") if mock_self else ("profile-123",)
+        func, mock_self, _ = _resolve_task(process_voice_clone)
+        args = (mock_self, "profile-123") if mock_self is not None else ("profile-123",)
         result = func(*args)
 
         assert result["ok"] is True
@@ -148,8 +158,8 @@ class TestProcessVoiceCloneSuccess:
 
         from worker_app.tasks.voice_clone import process_voice_clone
 
-        func, mock_self = _resolve_task(process_voice_clone)
-        args = (mock_self, "nonexistent") if mock_self else ("nonexistent",)
+        func, mock_self, _ = _resolve_task(process_voice_clone)
+        args = (mock_self, "nonexistent") if mock_self is not None else ("nonexistent",)
         result = func(*args)
 
         assert result["ok"] is False
@@ -189,24 +199,24 @@ class TestProcessVoiceCloneTimeout:
 
         from worker_app.tasks.voice_clone import process_voice_clone
 
-        func, mock_self = _resolve_task(process_voice_clone)
+        func, mock_self, real_task = _resolve_task(process_voice_clone)
 
-        # 设置 retry mock：根据环境不同，retry 在不同对象上
-        if mock_self is None:
-            # Proxy/Task 环境：retry 在 Task 实例上（func 是 bound method task.run）
-            real_task = process_voice_clone._get_current_object()
-            mock_retry = MagicMock()
-            mock_retry.side_effect = Retry("retrying")
-            with patch.object(real_task, "retry", mock_retry):
-                with pytest.raises(Retry):
-                    func("profile-123")
-                mock_retry.assert_called_once()
-        else:
+        if mock_self is not None:
             # 原始函数环境：retry 在 mock_self 上
             mock_self.retry.side_effect = Retry("retrying")
             with pytest.raises(Retry):
                 func(mock_self, "profile-123")
             mock_self.retry.assert_called_once()
+        else:
+            # Proxy/Task 环境：retry 在 Task 实例上。用 _resolve_task 返回的 real_task，
+            # 避免再次 _get_current_object() 在无 context 时抛 AttributeError。
+            retry_target = real_task if real_task is not None else process_voice_clone
+            mock_retry = MagicMock()
+            mock_retry.side_effect = Retry("retrying")
+            with patch.object(retry_target, "retry", mock_retry):
+                with pytest.raises(Retry):
+                    func("profile-123")
+                mock_retry.assert_called_once()
 
         mock_session.rollback.assert_called_once()
         mock_session.close.assert_called_once()
@@ -243,8 +253,8 @@ class TestProcessVoiceCloneFailure:
 
         from worker_app.tasks.voice_clone import process_voice_clone
 
-        func, mock_self = _resolve_task(process_voice_clone)
-        args = (mock_self, "profile-123") if mock_self else ("profile-123",)
+        func, mock_self, _ = _resolve_task(process_voice_clone)
+        args = (mock_self, "profile-123") if mock_self is not None else ("profile-123",)
         result = func(*args)
 
         assert result["ok"] is False
@@ -277,8 +287,8 @@ class TestProcessVoiceCloneFailure:
 
         from worker_app.tasks.voice_clone import process_voice_clone
 
-        func, mock_self = _resolve_task(process_voice_clone)
-        args = (mock_self, "profile-123") if mock_self else ("profile-123",)
+        func, mock_self, _ = _resolve_task(process_voice_clone)
+        args = (mock_self, "profile-123") if mock_self is not None else ("profile-123",)
         result = func(*args)
 
         assert result["ok"] is False
@@ -311,8 +321,8 @@ class TestProcessVoiceCloneFailure:
 
         from worker_app.tasks.voice_clone import process_voice_clone
 
-        func, mock_self = _resolve_task(process_voice_clone)
-        args = (mock_self, "profile-123") if mock_self else ("profile-123",)
+        func, mock_self, _ = _resolve_task(process_voice_clone)
+        args = (mock_self, "profile-123") if mock_self is not None else ("profile-123",)
         result = func(*args)
 
         assert result["ok"] is False