fix(backend): 部署韧性——模型自愈/就绪门禁/全局代理/启动诊断

- whisper: model.bin 截断/损坏时删目录重下重试一次，修「Unable to open file model.bin」死循环；mlx 同样按 config.json 判完整性 - /generate_note 加就绪门禁：本地转写引擎模型没下好直接拦截，返回 reason=transcriber_model_not_ready，不让任务静默卡在首次下载 - 全局代理：新增 ProxyConfigManager（JSON 配置 + HTTP_PROXY env 兜底） + build_openai_client，统一注入代理到 LLM/Groq 客户端；yt-dlp 与 youtube-transcript-api 也走代理 - build_openai_client 校验 api_key 非空，空 key 给「xxx 的 API Key 未配置」而不是天书般的 Illegal header value b'Bearer ' - universal_gpt: 模型拒绝自定义 temperature（o1/o3/gpt-5 系列）时就地去掉参数重试，不消耗重试预算 - connect_test 改用真实 chat completion 而非 /v1/models 探测 - main.py: lifespan 拆 [startup 1/5..5/5] 分段日志 + 异常清晰定位 - /sys_health 重构为结构化返回 {backend,ffmpeg,db,whisper_model} Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-13 03:30:10 +08:00 · 2026-05-14 19:01:14 +08:00
parent 88d25f8cc1
commit 41f17592c2
16 changed files with 534 additions and 92 deletions
--- a/backend/app/services/model.py
+++ b/backend/app/services/model.py
@@ -100,23 +100,46 @@ class ModelService:
            logger.error(f"[{provider_id}] 获取模型失败: {e}")
            return []
    @staticmethod
-    def connect_test(id: str) -> bool:
+    def connect_test(id: str, model: str | None = None) -> bool:
+        """连通性测试：发一条最小化 chat completion。

+        model 优先级：
+          1. 调用方显式传入（前端可在「模型选择」UI 里挑一个再测）
+          2. DB 中该 provider 已保存的第一个模型
+          3. 都没有 → 抛错让用户先加一个模型
+        """
        provider = ProviderService.get_provider_by_id(id)
-
-        if provider:
-            if not provider.get('api_key'):
-                raise ProviderError(code=ProviderErrorEnum.NOT_FOUND.code, message=ProviderErrorEnum.NOT_FOUND.message)
-            result =  OpenAICompatibleProvider.test_connection(
-                api_key=provider.get('api_key'),
-                base_url=provider.get('base_url')
+        if not provider:
+            raise ProviderError(
+                code=ProviderErrorEnum.NOT_FOUND.code,
+                message=ProviderErrorEnum.NOT_FOUND.message,
+            )
+        if not provider.get('api_key'):
+            raise ProviderError(
+                code=ProviderErrorEnum.NOT_FOUND.code,
+                message=ProviderErrorEnum.NOT_FOUND.message,
            )
-            if result:
-                return True
-            else:
-                raise ProviderError(code=ProviderErrorEnum.WRONG_PARAMETER.code,message=ProviderErrorEnum.WRONG_PARAMETER.message)

-        raise ProviderError(code=ProviderErrorEnum.NOT_FOUND.code, message=ProviderErrorEnum.NOT_FOUND.message)
+        if not model:
+            saved_models = ModelService.get_enabled_models_by_provider(provider["id"])
+            if not saved_models:
+                raise ProviderError(
+                    code=ProviderErrorEnum.WRONG_PARAMETER.code,
+                    message="请先为该供应商添加至少一个模型再测试连通性",
+                )
+            model = saved_models[0]["model_name"]
+
+        ok = OpenAICompatibleProvider.test_connection(
+            api_key=provider.get('api_key'),
+            base_url=provider.get('base_url'),
+            model=model,
+        )
+        if ok:
+            return True
+        raise ProviderError(
+            code=ProviderErrorEnum.WRONG_PARAMETER.code,
+            message=ProviderErrorEnum.WRONG_PARAMETER.message,
+        )



--- a/backend/app/services/proxy_config_manager.py
+++ b/backend/app/services/proxy_config_manager.py
@@ -0,0 +1,60 @@
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+class ProxyConfigManager:
+    """全局代理配置，存 JSON 文件，支持前端动态修改。
+
+    作用范围：LLM API + 转写 API（Groq 等）+ yt-dlp 视频下载。
+    优先级：配置文件里 enabled=true 的 url > 环境变量 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY。
+    这样桌面端/web 用户在设置页填，docker/服务器部署用环境变量兜底。
+    """
+
+    def __init__(self, filepath: str = "config/proxy.json"):
+        self.path = Path(filepath)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _read(self) -> Dict[str, Any]:
+        if not self.path.exists():
+            return {}
+        try:
+            with self.path.open("r", encoding="utf-8") as f:
+                return json.load(f)
+        except Exception:
+            return {}
+
+    def _write(self, data: Dict[str, Any]):
+        with self.path.open("w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+
+    def get_config(self) -> Dict[str, Any]:
+        data = self._read()
+        return {
+            "enabled": bool(data.get("enabled", False)),
+            "url": data.get("url", "") or "",
+        }
+
+    def update_config(self, enabled: bool, url: Optional[str] = None) -> Dict[str, Any]:
+        data = self._read()
+        data["enabled"] = bool(enabled)
+        if url is not None:
+            data["url"] = url.strip()
+        self._write(data)
+        return self.get_config()
+
+    def get_proxy_url(self) -> Optional[str]:
+        """返回当前生效的代理 URL；没有则 None。
+
+        - 配置文件 enabled=true 且 url 非空 → 用配置的 url
+        - 否则回退到环境变量（标准的 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY，大小写都认）
+        """
+        cfg = self.get_config()
+        if cfg["enabled"] and cfg["url"]:
+            return cfg["url"]
+        for key in ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"):
+            val = os.environ.get(key)
+            if val:
+                return val
+        return None
--- a/backend/app/services/transcriber_config_manager.py
+++ b/backend/app/services/transcriber_config_manager.py
@@ -61,3 +61,54 @@ class TranscriberConfigManager:

    def get_whisper_model_size(self) -> str:
        return self.get_config()["whisper_model_size"]
+
+    def is_model_ready(self) -> Dict[str, Any]:
+        """当前转写器是否就绪可用。
+
+        返回 {ready, transcriber_type, model_size, downloading, reason}：
+          - 在线引擎 (groq/bcut/kuaishou)：永远 ready（不需要本地模型）
+          - fast-whisper：检查 whisper-{size}/model.bin 落盘
+          - mlx-whisper：检查 {repo_id}/config.json 落盘
+        给 /generate_note 入口做「开始视频前先确认模型下载好」的门禁用。
+        """
+        cfg = self.get_config()
+        ttype = cfg["transcriber_type"]
+        size = cfg["whisper_model_size"]
+        result = {
+            "ready": True,
+            "transcriber_type": ttype,
+            "model_size": size,
+            "downloading": False,
+            "reason": "",
+        }
+        if ttype not in ("fast-whisper", "mlx-whisper"):
+            return result  # 在线引擎无需本地模型
+
+        # 延迟 import 避免与 routers.config 的循环依赖；只取纯函数，不触发路由副作用
+        try:
+            from app.routers.config import (
+                _check_whisper_model_exists,
+                _check_mlx_whisper_model_exists,
+                _downloading,
+            )
+        except Exception as e:
+            # 拿不到检查函数时保守放行，不要把用户卡死
+            result["reason"] = f"无法检查模型状态: {e}"
+            return result
+
+        if ttype == "fast-whisper":
+            downloaded = _check_whisper_model_exists(size, "whisper")
+            downloading = _downloading.get(size) == "downloading"
+        else:  # mlx-whisper
+            downloaded = _check_mlx_whisper_model_exists(size)
+            downloading = _downloading.get(f"mlx-{size}") == "downloading"
+
+        result["downloading"] = downloading
+        if downloaded:
+            return result
+        result["ready"] = False
+        result["reason"] = (
+            f"转写模型 {ttype} / {size} 尚未下载就绪"
+            + ("，正在下载中，请稍候" if downloading else "，请先在「设置 → 音频转写配置」页下载")
+        )
+        return result