⏺ feat: optimize LLM API Key configuration flow (#169)

Co-authored-by: nishenghao.nsh <nishenghao.nsh@oceanbase.com>

Author: niiish32x

packages/derisk-app/src/derisk_app/openapi/api_v1/config_api.py

@@ -56,6 +56,17 @@ class SecretRequest(BaseModel):
     description: Optional[str] = None
 
 
+class LLMKeyRequest(BaseModel):
+    provider: str
+    api_key: str
+
+
+class LLMKeyStatus(BaseModel):
+    provider: str
+    description: str
+    is_configured: bool
+
+
 _config_manager = None
 
 
@@ -599,9 +610,12 @@ async def list_secrets():
 
     default_secrets = {
         "master_encrypt_key": "主加密密钥，用于加密其他敏感数据",
-        "openai_api_key": "OpenAI API Key",
-        "dashscope_api_key": "阿里云 DashScope API Key",
-        "anthropic_api_key": "Anthropic API Key",
+        "openai_api_key": "OpenAI API Key (系统设置 - LLM)",
+        "dashscope_api_key": "阿里云 DashScope API Key (系统设置 - LLM)",
+        "alibaba_api_key": "阿里云 API Key (系统设置 - LLM)",
+        "anthropic_api_key": "Anthropic API Key (系统设置 - LLM)",
+        "claude_api_key": "Claude API Key (系统设置 - LLM)",
+        "llm_api_key": "通用 LLM API Key (系统设置 - LLM)",
         "oss_access_key_id": "阿里云 OSS Access Key ID",
         "oss_access_key_secret": "阿里云 OSS Access Key Secret",
         "db_password": "数据库密码",
@@ -710,6 +724,143 @@ async def export_config_safe():
     )
 
 
+@router.get("/llm-keys")
+async def list_llm_keys():
+    """获取 LLM Key 配置状态列表
+
+    只返回是否已配置的状态，不返回实际的 key 值
+    """
+    from derisk_core.config.encryption import list_secrets as get_secrets_status
+
+    secrets_status = get_secrets_status()
+
+    # 定义支持的 LLM Provider 及其默认描述（简化为最常用的两个）
+    llm_providers = {
+        "openai": "OpenAI API Key (GPT 系列模型)",
+        "alibaba": "阿里云 DashScope API Key (通义千问/Qwen/DeepSeek 等)",
+    }
+
+    # 定义各个 provider 对应的 secrets key 名称
+    provider_secret_keys = {
+        "openai": ["openai_api_key"],
+        "alibaba": ["dashscope_api_key"],
+    }
+
+    llm_keys = []
+    for provider, description in llm_providers.items():
+        secret_keys = provider_secret_keys.get(provider, [])
+        # 检查该 provider 是否有任意一个对应的 secret key 已配置
+        is_configured = any(
+            secrets_status.get(key, False) for key in secret_keys
+        )
+
+        llm_keys.append({
+            "provider": provider,
+            "description": description,
+            "is_configured": is_configured,
+        })
+
+    return JSONResponse(
+        content={
+            "success": True,
+            "data": llm_keys,
+            "note": "只返回配置状态，不返回实际的 key 值",
+        }
+    )
+
+
+@router.post("/llm-keys")
+async def set_llm_key(request: LLMKeyRequest):
+    """设置 LLM API Key
+
+    将 API Key 加密存储到 secrets 中，配置后立即生效
+    """
+    from derisk_core.config.encryption import set_secret
+    import logging
+
+    logger = logging.getLogger(__name__)
+
+    try:
+        # 根据 provider 确定存储的 key 名称（简化为只支持 openai 和 alibaba）
+        provider = request.provider.lower()
+
+        secret_key_mapping = {
+            "openai": "openai_api_key",
+            "alibaba": "dashscope_api_key",
+        }
+
+        if provider not in secret_key_mapping:
+            raise HTTPException(status_code=400, detail=f"不支持的 provider: {provider}")
+
+        secret_name = secret_key_mapping.get(provider)
+
+        # 清理 API Key（去除前后空格）
+        api_key = request.api_key.strip() if request.api_key else ""
+
+        if not api_key:
+            raise HTTPException(status_code=400, detail="API Key 不能为空")
+
+        # 记录调试信息（隐藏部分 key）
+        key_preview = f"{api_key[:8]}...{api_key[-4:]}" if len(api_key) > 12 else "***"
+        logger.info(f"Saving API key for provider={provider}, secret_name={secret_name}, key_preview={key_preview}, key_length={len(api_key)}")
+
+        # 加密存储 API Key
+        success = set_secret(secret_name, api_key)
+
+        if success:
+            return JSONResponse(
+                content={
+                    "success": True,
+                    "message": f"{provider} API Key 已加密存储",
+                    "provider": provider,
+                    "secret_name": secret_name,
+                    "note": "配置已生效，新的请求将使用此 API Key",
+                }
+            )
+        else:
+            raise HTTPException(status_code=500, detail="保存 API Key 失败")
+    except Exception as e:
+        logger.error(f"Failed to save LLM key: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/llm-keys/{provider}")
+async def delete_llm_key(provider: str):
+    """删除 LLM API Key 配置
+
+    删除后，系统将回退到使用配置文件中的 API Key
+    """
+    from derisk_core.config.encryption import delete_secret
+
+    try:
+        provider = provider.lower()
+
+        secret_key_mapping = {
+            "openai": "openai_api_key",
+            "alibaba": "dashscope_api_key",
+        }
+
+        if provider not in secret_key_mapping:
+            raise HTTPException(status_code=400, detail=f"不支持的 provider: {provider}")
+
+        secret_name = secret_key_mapping.get(provider)
+
+        success = delete_secret(secret_name)
+
+        if success:
+            return JSONResponse(
+                content={
+                    "success": True,
+                    "message": f"{provider} API Key 已删除",
+                    "note": "已删除系统设置中的 API Key，将回退到使用配置文件中的配置",
+                }
+            )
+        else:
+            raise HTTPException(status_code=500, detail="删除 API Key 失败")
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
 @router.get("/system")
 async def get_system_config():
     manager = get_config_manager()

packages/derisk-core/src/derisk/agent/util/llm/llm_client.py

@@ -21,6 +21,74 @@
 logger = logging.getLogger(__name__)
 
 
+def _get_api_key_from_secrets(provider_name: str, base_url: Optional[str] = None) -> Optional[str]:
+    """从加密存储的 secrets 中获取 API Key
+
+    优先级：
+    1. 先尝试获取特定于 provider 的 key (如 openai_api_key, dashscope_api_key)
+    2. 根据 base_url 判断是否使用特定平台的 key
+    3. 如果没有，尝试通用的 llm_api_key
+
+    Args:
+        provider_name: Provider 名称 (如 openai, alibaba, anthropic)
+        base_url: API base URL，用于判断实际使用的平台
+
+    Returns:
+        API Key 或 None
+    """
+    try:
+        from derisk_core.config.encryption import get_secret
+
+        provider_name_lower = provider_name.lower()
+
+        # 首先尝试获取 provider 特定的 key
+        provider_specific_keys = {
+            "openai": ["openai_api_key"],
+            "alibaba": ["dashscope_api_key", "alibaba_api_key"],
+            "anthropic": ["anthropic_api_key", "claude_api_key"],
+            "dashscope": ["dashscope_api_key"],
+            "claude": ["anthropic_api_key", "claude_api_key"],
+        }
+
+        # 根据 base_url 判断实际使用的平台（处理 OpenAI 兼容模式）
+        base_url_lower = base_url.lower() if base_url else ""
+        if "dashscope" in base_url_lower or "aliyun" in base_url_lower:
+            # 阿里云 DashScope 使用 OpenAI 兼容 API，但实际 key 是 dashscope_api_key
+            keys_to_try = ["dashscope_api_key", "alibaba_api_key", "llm_api_key"]
+        elif "anthropic" in base_url_lower or "claude" in base_url_lower:
+            keys_to_try = ["anthropic_api_key", "claude_api_key", "llm_api_key"]
+        elif "openai" in base_url_lower or "openai.com" in base_url_lower:
+            keys_to_try = ["openai_api_key", "llm_api_key"]
+        else:
+            # 使用默认的 provider 映射
+            keys_to_try = provider_specific_keys.get(provider_name_lower, [])
+            if provider_name_lower == "openai":
+                # openai provider 可能是 OpenAI 也可能是其他 OpenAI 兼容服务
+                # 尝试所有可能的 key
+                keys_to_try = ["openai_api_key", "dashscope_api_key", "alibaba_api_key", "anthropic_api_key"]
+
+        # 最后添加通用的 llm_api_key
+        if "llm_api_key" not in keys_to_try:
+            keys_to_try.append("llm_api_key")
+
+        logger.debug(f"Looking for API key: provider={provider_name}, base_url={base_url}, keys_to_try={keys_to_try}")
+
+        for key_name in keys_to_try:
+            secret_value = get_secret(key_name)
+            if secret_value:
+                # 记录找到的 key（只显示部分信息）
+                key_preview = f"{secret_value[:8]}...{secret_value[-4:]}" if len(secret_value) > 12 else "***"
+                logger.info(
+                    f"Found API key from secrets: key_name={key_name}, provider={provider_name}, preview={key_preview}, length={len(secret_value)}")
+                return secret_value
+
+        logger.debug(f"No API key found in secrets for provider={provider_name}")
+        return None
+    except Exception as e:
+        logger.warning(f"Failed to get API key from secrets: {e}")
+        return None
+
+
 class AgentLLMOut(BaseModel):
     llm_name: Optional[str] = None
     llm_context: Optional[dict] = None
@@ -58,10 +126,10 @@ class AIWrapper:
     }
 
     def __init__(
-        self,
-        llm_client: Optional[LLMClient] = None,
-        llm_config: Optional[AgentLLMConfig] = None,
-        output_parser: Optional[BaseOutputParser] = None,
+            self,
+            llm_client: Optional[LLMClient] = None,
+            llm_config: Optional[AgentLLMConfig] = None,
+            output_parser: Optional[BaseOutputParser] = None,
     ):
         """Create an AIWrapper instance.
 
@@ -89,7 +157,34 @@ def _init_provider(self):
         api_key = self._llm_config.api_key
         base_url = self._llm_config.base_url
 
+        # 检查 api_key 是否是占位符（未解析的配置引用或默认值）
+        def _is_placeholder_key(key: Optional[str]) -> bool:
+            if not key:
+                return True
+            # 检查是否是 ${env:xxx} 或 ${secrets.xxx} 格式
+            if key.startswith("${"):
+                return True
+            # 检查是否是常见的占位符值
+            placeholder_patterns = ["sk-...", "sk-xxxx", "your_api_key", "xxx", "placeholder"]
+            key_lower = key.lower()
+            if any(pattern in key_lower for pattern in placeholder_patterns):
+                return True
+            return False
+
+        is_placeholder = _is_placeholder_key(api_key)
+        if is_placeholder and api_key:
+            logger.debug(f"API key appears to be a placeholder: {api_key[:20]}..., will try to get from secrets")
+
+        # 优先级：系统设置(secrets) > 配置文件 > 环境变量
+        if not api_key or is_placeholder:
+            # 1. 首先尝试从加密存储的 secrets 中获取
+            secrets_key = _get_api_key_from_secrets(provider_name, base_url)
+            if secrets_key:
+                api_key = secrets_key
+                logger.info(f"Using API key from system secrets for provider={provider_name}")
+
         if not api_key:
+            # 2. 然后尝试从环境变量获取
             env_key = ProviderRegistry.get_env_key(provider_name)
             if env_key:
                 api_key = os.getenv(env_key)
@@ -111,7 +206,7 @@ def _init_provider(self):
             model=self._llm_config.model,
             **kwargs,
         )
-        
+
         if provider:
             self._provider = provider
         else:
@@ -172,9 +267,35 @@ async def create(self, **config):
                     try:
                         temp_llm_config = AgentLLMConfig.from_dict(model_config_dict)
                         provider_name = temp_llm_config.provider.lower()
-                        api_key = temp_llm_config.api_key
+
                         base_url = temp_llm_config.base_url
 
+                        # 检查 api_key 是否是占位符
+                        def _is_placeholder_key(key: Optional[str]) -> bool:
+                            if not key:
+                                return True
+                            if key.startswith("${"):
+                                return True
+                            placeholder_patterns = ["sk-...", "sk-xxxx", "your_api_key", "xxx", "placeholder"]
+                            key_lower = key.lower()
+                            if any(pattern in key_lower for pattern in placeholder_patterns):
+                                return True
+                            return False
+
+                        api_key = temp_llm_config.api_key
+                        is_placeholder = _is_placeholder_key(api_key)
+
+                        # 优先级：系统设置(secrets) > 配置文件 > 环境变量
+                        if not api_key or is_placeholder:
+                            api_key = _get_api_key_from_secrets(provider_name, base_url)
+                            if api_key:
+                                logger.info(
+                                    f"Using API key from system secrets for model={llm_model}, provider={provider_name}")
+                        if not api_key:
+                            env_key = ProviderRegistry.get_env_key(provider_name)
+                            if env_key:
+                                api_key = os.getenv(env_key)
+
                         provider = ProviderRegistry.create_provider(
                             name=provider_name,
                             api_key=api_key or "",
@@ -253,9 +374,9 @@ async def create(self, **config):
                 content = msg.content if hasattr(msg, "content") else str(msg)
                 if isinstance(content, list):
                     content_str = (
-                        "["
-                        + ", ".join([f"{c.get('type', 'unknown')}" for c in content])
-                        + "]"
+                            "["
+                            + ", ".join([f"{c.get('type', 'unknown')}" for c in content])
+                            + "]"
                     )
                 else:
                     content_str = (

packages/derisk-core/src/derisk_core/config/encryption.py

@@ -127,9 +127,12 @@ def decrypt(self, ciphertext: str) -> str:
             key = self._derive_key(self.get_master_key())
             f = self._fernet(key)
             encrypted = ciphertext[4:].encode()
-            return f.decrypt(encrypted).decode()
+            decrypted = f.decrypt(encrypted).decode()
+            logger.debug(f"Successfully decrypted data, length={len(decrypted)}")
+            return decrypted
         except Exception as e:
-            logger.error(f"Decryption failed: {e}")
+            logger.error(f"Decryption failed: {e}, ciphertext_prefix={ciphertext[:20] if ciphertext else 'empty'}...")
+            # 返回空字符串表示解密失败
             return ""