From 8988e91ee9822e0465bc498648a9a7d02989d04c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= <kvtodev@outlook.com>
Date: Mon, 21 Sep 2026 20:06:24 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=A8=E5=9B=BE=E7=89=87=20provider?=
 =?UTF-8?q?=20=E5=90=AF=E5=8A=A8=E6=8A=A5=E9=94=99=E4=B8=8E=E6=97=A5?=
 =?UTF-8?q?=E5=BF=97=E4=BF=A1=E6=81=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

缺少 BASE_URL / API_KEY 时点名对应环境变量

启动成功时记录 provider、base_url 与超时配置
---
 server-rs/crates/api-server/src/state.rs | 32 +++++++++++++++++++-----
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/server-rs/crates/api-server/src/state.rs b/server-rs/crates/api-server/src/state.rs
index 2fe39f32e..8496a5a94 100644
--- a/server-rs/crates/api-server/src/state.rs
+++ b/server-rs/crates/api-server/src/state.rs
@@ -2518,6 +2518,7 @@ fn build_required_image_provider_client(
     api_key: Option<String>,
     request_timeout_ms: u64,
 ) -> Result<ImageProviderClient, AppStateInitError> {
+    let (base_url_env, api_key_env) = required_image_provider_env_vars(provider);
     #[cfg(test)]
     let (base_url, api_key) = (
         if base_url.trim().is_empty() {
@@ -2532,8 +2533,9 @@ fn build_required_image_provider_client(
     let base_url = base_url.trim().trim_end_matches('/');
     if base_url.is_empty() {
         return Err(AppStateInitError::DependencyUnavailable(format!(
-            "{} 图片 provider 缺少 BASE_URL 配置",
-            provider.as_str()
+            "{} 图片 provider 缺少 BASE_URL 配置：请设置 {}。两个图片 provider 都在启动时构造，缺失即阻止 api-server 启动，不做 provider 回退。",
+            provider.as_str(),
+            base_url_env
         )));
     }
     let api_key = api_key
@@ -2542,18 +2544,36 @@ fn build_required_image_provider_client(
         .filter(|value| !value.is_empty())
         .ok_or_else(|| {
             AppStateInitError::DependencyUnavailable(format!(
-                "{} 图片 provider 缺少 API_KEY 配置",
-                provider.as_str()
+                "{} 图片 provider 缺少 API_KEY 配置：请设置 {}。两个图片 provider 都在启动时构造，缺失即阻止 api-server 启动，不做 provider 回退。",
+                provider.as_str(),
+                api_key_env
             ))
         })?;
-    build_image_provider_client(ImageProviderSettings {
+    let client = build_image_provider_client(ImageProviderSettings {
         provider,
         base_url: base_url.to_string(),
         api_key: api_key.to_string(),
         request_timeout_ms: request_timeout_ms.max(1),
         request_deadline: None,
     })
-    .map_err(|error| AppStateInitError::DependencyUnavailable(error.to_string()))
+    .map_err(|error| AppStateInitError::DependencyUnavailable(error.to_string()))?;
+    info!(
+        provider = provider.as_str(),
+        base_url = %base_url,
+        request_timeout_ms = request_timeout_ms.max(1),
+        env = base_url_env,
+        api_key_env,
+        "图片 provider client 已启用"
+    );
+    Ok(client)
+}
+
+/// 图片 provider 在启动期必须齐备的环境变量名，用于给出可直接执行的报错与启动日志。
+fn required_image_provider_env_vars(provider: ImageProvider) -> (&'static str, &'static str) {
+    match provider {
+        ImageProvider::VectorEngine => ("VECTOR_ENGINE_BASE_URL", "VECTOR_ENGINE_API_KEY"),
+        ImageProvider::Tiantoken => ("TIANTOKEN_BASE_URL", "TIANTOKEN_API_KEY"),
+    }
 }
 
 fn build_oss_client(config: &AppConfig) -> Result<Option<OssClient>, AppStateInitError> {