chore(ai-avatar): generateSmartCover 接口超时 60s → 120s (#1861 )

Co-authored-by: xiaoxia <dev@xiaoxiajianji.com> Co-committed-by: xiaoxia <dev@xiaoxiajianji.com>
Merge pull request 'fix(ai-avatar, P0): FFmpeg subprocess list修复32512 + Celery异常raise + 投递失败写DB + 封面drawtext标题 + audio/x-wav白名单' (#1859 ) from fix/ai-avatar-ffmpeg-cover-wav into develop
2026-09-11 15:58:19 +08:00 · 2026-09-11 15:52:55 +08:00 · 2026-09-11 15:12:55 +08:00 · 2026-09-11 15:00:22 +08:00 · 2026-09-11 06:27:13 +00:00 · 2026-09-11 14:22:45 +08:00
23 changed files with 554 additions and 551 deletions
@@ -1,43 +0,0 @@
-name: Debug Lipsync SSH Diag
-on:
-  workflow_dispatch:
-    inputs:
-      reason:
-        description: "debug reason"
-        required: false
-        default: "lipsync tts_processing stuck diagnosis"
-  push:
-    branches:
-      - debug/lipsync-ssh-diag
-permissions:
-  contents: read
-jobs:
-  ssh-diag:
-    name: SSH Staging Diagnostics
-    runs-on: runtime-builder
-    timeout-minutes: 15
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Setup SSH
-        shell: bash
-        env:
-          STAGING_SSH_KEY: ${{ secrets.PREVIEW_SSH_KEY }}
-        run: |
-          set -euo pipefail
-          which ssh || (apt-get update -qq && apt-get install -y -qq openssh-client)
-          mkdir -p ~/.ssh && chmod 700 ~/.ssh
-          printf "%s" "$STAGING_SSH_KEY" > ~/.ssh/id_rsa
-          chmod 600 ~/.ssh/id_rsa
-          H=47.98.113.167; P=22222
-          ssh-keyscan -p $P -H $H >> ~/.ssh/known_hosts 2>/dev/null
-          ssh -p $P -i ~/.ssh/id_rsa -o StrictHostKeyChecking=no root@$H "echo SSH_OK; hostname; date"
-      - name: Upload diag script and run
-        shell: bash
-        run: |
-          set -euo pipefail
-          H=47.98.113.167; P=22222
-          scp -P $P -i ~/.ssh/id_rsa -o StrictHostKeyChecking=no \
-            infra/scripts/server-lipsync-diag-v3.sh root@$H:/tmp/server-lipsync-diag-v3.sh
-          ssh -p $P -i ~/.ssh/id_rsa -o StrictHostKeyChecking=no root@$H \
-            "bash /tmp/server-lipsync-diag-v3.sh 2>&1"
@@ -0,0 +1,60 @@
+name: "Debug: Web container v2 (mount conflict)"
+on:
+  push:
+    branches: [debug/web-crash-v2]
+  workflow_dispatch:
+jobs:
+  web-diag:
+    runs-on: runtime-builder
+    timeout-minutes: 10
+    steps:
+      - name: Setup SSH and diagnose
+        shell: bash
+        env:
+          STAGING_SSH_KEY: ${{ secrets.PREVIEW_SSH_KEY }}
+        run: |
+          set -x
+          which ssh || (apt-get update -qq && apt-get install -y -qq openssh-client)
+          mkdir -p ~/.ssh && chmod 700 ~/.ssh
+          printf "%s" "$STAGING_SSH_KEY" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          H=47.98.113.167; P=22222
+          ssh-keyscan -p $P -H $H >> ~/.ssh/known_hosts 2>/dev/null
+          ssh -p $P -i ~/.ssh/id_rsa -o StrictHostKeyChecking=no root@$H 'bash -s' <<'REMOTE'
+          set -x
+          echo "=== Current staging containers ==="
+          docker ps -a --filter name=xiaoxia-*-staging --format "table {{.Names}}\t{{.Status}}\t{{.Image}}"
+          echo ""
+          echo "=== Web container logs (current/current-rolledback) ==="
+          docker logs xiaoxia-web-staging 2>&1 | tail -40
+          echo ""
+          echo "=== Web inspect: env & mounts ==="
+          docker inspect xiaoxia-web-staging --format 'Entrypoint: {{.Config.Entrypoint}} Cmd: {{.Config.Cmd}}'
+          docker inspect xiaoxia-web-staging --format '{{range .Config.Env}}{{.}}{{"\n"}}{{end}}' | grep -E "APP_ENV|VERSION"
+          echo "Mounts:"
+          docker inspect xiaoxia-web-staging --format '{{range .Mounts}}{{.Type}} {{.Source}} -> {{.Destination}} (rw={{.RW}}){{"\n"}}{{end}}'
+          echo ""
+          echo "=== Reproduce: rm on read-only bind mount ==="
+          docker run --rm --name nginx-ro-test \
+            -v /var/lib/xiaoxia-saas-staging/nginx-staging.conf:/etc/nginx/conf.d/default.conf:ro \
+            git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas/xiaoxia-saas-web:387514c \
+            sh -c '
+              set -x
+              echo "Before:"
+              ls -la /etc/nginx/conf.d/
+              echo "Try rm (as entrypoint does):"
+              rm -f /etc/nginx/conf.d/default.conf
+              echo "rm exitcode=$?"
+              echo "After rm:"
+              ls -la /etc/nginx/conf.d/
+              echo "Test ln:"
+              ln -s /etc/nginx/nginx-staging.conf /etc/nginx/conf.d/default.conf
+              echo "ln exitcode=$?"
+              ls -la /etc/nginx/conf.d/
+              echo "nginx -t:"
+              nginx -t 2>&1
+            ' 2>&1
+          echo ""
+          echo "=== Also test with NEW fixed image (9c0d4b1 if present) ==="
+          docker images | grep xiaoxia-saas-web | head -5
+REMOTE
@@ -11,6 +11,7 @@
 from __future__ import annotations

 import logging
+from datetime import datetime, timezone

 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_db_session
@@ -77,10 +78,16 @@ def create_render_job(
        from app.tasks.ai_avatar_render import execute_ai_avatar_render

        execute_ai_avatar_render.delay(job.id)
-    except Exception:
-        logger.warning("Celery 任务提交失败，渲染任务已创建但未触发执行: %s", job.id)
+    except Exception as exc:
+        logger.exception("Celery 任务投递失败（创建）: job_id=%s err=%s", job.id, exc)
+        job.status = "failed"
+        job.error_message = f"任务提交失败：{exc}"
+        job.updated_at = datetime.now(timezone.utc)
+        svc.db.commit()
+        svc.db.refresh(job)
+        return AiAvatarRenderJobResponse.model_validate(job)

-    return job
+    return AiAvatarRenderJobResponse.model_validate(job)


 # ── GET /jobs — 任务列表 ─────────────────────────────────────────────────
@@ -172,10 +179,16 @@ def retry_render_job(
        from app.tasks.ai_avatar_render import execute_ai_avatar_render

        execute_ai_avatar_render.delay(job.id)
-    except Exception:
-        logger.warning("Celery 任务提交失败，重试任务已重置但未触发执行: %s", job.id)
+    except Exception as exc:
+        logger.exception("Celery 任务投递失败（重试）: job_id=%s err=%s", job.id, exc)
+        job.status = "failed"
+        job.error_message = f"任务提交失败：{exc}"
+        job.updated_at = datetime.now(timezone.utc)
+        svc.db.commit()
+        svc.db.refresh(job)
+        return AiAvatarRenderJobResponse.model_validate(job)

-    return job
+    return AiAvatarRenderJobResponse.model_validate(job)



@@ -199,7 +212,11 @@ def generate_avatar_smart_cover(
        raise HTTPException(status_code=400, detail="video_url 必须是合法的 HTTP/HTTPS URL")

    try:
-        cover_url = generate_smart_cover(video_url, max_frames=body.max_frames)
+        cover_url = generate_smart_cover(
+            video_url,
+            max_frames=body.max_frames,
+            title_config=getattr(body, "title_config", None),
+        )
    except Exception as exc:
        logger.error(
            "智能封面生成异常: user=%s video_url=%s err=%s",
@@ -110,10 +110,13 @@ class AiAvatarRenderProgressResponse(BaseModel):


 class SmartCoverRequest(BaseModel):
-    """智能封面请求 — MediaKit 抽帧 + 质量评分选最佳帧."""
+    """智能封面请求 — MediaKit 抽帧 + 质量评分选最佳帧 + 可选标题 drawtext 叠加."""

    video_url: str = Field(..., description="数字人视频 URL（对口型/渲染成片）")
    max_frames: int = Field(5, ge=1, le=10, description="抽帧数量（默认 5）")
+    title_config: Optional[dict[str, Any]] = Field(
+        None, description="标题配置；传入时在封面上用 drawtext 叠加标题（竖屏 720x1280）"
+    )


 class SmartCoverResponse(BaseModel):
@@ -11,6 +11,8 @@
 from __future__ import annotations

 import logging
+import os
+import subprocess
 import tempfile
 import uuid
 from pathlib import Path
@@ -156,13 +158,79 @@ def select_best_cover_frame(video_url: str, *, max_frames: int = 5) -> str:
        return ""


-def persist_cover_to_oss(frame_url: str, *, job_id: str = "", prefix: str = "ai-avatar/covers") -> str:
+def apply_title_to_cover(local_frame: str, *, title_config: dict | None) -> str:
+    """用 ffmpeg drawtext 在封面图上叠加标题，返回叠加后图片的本地路径.
+
+    ffmpeg 失败时回退返回原始 local_frame。竖屏封面按 720x1280 计算位置。
+    """
+    if not title_config or not isinstance(title_config, dict):
+        return local_frame
+    text = (title_config.get("text") or title_config.get("content") or "").strip()
+    if not text:
+        return local_frame
+    enabled = title_config.get("enabled", True)
+    if not enabled:
+        return local_frame
+
+    try:
+        from packages.domain.video_filter_builder import build_title_drawtext_filter
+
+        drawtext_filter = build_title_drawtext_filter(
+            title_config,
+            output_width=720,
+            output_height=1280,
+        )
+        if not drawtext_filter:
+            return local_frame
+
+        base, ext = os.path.splitext(local_frame)
+        titled_path = f"{base}_titled{ext or '.jpg'}"
+        cmd = [
+            "ffmpeg",
+            "-i",
+            local_frame,
+            "-vf",
+            drawtext_filter,
+            "-y",
+            titled_path,
+        ]
+        logger.info("[数字人封面] 叠加标题: text=%s", text[:30])
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            logger.warning(
+                "[数字人封面] drawtext 失败，回退无标题: exit=%s stderr=%s",
+                result.returncode,
+                (result.stderr or "")[-300:],
+            )
+            return local_frame
+        if not os.path.exists(titled_path) or os.path.getsize(titled_path) == 0:
+            logger.warning("[数字人封面] drawtext 输出为空，回退无标题")
+            return local_frame
+        return titled_path
+    except Exception as exc:
+        logger.warning("[数字人封面] 标题叠加异常，回退无标题: %s", exc, exc_info=True)
+        return local_frame
+
+
+def persist_cover_to_oss(
+    frame_url: str,
+    *,
+    job_id: str = "",
+    prefix: str = "ai-avatar/covers",
+    title_config: dict | None = None,
+) -> str:
    """下载帧图并转存到 OSS，返回公网封面 URL.

    Args:
        frame_url: MediaKit 返回的临时帧图 URL
        job_id: 关联任务 ID（用于 OSS key 命名）
        prefix: OSS key 前缀
+        title_config: 可选标题配置；传入时用 drawtext 叠加标题（竖屏 720x1280）

    Returns:
        OSS 公网 URL；失败回退原始 frame_url
@@ -170,6 +238,7 @@ def persist_cover_to_oss(frame_url: str, *, job_id: str = "", prefix: str = "ai-
    if not frame_url:
        return ""
    tmp_path: Optional[str] = None
+    titled_path: Optional[str] = None
    try:
        import httpx

@@ -189,12 +258,21 @@ def persist_cover_to_oss(frame_url: str, *, job_id: str = "", prefix: str = "ai-
        storage = get_shared_storage_service()
        token = job_id or uuid.uuid4().hex[:12]
        cover_key = f"{prefix}/{token}/cover_{uuid.uuid4().hex[:8]}.jpg"
+
+        upload_path = apply_title_to_cover(tmp_path, title_config=title_config)
+        if upload_path != tmp_path:
+            titled_path = upload_path
+
        public_url = storage.upload_file(
-            file_or_path=tmp_path,
+            file_or_path=upload_path,
            storage_key=cover_key,
            content_type="image/jpeg",
        )
-        logger.info("[数字人封面] 封面已转存 OSS: key=%s", cover_key)
+        logger.info(
+            "[数字人封面] 封面已转存 OSS: key=%s titled=%s",
+            cover_key,
+            bool(titled_path),
+        )
        # 私有桶：返回预签名 URL（前端才能加载）
        if public_url:
            signed = storage.get_download_url(cover_key, expires_seconds=86400)
@@ -204,19 +282,32 @@ def persist_cover_to_oss(frame_url: str, *, job_id: str = "", prefix: str = "ai-
        logger.warning("[数字人封面] 封面转存 OSS 失败，返回原始 URL", exc_info=True)
        return frame_url
    finally:
-        if tmp_path:
-            try:
-                Path(tmp_path).unlink(missing_ok=True)
-            except Exception:
-                pass
+        for p in (tmp_path, titled_path):
+            if p:
+                try:
+                    Path(p).unlink(missing_ok=True)
+                except Exception:
+                    pass


-def generate_smart_cover(video_url: str, *, job_id: str = "", max_frames: int = 5) -> str:
-    """一站式：MediaKit 智能抽帧选最佳 → 转存 OSS，返回封面公网 URL.
+def generate_smart_cover(
+    video_url: str,
+    *,
+    job_id: str = "",
+    max_frames: int = 5,
+    title_config: dict | None = None,
+) -> str:
+    """一站式：MediaKit 智能抽帧选最佳 → （可选）drawtext 叠加标题 → 转存 OSS.

    供独立封面接口与渲染管线复用。失败返回空字符串。
+
+    Args:
+        video_url: 可公网访问的视频 URL
+        job_id: 关联任务 ID
+        max_frames: 抽帧数量
+        title_config: 可选标题配置；传入时在封面上叠加 drawtext 标题（竖屏 720x1280）
    """
    best_frame = select_best_cover_frame(video_url, max_frames=max_frames)
    if not best_frame:
        return ""
-    return persist_cover_to_oss(best_frame, job_id=job_id)
+    return persist_cover_to_oss(best_frame, job_id=job_id, title_config=title_config)
@@ -11,6 +11,7 @@ from __future__ import annotations

 import logging
 import os
+import subprocess
 import tempfile
 import uuid
 from datetime import datetime, timezone
@@ -24,7 +25,6 @@ from packages.adapters.sqlalchemy_impl.models import (
    ScriptModel,
 )
 from packages.domain.video_filter_builder import (
-    build_cover_extract_command,
    build_title_drawtext_filter,
 )
 from packages.shared.storage import get_shared_storage_service
@@ -257,7 +257,7 @@ class AiAvatarRenderService:
            with tempfile.TemporaryDirectory() as tmpdir:
                output_video_path = os.path.join(tmpdir, "output.mp4")

-                cmd = self._build_ffmpeg_command(
+                cmd_list = self._build_ffmpeg_command(
                    input_video=input_video_path,
                    b_roll_segments=job.b_roll_segments,
                    filter_complex=filter_complex,
@@ -265,9 +265,25 @@ class AiAvatarRenderService:
                    output_path=output_video_path,
                )

-                exit_code = os.system(cmd)
-                if exit_code != 0:
-                    raise AiAvatarRenderError(f"FFmpeg 渲染失败，退出码: {exit_code}", code="FFmpegFailed")
+                try:
+                    render_result = subprocess.run(
+                        cmd_list,
+                        capture_output=True,
+                        text=True,
+                        timeout=600,
+                    )
+                except subprocess.TimeoutExpired as exc:
+                    raise AiAvatarRenderError(
+                        "FFmpeg 渲染超时（600s）",
+                        code="FFmpegTimeout",
+                    ) from exc
+
+                if render_result.returncode != 0:
+                    stderr_tail = (render_result.stderr or "").strip()[-800:]
+                    raise AiAvatarRenderError(
+                        f"FFmpeg 渲染失败，退出码: {render_result.returncode}, stderr: {stderr_tail}",
+                        code="FFmpegFailed",
+                    )

                job.progress = 80
                self.db.commit()
@@ -276,11 +292,27 @@ class AiAvatarRenderService:
                cover_path = ""
                if job.cover_config:
                    cover_path = os.path.join(tmpdir, "cover.jpg")
-                    cover_cmd = build_cover_extract_command(job.cover_config, cover_path)
-                    cover_cmd = cover_cmd.replace("INPUT_VIDEO", output_video_path)
-                    cover_exit = os.system(cover_cmd)
-                    if cover_exit != 0:
-                        logger.warning("封面提取失败，跳过: %s", cover_cmd)
+                    cover_cmd = self._build_cover_extract_cmd(
+                        cover_config=job.cover_config,
+                        input_video=output_video_path,
+                        output_path=cover_path,
+                    )
+                    try:
+                        cover_result = subprocess.run(
+                            cover_cmd,
+                            capture_output=True,
+                            text=True,
+                            timeout=60,
+                        )
+                        if cover_result.returncode != 0:
+                            logger.warning(
+                                "封面提取失败（非致命），跳过: exit=%s stderr=%s",
+                                cover_result.returncode,
+                                (cover_result.stderr or "")[-300:],
+                            )
+                            cover_path = ""
+                    except Exception as cover_err:
+                        logger.warning("封面提取异常（非致命），跳过: %s", cover_err)
                        cover_path = ""

                job.progress = 90
@@ -290,7 +322,7 @@ class AiAvatarRenderService:
                output_video_url = self._upload_to_oss(output_video_path, f"ai-avatar/{job_id}/output.mp4")
                job.output_video_url = output_video_url

-                # 封面：优先复用智能剪辑的 MediaKit 抽帧 + 质量评分选最佳帧；
+                # 封面：优先复用智能剪辑的 MediaKit 抽帧 + 质量评分选最佳帧（支持 drawtext 标题叠加）；
                # MediaKit 不可用时回退到 FFmpeg 已按 cover_config 抽取的 cover_path
                smart_cover_url = ""
                if output_video_url:
@@ -299,7 +331,12 @@ class AiAvatarRenderService:
                            generate_smart_cover,
                        )

-                        smart_cover_url = generate_smart_cover(output_video_url, job_id=job_id, max_frames=5)
+                        smart_cover_url = generate_smart_cover(
+                            output_video_url,
+                            job_id=job_id,
+                            max_frames=5,
+                            title_config=job.title_config,
+                        )
                    except Exception:
                        logger.warning("智能封面(MediaKit)失败，回退 FFmpeg 封面 job_id=%s", job_id, exc_info=True)

@@ -360,12 +397,14 @@ class AiAvatarRenderService:
            job.updated_at = datetime.now(timezone.utc)
            self.db.commit()
            logger.error("渲染任务失败 [%s]: %s", job_id, exc)
+            raise
        except Exception as exc:
            job.status = "failed"
            job.error_message = f"渲染异常: {str(exc)}"
            job.updated_at = datetime.now(timezone.utc)
            self.db.commit()
            logger.exception("渲染任务异常 [%s]", job_id)
+            raise

    def _download_video(self, url: str) -> str:
        """下载视频到临时文件."""
@@ -391,24 +430,73 @@ class AiAvatarRenderService:
        filter_complex: str,
        final_label: Optional[str],
        output_path: str,
-    ) -> str:
-        """构建 FFmpeg 命令."""
-        # 输入文件
-        inputs = f"-i {input_video}"
+    ) -> list[str]:
+        """构建 FFmpeg 命令（list 形式，shell=False）.
+
+        根因修复 #1798 P0：OSS 预签名 URL 含 `&Expires=...&Signature=...` 特殊字符，
+        os.system(shell=True) 会把 `&` 解释为后台命令分隔符，导致 -filter_complex 被
+        当成独立命令报 sh: -filter_complex: not found（exit 127 → Python 32512）。
+        list + shell=False 彻底规避 shell 转义问题。
+        """
+        cmd: list[str] = ["ffmpeg", "-i", input_video]
        for seg in b_roll_segments:
            asset_url = seg.get("asset_url", "")
            if asset_url:
-                inputs += f" -i {asset_url}"
+                cmd.extend(["-i", asset_url])

-        # 滤镜
        if filter_complex and final_label:
-            filter_arg = f'-filter_complex "{filter_complex}" -map "[{final_label}]"'
+            cmd.extend(["-filter_complex", filter_complex, "-map", f"[{final_label}]"])
        elif filter_complex:
-            filter_arg = f'-filter_complex "{filter_complex}"'
-        else:
-            filter_arg = ""
+            cmd.extend(["-filter_complex", filter_complex])

-        return f"ffmpeg {inputs} {filter_arg} -c:v libx264 -preset veryfast -crf 23 -y {output_path}"
+        cmd.extend(
+            [
+                "-c:v",
+                "libx264",
+                "-preset",
+                "veryfast",
+                "-crf",
+                "23",
+                "-y",
+                output_path,
+            ]
+        )
+        return cmd
+
+    def _build_cover_extract_cmd(
+        self,
+        *,
+        cover_config: dict[str, Any],
+        input_video: str,
+        output_path: str,
+    ) -> list[str]:
+        """构建封面截帧 FFmpeg 命令（list 形式，shell=False）."""
+        if not cover_config or not isinstance(cover_config, dict):
+            timestamp = 0.0
+            width = 0
+            height = 0
+        else:
+            timestamp = cover_config.get("timestamp", 0.0)
+            width = cover_config.get("width", 0)
+            height = cover_config.get("height", 0)
+
+        cmd: list[str] = [
+            "ffmpeg",
+            "-ss",
+            str(timestamp),
+            "-i",
+            input_video,
+            "-frames:v",
+            "1",
+        ]
+        if width > 0 and height > 0:
+            vf = (
+                f"scale={width}:{height}:force_original_aspect_ratio=decrease,"
+                f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2"
+            )
+            cmd.extend(["-vf", vf])
+        cmd.extend(["-y", output_path])
+        return cmd

    def _upload_to_oss(self, local_path: str, oss_key: str) -> str:
        """上传文件到 OSS，返回 URL.
@@ -211,12 +211,18 @@ class LipsyncService:
                        normalize_emotion(emotion),
                    )
                )
-            except Exception:
-                logger.warning(
-                    "Celery 任务提交失败，TTS 任务已创建但未触发执行: %s",
+            except Exception as exc:
+                # 投递失败时立即把 job 标成 failed 并写入 error_message，
+                # 前端轮询时能直接看到失败原因，不会无限卡在 tts_processing。
+                logger.exception(
+                    "Celery 任务提交失败，TTS 任务已创建但未触发执行: job_id=%s err=%s",
                    job_id,
-                    exc_info=True,
+                    exc,
                )
+                job.status = "failed"
+                job.error_message = f"Celery 任务投递失败: {exc}"
+                job.error_code = "AsyncDispatchFailed"
+                job.updated_at = datetime.now(timezone.utc)
        else:
            # 2b. 直接音频模式：同步签名并提交 MediaKit
            video_url = self._sign_media_url(video_url)
@@ -76,11 +76,21 @@ def tts_synthesize_and_submit(
    from app.services.mediakit_client import MediaKitError, get_mediakit_client
    from sqlalchemy.orm import Session as DBSession

-    from packages.adapters.sqlalchemy_impl.database import SessionLocal
    from packages.adapters.sqlalchemy_impl.models import LipsyncJobModel
    from packages.application.cosyvoice_service import CosyVoiceError, CosyVoiceService
    from packages.shared.url_security import safe_download_bytes

+    # SessionLocal 获取：
+    # - API 容器：app.db.SessionLocal（环境变量完整，导入即建引擎）
+    # - Worker 容器：worker_app.db.SessionLocal（Worker 自己的 settings 初始化引擎）
+    # API 侧没有 worker_app 模块 → ImportError 直接回退；
+    # Worker 侧 app.db 会因缺少 API 专有环境变量抛 pydantic ValidationError，
+    # 此时也要回退到 worker_app.db。
+    try:
+        from worker_app.db import SessionLocal  # type: ignore
+    except Exception:  # noqa: BLE001
+        from app.db import SessionLocal  # type: ignore
+
    db: DBSession = SessionLocal()
    try:
        job = (
@@ -146,6 +156,7 @@ def tts_synthesize_and_submit(
                    "audio/mpeg",
                    "audio/mp3",
                    "audio/wav",
+                    "audio/x-wav",  # CosyVoice 部分接口返回 audio/x-wav，与 audio/wav 等价（RIFF/WAVE）
                    "audio/mp4",
                    "audio/x-m4a",
                ),
@@ -552,7 +552,7 @@
  max-width: 240px;
  aspect-ratio: 9/16;
  background: #f0f0f5;
-  border-radius: 8px;
+  border-radius: 12px;
  overflow: hidden;
  display: flex;
  align-items: center;
@@ -564,8 +564,10 @@
 .aa-cover-preview img {
  width: 100%;
  height: 100%;
+  aspect-ratio: 9/16;
  object-fit: cover;
  display: block;
+  border-radius: 12px;
 }

 .aa-cover-preview__placeholder {
@@ -573,6 +575,19 @@
  color: #8c8ca1;
 }

+.aa-cover-preview__loading {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.45);
+  color: #fff;
+  font-size: 13px;
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
+}
+
 .aa-cover-actions {
  display: flex;
  gap: 8px;
@@ -441,6 +441,7 @@ const AiAvatarPage: React.FC = () => {
              <div className="aa-panel__body">
                <PanelCoverAndGenerate
                  coverConfig={state.coverConfig}
+                  titleConfig={state.titleConfig}
                  onCoverConfigChange={(partial) =>
                    state.setCoverConfig((prev) => ({ ...prev, ...partial }))
                  }
@@ -66,7 +66,8 @@ export const generateSmartCover = async (
  const response = await apiClient.post<{ cover_url: string; status: string; message: string }>(
    "/ai-avatar/render/smart-cover",
    { video_url, max_frames },
-    { timeout: 60000 },
+    // smart-cover 链路：下载视频+抽帧+drawtext 加标题+上传 OSS，需要较长时间，120s 超时
+    { timeout: 120000 },
  )
  return response.data
 }
@@ -1,17 +1,18 @@
 /**
 * AI数字人 — 面板5：封面 & 生成
- * - 竖屏 9:16 封面预览（从视频截取 / 自定义上传）
+ * - 竖屏 9:16 封面预览（从视频截取 / 自定义上传）+ 标题文字实时叠加预览
 * - 分辨率选择（720p / 1080p / 4K）
 * - 配置汇总卡片（出镜视频/音色/文案/对口型/B-roll/标题/封面）
 * - 渐变紫色生成按钮
 *
 * 注意：v3 已删除"画面插入模式"，本面板不包含该选项。
 */
-import React, { useRef } from "react"
-import type { AiAvatarCoverConfig } from "../types"
+import React, { useMemo, useRef } from "react"
+import type { AiAvatarCoverConfig, AiAvatarTitleConfig } from "../types"

 interface PanelCoverAndGenerateProps {
  coverConfig: AiAvatarCoverConfig
+  titleConfig: AiAvatarTitleConfig
  onCoverConfigChange: (partial: Partial<AiAvatarCoverConfig>) => void
  resolution: string
  onResolutionChange: (r: string) => void
@@ -47,8 +48,19 @@ const LIPSYNC_STATUS_LABEL: Record<string, { text: string; cls: string }> = {
  failed: { text: "失败", cls: "aa-status-badge--failed" },
 }

+/** 字体名 → CSS font-family 映射（与后端 drawtext 对齐） */
+const FONT_FAMILY_MAP: Record<string, string> = {
+  思源黑体: "'Noto Sans SC', 'Source Han Sans SC', 'PingFang SC', 'Microsoft YaHei', sans-serif",
+  思源宋体: "'Noto Serif SC', 'Source Han Serif SC', 'SimSun', serif",
+  楷体: "KaiTi, 'STKaiti', serif",
+  黑体: "'Heiti SC', 'SimHei', 'Microsoft YaHei', sans-serif",
+}
+
+const getFontFamily = (font: string): string => FONT_FAMILY_MAP[font] || FONT_FAMILY_MAP["思源黑体"]
+
 const PanelCoverAndGenerate: React.FC<PanelCoverAndGenerateProps> = ({
  coverConfig,
+  titleConfig,
  onCoverConfigChange,
  resolution,
  onResolutionChange,
@@ -86,15 +98,85 @@ const PanelCoverAndGenerate: React.FC<PanelCoverAndGenerateProps> = ({

  const canGenerate = summary.lipsyncStatus === "completed" && !isGenerating

+  /** 封面图实际展示的 url：智能封面 > 自定义上传 > 空 */
+  const coverUrl =
+    coverConfig.smart_cover_url || coverConfig.thumbnail_url || coverConfig.upload_url
+  const hasCoverImage = Boolean(coverUrl)
+
+  /** 是否显示标题叠加层：有图、有文字、非加载中 */
+  const showTitleOverlay =
+    hasCoverImage && !smartCoverLoading && titleConfig.title.trim().length > 0
+
+  /** 计算标题叠加层的 inline 样式 */
+  const titleOverlayStyle = useMemo<React.CSSProperties>(() => {
+    const style: React.CSSProperties = {
+      position: "absolute",
+      left: "50%",
+      width: "90%",
+      transform: "translateX(-50%)",
+      textAlign: "center",
+      boxSizing: "border-box",
+      padding: "0 4px",
+      wordBreak: "break-word",
+      whiteSpace: "pre-wrap",
+      color: titleConfig.color || "#ffffff",
+      fontSize: `${titleConfig.size}px`,
+      fontFamily: getFontFamily(titleConfig.font),
+      fontWeight: titleConfig.bold ? "bold" : "normal",
+      fontStyle: titleConfig.italic ? "italic" : "normal",
+      lineHeight: 1.3,
+      pointerEvents: "none",
+    }
+
+    // 位置
+    const pos = titleConfig.position || "bottom"
+    if (pos === "top") {
+      style.top = "40px"
+    } else if (pos === "center") {
+      style.top = "50%"
+      style.transform = "translate(-50%, -50%)"
+    } else if (pos === "custom" && titleConfig.pos_x != null && titleConfig.pos_y != null) {
+      // pos_x/pos_y 是相对预览容器的百分比坐标
+      style.left = `${titleConfig.pos_x}%`
+      style.top = `${titleConfig.pos_y}%`
+      style.transform = "translate(-50%, -50%)"
+    } else {
+      style.bottom = "40px"
+    }
+
+    // 描边优先于阴影（二者互斥，与 drawtext 对齐）
+    if (titleConfig.stroke) {
+      // 描边宽度按字号估算，保证视觉一致
+      const strokeWidth = Math.max(1, Math.round(titleConfig.size / 18))
+      ;(style as React.CSSProperties)["WebkitTextStroke"] = `${strokeWidth}px rgba(0,0,0,0.75)`
+      style.textShadow = "none"
+    } else if (titleConfig.shadow) {
+      style.textShadow = "0 2px 8px rgba(0,0,0,0.7), 0 0 2px rgba(0,0,0,0.5)"
+    } else {
+      // 默认给轻微阴影保证白字在亮背景可读
+      style.textShadow = "0 2px 6px rgba(0,0,0,0.6)"
+    }
+
+    return style
+  }, [titleConfig])
+
  return (
    <div className="aa-cover-generate">
      {/* 封面预览（竖屏 9:16） */}
      <div className="aa-cover-preview">
-        {coverConfig.thumbnail_url ? (
-          <img src={coverConfig.thumbnail_url} alt="封面预览" />
+        {hasCoverImage ? (
+          <img src={coverUrl!} alt="封面预览" draggable={false} />
        ) : (
          <span className="aa-cover-preview__placeholder">暂无封面</span>
        )}
+        {/* 智能封面加载遮罩 */}
+        {smartCoverLoading && <div className="aa-cover-preview__loading">⏳ 智能选帧中…</div>}
+        {/* 标题文字叠加层（实时预览，仅前端视觉参考，最终由后端 ffmpeg drawtext 叠加） */}
+        {showTitleOverlay && (
+          <div style={titleOverlayStyle} aria-hidden="true">
+            {titleConfig.title}
+          </div>
+        )}
      </div>

      <div className="aa-cover-actions">
@@ -34,6 +34,8 @@ celery_app.conf.imports = (
    "worker_app.tasks.tts_synthesis",
    "worker_app.tasks.batch_download",
    "worker_app.tasks.duplication_check",
+    # #1798 AI 数字人渲染：必须在 Worker 实例上注册同名任务，否则消息无人消费（渲染卡 0%）
+    "worker_app.tasks.ai_avatar_render",
    "worker_app.tasks._startup",
    "apps.worker.video_processing.dedup",
    "worker_app.tasks.cleanup",
@@ -0,0 +1,48 @@
+"""AI 数字人渲染任务 — Worker 侧 Celery 任务注册.
+
+#1798 渲染进度卡在 0% 的根因：渲染任务定义在 API 侧（`app.tasks.ai_avatar_render`），
+装饰在 API 自己的 Celery 实例（`xiaoxia-saas-api`）上；而 Worker 用的是
+`worker_app.celery_app` 实例，`conf.imports` 从未导入该任务，Worker 的任务
+注册表里没有 `ai_avatar_render.execute`，消息被路由到默认 `celery` 队列后
+无人消费，任务永远停在 0%。
+
+修复：在 Worker 侧用 `worker_app.celery_app` 注册同名任务，直接调用与 API
+服务一致的 `AiAvatarRenderService.execute_render` 核心管线（业务逻辑在
+`apps.api.app.services`，worker 镜像已复制 `apps/api/app`）。任务名保持
+`ai_avatar_render.execute`，与 API 生产端 `.delay()` 的消息路由一致；未在
+task_routes 显式配置，走默认 `celery` 队列，由 transcode worker 消费。
+"""
+
+from __future__ import annotations
+
+import logging
+
+from worker_app.celery_app import celery_app
+from worker_app.db import SessionLocal
+
+logger = logging.getLogger(__name__)
+
+
+@celery_app.task(bind=True, name="ai_avatar_render.execute", max_retries=2)
+def execute_ai_avatar_render(self, job_id: str) -> dict:
+    """执行 AI 数字人渲染管线（Worker 侧入口）.
+
+    进度由 service 直接写入 DB（AiAvatarRenderJob.progress:
+    0→5→20→40→80→90→95→100），API 通过轮询 progress 字段展示。
+    """
+    logger.info("开始执行渲染任务: %s", job_id)
+    self.update_state(state="PROCESSING", meta={"progress": 0, "job_id": job_id})
+
+    session = SessionLocal()
+    try:
+        from app.services.ai_avatar_render_service import AiAvatarRenderService
+
+        service = AiAvatarRenderService(session)
+        service.execute_render(job_id)
+        return {"status": "completed", "job_id": job_id}
+    except Exception as exc:
+        logger.exception("渲染任务执行异常 [%s]: %s", job_id, exc)
+        self.update_state(state="FAILED", meta={"progress": 0, "error": str(exc)})
+        raise
+    finally:
+        session.close()
@@ -1,18 +1,49 @@
 #!/bin/sh
 # Select nginx config based on APP_ENV (staging/production).
-# Both configs are baked into the image at well-known paths.
-# nginx reads config only at startup, so symlink before exec.
+#
+# 两种运行模式：
+# 1. CI/CD 部署（staging/production）：部署脚本通过 `-v 宿主机文件:/etc/nginx/conf.d/default.conf:ro`
+#    把宿主机生成的带 resolver/docker upstream 的配置 bind mount 进来，entrypoint 不应改动。
+#    bind mount 的文件是 readonly 的，rm 会报 EBUSY ("Resource busy")，直接 exec nginx 即可。
+# 2. 本地 docker-compose / 直接 `docker run`（无外部挂载）：镜像烤入了 nginx-staging.conf 与
+#    nginx-production.conf 到 /etc/nginx/，entrypoint 根据 APP_ENV 把 default.conf 换成正确的 symlink。
+#
+# 策略：
+# - 如果 /etc/nginx/conf.d/default.conf 已经是指向目标 conf 的 symlink，什么都不做；
+# - 否则尝试 rm -f 再 ln -s；rm 失败说明是外部 bind mount（已有正确配置），不阻塞启动；
+# - 兜底：只要 conf.d 目录里有 .conf 文件（含 bind mount 来的），就直接启动 nginx。
 set -e

 NGINX_CONF_DIR="/etc/nginx/conf.d"
+TARGET_CONF=""

 case "${APP_ENV:-production}" in
  staging)
-    ln -sf /etc/nginx/nginx-staging.conf "$NGINX_CONF_DIR/default.conf"
+    TARGET_CONF="/etc/nginx/nginx-staging.conf"
    ;;
  *)
-    ln -sf /etc/nginx/nginx-production.conf "$NGINX_CONF_DIR/default.conf"
+    TARGET_CONF="/etc/nginx/nginx-production.conf"
    ;;
 esac

+DEFAULT_CONF="$NGINX_CONF_DIR/default.conf"
+
+# 1. 已经是正确的 symlink：直接启动
+if [ -L "$DEFAULT_CONF" ] && [ "$(readlink "$DEFAULT_CONF" 2>/dev/null)" = "$TARGET_CONF" ]; then
+  exec nginx -g "daemon off;"
+fi
+
+# 2. 尝试替换为目标 symlink（无 bind mount 的场景）
+#    若 rm 失败（bind mount readonly，EBUSY/EPERM），则认为外部已注入配置，不阻塞。
+rm -f "$DEFAULT_CONF" 2>/dev/null || true
+if [ -f "$TARGET_CONF" ] && [ ! -e "$DEFAULT_CONF" ]; then
+  ln -s "$TARGET_CONF" "$DEFAULT_CONF" 2>/dev/null || true
+fi
+
+# 3. 兜底：至少要有一个 .conf 文件，否则 nginx 起不来
+if ! ls "$NGINX_CONF_DIR"/*.conf >/dev/null 2>&1; then
+  echo "ERROR: no nginx config found in $NGINX_CONF_DIR (tried $TARGET_CONF and external bind mount)" >&2
+  exit 1
+fi
+
 exec nginx -g "daemon off;"
@@ -1,152 +0,0 @@
-#!/bin/bash
-# Lipsync 深度诊断脚本 v2 - 重点排查broker连通/消息投递/DB状态
-set +e
-echo "#########################################################"
-echo "#  Lipsync 深度诊断 v2"
-echo "#  Date: $(date)"
-echo "#########################################################"
-
-W=$(docker ps --format '{{.Names}}' | grep -E 'worker' | head -1)
-A=$(docker ps --format '{{.Names}}' | grep -E 'api' | grep -v 'web' | head -1)
-R=$(docker ps --format '{{.Names}}' | grep -E 'redis' | head -1)
-echo "Containers: W=$W  A=$A  R=$R"
-
-echo ""
-echo "=== 1. 容器 uptime + image tag ==="
-for c in $W $A; do
-  echo "--- $c ---"
-  docker inspect "$c" --format 'Image={{.Config.Image}} Created={{.Created}} Started={{.State.StartedAt}} Restarts={{.RestartCount}}'
-done
-
-echo ""
-echo "=== 2. API+Worker 的 BROKER/REDIS 地址（隐藏密码） ==="
-echo "--- API BROKER ---"
-docker exec "$A" env | grep -iE "broker|celery_broker|redis_url|backend" | sed -E 's|(:)?//[^:]+:([^@]+)@|\1//***:***@|g'
-echo "--- Worker BROKER ---"
-docker exec "$W" env | grep -iE "broker|celery_broker|redis_url|backend" | sed -E 's|(:)?//[^:]+:([^@]+)@|\1//***:***@|g'
-
-echo ""
-echo "=== 3. API容器 完整日志（近1000行） lipsync/TTS 相关 ==="
-docker logs --tail=1000 "$A" 2>&1 | grep -iE "lipsync|tts_synth|tts_processing|celery.*task|apply_async|NotRegistered|OperationalError|ConnectionError|error.*submit|traceback|submitted" | tail -200
-
-echo ""
-echo "=== 4. API 容器最近的 ERROR/Exception ==="
-docker logs --tail=2000 "$A" 2>&1 | grep -iE "error|exception|traceback|critical" | grep -v "health\|/health" | tail -80
-
-echo ""
-echo "=== 5. 测试1：在API容器内实际投递一条测试消息，看Worker是否消费 ==="
-# 投递后立即检查队列和Worker日志
-docker exec "$A" python - <<'PYEOF'
-import sys, time, traceback
-try:
-    from app.tasks.lipsync_tts import tts_synthesize_and_submit
-    from app.core.celery_app import celery_app as api_app
-    # 检查broker连接
-    conn = api_app.connection()
-    conn.ensure_connection(max_retries=2)
-    print("API celery broker connected:", conn.as_uri())
-    # 投递到celery默认队列
-    result = tts_synthesize_and_submit.apply_async(
-        args=["diag-test-job-id", "diag-user-id", "diag-voice", "diagnostic script text", 1.0, "neutral"],
-        queue="celery",
-    )
-    print("APPLY_ASYNC_OK task_id:", result.id)
-    print("task name:", result.name)
-except Exception as e:
-    traceback.print_exc()
-PYEOF
-echo ""
-sleep 3
-echo "--- After apply_async: queue lengths ---"
-for q in celery generation transcode; do
-    echo "  $q: $(docker exec "$R" redis-cli LLEN $q)"
-done
-
-echo ""
-echo "=== 6. 等8秒看Worker是否收到并消费 ==="
-sleep 8
-echo "--- Queue lengths after 8s ---"
-for q in celery generation transcode; do
-    echo "  $q: $(docker exec "$R" redis-cli LLEN $q)"
-done
-
-echo ""
-echo "=== 7. Worker 日志最新记录（查看是否消费了测试消息） ==="
-docker logs --since=30s "$W" 2>&1 | tail -60
-
-echo ""
-echo "=== 8. Worker 内 Python 直接连接broker测试 ==="
-docker exec "$W" python - <<'PYEOF'
-import traceback
-try:
-    from worker_app.celery_app import celery_app
-    conn = celery_app.connection()
-    conn.ensure_connection(max_retries=2)
-    print("Worker celery broker connected:", conn.as_uri())
-    insp = celery_app.control.inspect(timeout=3)
-    reg = insp.registered()
-    print("Registered from worker inspect (via broker):")
-    for node, tasks in (reg or {}).items():
-        has_l = any('lipsync' in t for t in tasks)
-        print(f"  {node}: {len(tasks)} tasks, lipsync registered: {has_l}")
-except Exception as e:
-    traceback.print_exc()
-PYEOF
-
-echo ""
-echo "=== 9. DB 查询最近10条lipsync_jobs状态 ==="
-docker exec "$A" python - <<'PYEOF' 2>&1
-import os, traceback
-db_url = os.environ.get("DATABASE_URL","")
-print("DATABASE_URL prefix:", (db_url[:50]+"...") if db_url else "(empty)")
-try:
-    # 通过现有代码路径
-    from app.db.session import SessionLocal
-    from packages.adapters.sqlalchemy_impl.models import LipsyncJobModel
-    db = SessionLocal()
-    jobs = db.query(LipsyncJobModel).order_by(LipsyncJobModel.created_at.desc()).limit(10).all()
-    print(f"Found {len(jobs)} recent lipsync jobs:")
-    for j in jobs:
-        err = getattr(j, 'error_message', '') or ''
-        t_id = getattr(j, 'celery_task_id', '') or ''
-        print(f"  id={j.id} status={j.status} mode={getattr(j,'mode','?')} "
-              f"created={j.created_at} celery_task_id={t_id} "
-              f"error={(err[:120]+'...') if len(err)>120 else err!r}")
-    db.close()
-except Exception as e:
-    traceback.print_exc()
-PYEOF
-
-echo ""
-echo "=== 10. Worker 启动完整日志（前60行）==="
-docker logs "$W" 2>&1 | head -60
-
-echo ""
-echo "=== 11. lipsync_service.py 完整 create_job 相关段 ==="
-docker exec "$A" sed -n '170,240p' /app/apps/api/app/services/lipsync_service.py 2>&1
-
-echo ""
-echo "=== 12. celery_app task_routes / queue 配置（API侧）==="
-docker exec "$A" python - <<'PYEOF'
-from app.core.celery_app import celery_app
-print("task_routes:", getattr(celery_app.conf, 'task_routes', None))
-print("task_default_queue:", celery_app.conf.task_default_queue)
-print("task_queues:", celery_app.conf.task_queues)
-print("broker_url prefix:", celery_app.conf.broker_url[:60])
-print("result_backend prefix:", str(celery_app.conf.result_backend)[:60] if celery_app.conf.result_backend else None)
-PYEOF
-
-echo ""
-echo "=== 13. Worker celery_app queue 配置 ==="
-docker exec "$W" python - <<'PYEOF'
-from worker_app.celery_app import celery_app
-print("task_routes:", getattr(celery_app.conf, 'task_routes', None))
-print("task_default_queue:", celery_app.conf.task_default_queue)
-print("task_queues:", celery_app.conf.task_queues)
-print("include/imports count:", len(celery_app.conf.imports))
-PYEOF
-
-echo ""
-echo "#########################################################"
-echo "#  v2 诊断完成"
-echo "#########################################################"
@@ -1,162 +0,0 @@
-#!/bin/bash
-# Lipsync 诊断脚本 v3 - 用独立文件避免heredoc问题
-set +e
-echo "#########################################################"
-echo "#  Lipsync 诊断 v3"
-echo "#  Date: $(date)"
-echo "#########################################################"
-
-W=$(docker ps --format '{{.Names}}' | grep -E 'worker' | head -1)
-A=$(docker ps --format '{{.Names}}' | grep -E 'api' | grep -v 'web' | head -1)
-R=$(docker ps --format '{{.Names}}' | grep -E 'redis' | head -1)
-NGINX=$(docker ps --format '{{.Names}}' | grep -iE 'nginx|web' | head -1)
-echo "Containers:"
-echo "  W=$W"
-echo "  A=$A"
-echo "  R=$R"
-echo "  NGINX=$NGINX"
-
-echo ""
-echo "=== A1. API 容器近 2000 行日志全部（看请求是否进来） ==="
-docker logs --tail=2000 "$A" 2>&1 | tail -300
-
-echo ""
-echo "=== A2. API容器启动命令 & 网络 ==="
-docker inspect "$A" --format 'Cmd={{.Config.Cmd}} Entrypoint={{.Config.Entrypoint}} NetworkMode={{.HostConfig.NetworkMode}}'
-docker inspect "$A" --format '{{range .NetworkSettings.Networks}}{{.NetworkID}} {{.IPAddress}}{{end}}'
-
-echo ""
-echo "=== A3. Nginx 容器（如果有）日志 ==="
-if [ -n "$NGINX" ]; then
-  docker logs --tail=200 "$NGINX" 2>&1 | grep -iE "lipsync|ai-avatar|error|upstream" | tail -100
-  echo "--- nginx config ---"
-  docker exec "$NGINX" cat /etc/nginx/conf.d/default.conf 2>&1 | head -80
-fi
-
-echo ""
-echo "=== B1. 写测试脚本到/tmp，再docker cp到容器里执行（避免heredoc问题） ==="
-cat > /tmp/api_diag.py << 'PYEOF'
-import sys, traceback, os
-print("=== PYTHON OK in API container, cwd=", os.getcwd())
-print("sys.path[0:3]:", sys.path[:3])
-print("PYTHONPATH:", os.environ.get("PYTHONPATH",""))
-try:
-    from app.tasks.lipsync_tts import tts_synthesize_and_submit
-    from app.core.celery_app import celery_app as api_app
-    print("api_app.main:", api_app.main)
-    print("api_app.conf.broker_url:", api_app.conf.broker_url)
-    print("task name:", tts_synthesize_and_submit.name)
-    print("task.app.main:", tts_synthesize_and_submit.app.main)
-    print("task in api_app.tasks:", tts_synthesize_and_submit.name in api_app.tasks)
-    print("api_app.conf.task_routes:", api_app.conf.task_routes)
-    print("api_app.conf.task_default_queue:", api_app.conf.task_default_queue)
-    # 测试broker连接
-    conn = api_app.connection()
-    conn.ensure_connection(max_retries=2)
-    print("broker connected OK:", conn.as_uri())
-    # 投递测试任务
-    result = tts_synthesize_and_submit.apply_async(
-        args=["diag-v3-job", "diag-user", "diag-voice", "hello v3 diag", 1.0, "neutral"],
-        queue="celery",
-    )
-    print("APPLY_ASYNC_OK id=", result.id, "name=", result.name, "queue=celery")
-except Exception as e:
-    traceback.print_exc()
-PYEOF
-docker cp /tmp/api_diag.py "$A:/tmp/api_diag.py"
-echo "--- docker exec python /tmp/api_diag.py in API ---"
-docker exec "$A" python /tmp/api_diag.py 2>&1
-
-echo ""
-echo "=== B2. 投递3秒后查队列 ==="
-sleep 3
-for q in celery generation transcode; do
-    echo "  queue $q: $(docker exec "$R" redis-cli LLEN $q)"
-done
-echo "--- peek celery ---"
-docker exec "$R" redis-cli LRANGE celery 0 2 2>&1 | head -20
-
-echo ""
-echo "=== B3. 等10秒再查队列和Worker日志 ==="
-sleep 7
-for q in celery generation transcode; do
-    echo "  queue $q: $(docker exec "$R" redis-cli LLEN $q)"
-done
-echo "--- Worker logs since 20s ago ---"
-docker logs --since=20s "$W" 2>&1 | tail -50
-
-echo ""
-echo "=== C1. Worker侧执行诊断脚本 ==="
-cat > /tmp/worker_diag.py << 'PYEOF'
-import sys, os, traceback
-print("=== PYTHON OK in Worker container ===")
-try:
-    from worker_app.celery_app import celery_app
-    print("worker celery_app.main:", celery_app.main)
-    print("broker_url:", celery_app.conf.broker_url)
-    print("task_default_queue:", celery_app.conf.task_default_queue)
-    print("task_routes:", celery_app.conf.task_routes)
-    print("task_queues:", [(q.name, [b.name for b in q.bindings]) for q in (celery_app.conf.task_queues or [])])
-    # inspect via broker
-    insp = celery_app.control.inspect(timeout=3)
-    act = insp.active() or {}
-    reg = insp.registered() or {}
-    res = insp.reserved() or {}
-    for node, tasks in act.items():
-        print(f"ACTIVE on {node}: {len(tasks)} tasks")
-        for t in tasks:
-            print(f"  - {t.get('name')} args={str(t.get('args',''))[:60]}")
-    for node, tasks in res.items():
-        print(f"RESERVED on {node}: {len(tasks)} tasks")
-        for t in tasks:
-            print(f"  - {t.get('name')}")
-    print("registered lipsync count per node:")
-    for node, tasks in reg.items():
-        has = [t for t in tasks if 'lipsync' in t]
-        print(f"  {node}: total={len(tasks)}, lipsync={has}")
-except Exception as e:
-    traceback.print_exc()
-PYEOF
-docker cp /tmp/worker_diag.py "$W:/tmp/worker_diag.py"
-docker exec "$W" python /tmp/worker_diag.py 2>&1
-
-echo ""
-echo "=== D1. DB最近20条lipsync jobs ==="
-cat > /tmp/db_diag.py << 'PYEOF'
-import sys, os, traceback
-print("=== DB diag in API container ===")
-print("DATABASE_URL prefix:", os.environ.get("DATABASE_URL","")[:60])
-try:
-    from app.db.session import SessionLocal
-    from packages.adapters.sqlalchemy_impl.models import LipsyncJobModel
-    from datetime import datetime, timezone
-    db = SessionLocal()
-    jobs = db.query(LipsyncJobModel).order_by(LipsyncJobModel.created_at.desc()).limit(20).all()
-    print(f"Found {len(jobs)} recent lipsync jobs:")
-    for j in jobs:
-        err = getattr(j, 'error_message', None) or ''
-        t_id = getattr(j, 'celery_task_id', None) or ''
-        c_at = j.created_at.isoformat() if j.created_at else '?'
-        print(f"  id={j.id} status={j.status} mode={'tts' if (j.voice_id and not j.audio_url) else 'audio'} "
-              f"created={c_at} celery_task_id={t_id} err={(err[:100]+'...') if len(err)>100 else err!r}")
-    db.close()
-except Exception as e:
-    traceback.print_exc()
-PYEOF
-docker cp /tmp/db_diag.py "$A:/tmp/db_diag.py"
-docker exec "$A" python /tmp/db_diag.py 2>&1
-
-echo ""
-echo "=== D2. API容器监听端口 ==="
-docker exec "$A" sh -c "ss -tlnp 2>/dev/null || netstat -tlnp 2>/dev/null || cat /proc/net/tcp | head" 2>&1 | head -20
-
-echo ""
-echo "=== E1. 外部HTTPS健康检查 ==="
-curl -sk --max-time 8 https://staging-api.xiaoxiajianji.com/api/v1/health 2>&1 | head -3
-echo ""
-curl -sk --max-time 8 https://staging-api.xiaoxiajianji.com/api/v1/lipsync/jobs 2>&1 | head -3
-
-echo ""
-echo "#########################################################"
-echo "#  v3 诊断完成"
-echo "#########################################################"
@@ -1,117 +0,0 @@
-#!/bin/bash
-# Lipsync staging 诊断脚本（在staging服务器本机执行）
-set +e
-echo "#########################################################"
-echo "#  Lipsync TTS async 诊断报告"
-echo "#  Host: $(hostname)"
-echo "#  Date: $(date)"
-echo "#########################################################"
-
-echo ""
-echo "=== 1. docker ps (worker/api/redis) ==="
-docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.CreatedAt}}' | grep -E "worker|api|redis|nginx|NAMES"
-
-W=$(docker ps --format '{{.Names}}' | grep -E 'worker' | head -1)
-A=$(docker ps --format '{{.Names}}' | grep -E 'api' | grep -v 'web' | head -1)
-R=$(docker ps --format '{{.Names}}' | grep -E 'redis' | head -1)
-
-echo ""
-echo "=== Worker container: $W ==="
-echo "=== API container: $A ==="
-echo "=== Redis container: $R ==="
-
-echo ""
-echo "=== 2. Worker container image + created time ==="
-docker inspect "$W" --format 'Image={{.Config.Image}} Created={{.Created}}'
-docker inspect "$A" --format 'Image={{.Config.Image}} Created={{.Created}}'
-
-echo ""
-echo "=== 3. Worker 启动日志：celery ready / registered / lipsync 相关 ==="
-docker logs --tail=500 "$W" 2>&1 | grep -iE "lipsync|tts_synth|synthesize|celery@|ready|registered|register|error|traceback|import|critical|not registered|Consumer|mingle|tasks" | tail -120
-
-echo ""
-echo "=== 4. celery -A inspect registered ==="
-docker exec "$W" celery -A worker_app.celery_app inspect registered 2>&1 | tail -80
-
-echo ""
-echo "=== 5. celery -A inspect active/reserved ==="
-echo "--- active ---"
-docker exec "$W" celery -A worker_app.celery_app inspect active 2>&1 | tail -30
-echo "--- reserved ---"
-docker exec "$W" celery -A worker_app.celery_app inspect reserved 2>&1 | tail -30
-
-echo ""
-echo "=== 6. Worker 内 Python: import lipsync_tts task，看绑定 ==="
-docker exec "$W" python -c "
-from worker_app.celery_app import celery_app
-print('worker celery_app.main:', celery_app.main)
-print('worker celery_app.conf.imports:')
-for m in celery_app.conf.imports:
-    print('  ', m)
-import app.tasks.lipsync_tts as m
-t = m.tts_synthesize_and_submit
-print('task name:', t.name)
-print('task.app.main:', t.app.main)
-print('task.app is worker celery_app:', t.app is celery_app)
-print('task.name in worker celery_app.tasks:', t.name in celery_app.tasks)
-" 2>&1
-
-echo ""
-echo "=== 7. API 容器日志：lipsync/celery/apply_async 相关错误 ==="
-docker logs --tail=800 "$A" 2>&1 | grep -iE "lipsync|tts_|celery|apply_async|NotRegistered|traceback|error.*task" | tail -120
-
-echo ""
-echo "=== 8. API 内 Python: import task 看绑定 + apply_async 试投递（不消费） ==="
-docker exec "$A" python -c "
-import traceback
-try:
-    from app.tasks.lipsync_tts import tts_synthesize_and_submit
-    from app.core.celery_app import celery_app as api_app
-    print('api celery_app.main:', api_app.main)
-    print('task name:', tts_synthesize_and_submit.name)
-    print('task.app.main:', tts_synthesize_and_submit.app.main)
-    print('task.app is api_app:', tts_synthesize_and_submit.app is api_app)
-    print('task.name in api_app.tasks:', tts_synthesize_and_submit.name in api_app.tasks)
-    # 测试 send_task 是否能路由（不发送真任务）
-    print('api_app tasks includes lipsync_tts.synthesize_and_submit:', 'lipsync_tts.synthesize_and_submit' in api_app.tasks)
-except Exception as e:
-    traceback.print_exc()
-" 2>&1
-
-echo ""
-echo "=== 9. Redis 队列长度 ==="
-for q in celery generation transcode; do
-    len=$(docker exec "$R" redis-cli LLEN $q 2>&1)
-    echo "  $q length: $len"
-done
-
-echo ""
-echo "=== 10. Redis celery 队列 peek（最多5条） ==="
-docker exec "$R" redis-cli LRANGE celery 0 4 2>&1 | head -40
-
-echo ""
-echo "=== 11. Worker 关键文件内容校验 ==="
-echo "--- worker_app/celery_app.py imports 段 ---"
-docker exec "$W" grep -n "lipsync\|imports\s*=\|app.tasks\|apps.api" /app/apps/worker/worker_app/celery_app.py 2>&1
-echo ""
-echo "--- lipsync_tts.py 前20行（应该是 shared_task） ---"
-docker exec "$W" head -25 /app/apps/api/app/tasks/lipsync_tts.py 2>&1
-
-echo ""
-echo "=== 12. API lipsync_service.py apply_async 上下文 ==="
-docker exec "$A" grep -n -B3 -A10 "apply_async\|tts_synthesize" /app/apps/api/app/services/lipsync_service.py 2>&1 | head -80
-
-echo ""
-echo "=== 13. Worker /app 目录结构（app/tasks） ==="
-docker exec "$W" ls -la /app/apps/api/app/tasks/ 2>&1 | head -30
-echo ""
-echo "--- /app/apps/api/app/__init__.py? ---"
-docker exec "$W" ls -la /app/apps/api/app/__init__.py /app/apps/api/app/core/__init__.py /app/apps/api/app/api/__init__.py 2>&1
-echo ""
-echo "--- PYTHONPATH inside worker ---"
-docker exec "$W" env | grep PYTHONPATH
-
-echo ""
-echo "#########################################################"
-echo "#  诊断完成"
-echo "#########################################################"
@@ -0,0 +1 @@
+# xiaoxia-saas shared packages namespace
@@ -0,0 +1 @@
+# adapter implementations namespace
@@ -547,7 +547,7 @@ class TestAiAvatarRenderService:
        with (
            patch.object(svc, "_download_video", return_value="/tmp/video.mp4"),
            patch.object(svc, "_upload_to_oss", side_effect=lambda path, key: f"https://oss/{key}"),
-            patch("os.system", return_value=0),
+            patch("subprocess.run") as mock_run,
            patch("tempfile.TemporaryDirectory") as tmpdir_mock,
            patch(
                "app.services.ai_avatar_cover_service.generate_smart_cover", return_value="https://oss/smart_cover.jpg"
@@ -557,6 +557,9 @@ class TestAiAvatarRenderService:
                "packages.adapters.sqlalchemy_impl.generated_video_repository.SQLAlchemyGeneratedVideoRepository"
            ) as repo_cls,
        ):
+            import subprocess as _sp
+
+            mock_run.return_value = _sp.CompletedProcess(args=[], returncode=0, stdout="", stderr="")
            import tempfile as _tf

            tmpdir_mock.return_value.__enter__ = MagicMock(return_value="/tmp/testdir")
@@ -605,10 +608,13 @@ class TestAiAvatarRenderService:
        with (
            patch.object(svc, "_download_video", return_value="/tmp/video.mp4"),
            patch.object(svc, "_upload_to_oss", side_effect=lambda path, key: f"https://oss/{key}"),
-            patch("os.system", return_value=0),
+            patch("subprocess.run") as mock_run,
            patch("tempfile.TemporaryDirectory") as tmpdir_mock,
            patch("app.services.ai_avatar_cover_service.generate_smart_cover", side_effect=RuntimeError("DB error")),
        ):
+            import subprocess as _sp
+
+            mock_run.return_value = _sp.CompletedProcess(args=[], returncode=0, stdout="", stderr="")
            tmpdir_mock.return_value.__enter__ = MagicMock(return_value="/tmp/testdir")
            tmpdir_mock.return_value.__exit__ = MagicMock(return_value=False)
            svc.execute_render("render-clip-fail")
@@ -35,7 +35,10 @@ class TestFFmpegPresetOptimization:
            final_label=None,
            output_path="/tmp/output.mp4",
        )
-        assert "-preset veryfast" in cmd, f"期望 -preset veryfast，实际命令: {cmd}"
+        # cmd 现在是 list[str]；preset 与值是相邻两个元素
+        assert "-preset" in cmd, f"期望包含 -preset，实际命令: {cmd}"
+        preset_idx = cmd.index("-preset")
+        assert cmd[preset_idx + 1] == "veryfast", f"期望 veryfast，实际: {cmd}"

    def test_preset_veryfast_with_filter(self):
        """带滤镜场景下也必须使用 veryfast."""
@@ -49,7 +52,8 @@ class TestFFmpegPresetOptimization:
            final_label="[v]",
            output_path="/tmp/output.mp4",
        )
-        assert "-preset veryfast" in cmd
+        assert "-preset" in cmd
+        assert cmd[cmd.index("-preset") + 1] == "veryfast"
        assert "-filter_complex" in cmd

    def test_preset_not_fast(self):
@@ -65,11 +69,11 @@ class TestFFmpegPresetOptimization:
            output_path="/tmp/output.mp4",
        )
        # 确保是 veryfast 而不是 fast
-        assert "-preset veryfast" in cmd
-        # 排除 "fast" 单独出现（veryfast 包含 fast 子串，需精确判断）
-        parts = cmd.split()
-        preset_idx = parts.index("-preset")
-        assert parts[preset_idx + 1] == "veryfast"
+        assert "-preset" in cmd
+        preset_idx = cmd.index("-preset")
+        assert cmd[preset_idx + 1] == "veryfast"
+        # 禁止 fast 单独作为 preset 值（veryfast 包含 "fast" 子串，不影响）
+        assert cmd[preset_idx + 1] != "fast"


 # ═══════════════════════════════════════════════════════════════════════════════
@@ -143,8 +147,8 @@ class TestCreateJobAsyncTTS:
        assert args[2] == "v-1"  # voice_id
        assert args[3] == "测试文本"  # script_text

-    def test_tts_mode_celery_dispatch_failure_still_creates_job(self):
-        """Celery dispatch 失败时，job 记录已创建，状态保持 tts_processing."""
+    def test_tts_mode_celery_dispatch_failure_marks_job_failed(self):
+        """Celery dispatch 失败时，job 标为 failed 并写入 error_message，前端轮询能直接看到错误."""
        svc, client, cosy = _make_service_with_mocks()

        with patch("app.services.lipsync_service.tts_synthesize_and_submit") as mock_task:
@@ -157,9 +161,11 @@ class TestCreateJobAsyncTTS:
                script_text="测试文本",
            )

-        # job 已创建
+        # job 已创建且状态标为 failed
        assert job is not None
-        assert job.status == "tts_processing"
+        assert job.status == "failed"
+        assert "Celery 任务投递失败" in job.error_message
+        assert job.error_code == "AsyncDispatchFailed"
        # MediaKit 未被调用
        client.submit_lipsync.assert_not_called()

@@ -73,12 +73,16 @@ def _apply_all_patches(
    lipsync_tts.run() 在函数体内部懒 import 多个模块，通过 sys.modules 注入
    伪造包路径避免真实导入；对存在的模块用 patch() 替换返回值/side_effect。
    """
-    fake_db_mod = ModuleType("packages.adapters.sqlalchemy_impl.database")
+    # SessionLocal 通过懒探测获取（Worker 用 worker_app.db，API 用 app.db），
+    # 测试环境里两个模块都能被真实导入，必须同时 mock 保证用的是 fake session。
+    fake_app_db = ModuleType("app.db")
+    fake_worker_db = ModuleType("worker_app.db")
    session, factory = _build_session(job)
-    fake_db_mod.SessionLocal = factory
+    fake_app_db.SessionLocal = factory
+    fake_worker_db.SessionLocal = factory

    patches = [
-        patch.dict(sys.modules, {"packages.adapters.sqlalchemy_impl.database": fake_db_mod}),
+        patch.dict(sys.modules, {"app.db": fake_app_db, "worker_app.db": fake_worker_db}),
        patch(
            "app.tasks.lipsync_tts._sign_media_url",
            side_effect=lambda url: url + "?signed" if url else url,
@@ -289,9 +293,11 @@ class TestTtsSynthesizeAndSubmit:
        from app.tasks.lipsync_tts import tts_synthesize_and_submit

        job = _make_fake_job()
-        fake_db_mod = ModuleType("packages.adapters.sqlalchemy_impl.database")
+        fake_app_db = ModuleType("app.db")
+        fake_worker_db = ModuleType("worker_app.db")
        session, factory = _build_session(job)
-        fake_db_mod.SessionLocal = factory
+        fake_app_db.SessionLocal = factory
+        fake_worker_db.SessionLocal = factory

        # CosyVoiceService 在 __init__ 抛 RuntimeError（非 CosyVoiceError/ValueError）
        fake_cosy_mod = ModuleType("packages.application.cosyvoice_service")
@@ -309,7 +315,8 @@ class TestTtsSynthesizeAndSubmit:
        with patch.dict(
            sys.modules,
            {
-                "packages.adapters.sqlalchemy_impl.database": fake_db_mod,
+                "app.db": fake_app_db,
+                "worker_app.db": fake_worker_db,
                "packages.application.cosyvoice_service": fake_cosy_mod,
            },
        ):