fix(admin): 修复 Key 自动获取模型时 allowed_models 同步逻辑

- 关闭自动获取上游模型时清空 allowed_models
- 开启自动获取上游模型时立即拉取并覆盖 allowed_models
- 增加模型覆盖提示并补充相关回归测试

apps/aether-gateway/src/handlers/admin/provider/endpoint_keys/mutations/update.rs

@@ -1,7 +1,7 @@
 use crate::handlers::admin::provider::shared::paths::admin_update_key_id;
 use crate::handlers::admin::provider::shared::payloads::AdminProviderKeyUpdatePatch;
 use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
-use crate::GatewayError;
+use crate::{model_fetch::perform_model_fetch_for_key, GatewayError};
 use axum::{
     body::{Body, Bytes},
     http,
@@ -81,6 +81,33 @@ pub(super) async fn maybe_handle(
     let Some(updated) = state.update_provider_catalog_key(&updated_record).await? else {
         return Ok(None);
     };
+    let should_overwrite_allowed_models_immediately =
+        !existing_key.auto_fetch_models && updated.auto_fetch_models;
+    let updated = if should_overwrite_allowed_models_immediately {
+        let summary =
+            perform_model_fetch_for_key(state.as_ref(), &provider.id, &updated.id).await?;
+        if summary.succeeded == 0 {
+            let detail = state
+                .read_provider_catalog_keys_by_ids(std::slice::from_ref(&key_id))
+                .await?
+                .into_iter()
+                .next()
+                .and_then(|key| key.last_models_fetch_error)
+                .unwrap_or_else(|| "未获取到可用上游模型".to_string());
+            return Err(GatewayError::Internal(format!(
+                "开启自动获取模型后同步上游模型失败: {detail}"
+            )));
+        }
+
+        state
+            .read_provider_catalog_keys_by_ids(std::slice::from_ref(&key_id))
+            .await?
+            .into_iter()
+            .next()
+            .unwrap_or(updated)
+    } else {
+        updated
+    };
     let now_unix_secs = SystemTime::now()
         .duration_since(UNIX_EPOCH)
         .ok()

apps/aether-gateway/src/handlers/admin/provider/write/keys/update.rs

@@ -22,6 +22,8 @@ pub(crate) async fn build_admin_update_provider_key_record(
     let state = state.as_ref();
     let mut updated = existing.clone();
     let (fields, payload) = patch.into_parts();
+    let auto_fetch_disabled =
+        existing.auto_fetch_models && matches!(payload.auto_fetch_models, Some(false));
     let current_auth_type = normalize_auth_type(Some(&existing.auth_type))?;
     let target_auth_type = payload
         .auth_type
@@ -245,6 +247,9 @@ pub(crate) async fn build_admin_update_provider_key_record(
     if let Some(auto_fetch_models) = payload.auto_fetch_models {
         updated.auto_fetch_models = auto_fetch_models;
     }
+    if auto_fetch_disabled {
+        updated.allowed_models = None;
+    }
     if fields.contains("locked_models") {
         updated.locked_models =
             normalize_string_list(payload.locked_models).map(|value| json!(value));

apps/aether-gateway/src/model_fetch/mod.rs

@@ -4,4 +4,6 @@ mod tests;
 
 pub(crate) use aether_model_fetch::ModelFetchRunSummary;
 pub(crate) use runtime::state::ModelFetchRuntimeState;
-pub(crate) use runtime::{perform_model_fetch_once, spawn_model_fetch_worker};
+pub(crate) use runtime::{
+    perform_model_fetch_for_key, perform_model_fetch_once, spawn_model_fetch_worker,
+};

apps/aether-gateway/src/model_fetch/runtime.rs

@@ -65,29 +65,56 @@ pub(crate) async fn perform_model_fetch_once(
     perform_model_fetch_once_with_state(state).await
 }
 
+pub(crate) async fn perform_model_fetch_for_key(
+    state: &AppState,
+    provider_id: &str,
+    key_id: &str,
+) -> Result<ModelFetchRunSummary, GatewayError> {
+    perform_model_fetch_for_key_with_state(state, provider_id, key_id).await
+}
+
 async fn perform_model_fetch_once_with_state<S>(
     state: &S,
 ) -> Result<ModelFetchRunSummary, GatewayError>
+where
+    S: ModelFetchRuntimeState + ?Sized,
+{
+    let targets = collect_fetch_targets(state, None, None).await?;
+    execute_fetch_targets(state, targets).await
+}
+
+async fn perform_model_fetch_for_key_with_state<S>(
+    state: &S,
+    provider_id: &str,
+    key_id: &str,
+) -> Result<ModelFetchRunSummary, GatewayError>
+where
+    S: ModelFetchRuntimeState + ?Sized,
+{
+    let targets = collect_fetch_targets(state, Some(provider_id), Some(key_id)).await?;
+    execute_fetch_targets(state, targets).await
+}
+
+async fn collect_fetch_targets<S>(
+    state: &S,
+    provider_id_filter: Option<&str>,
+    key_id_filter: Option<&str>,
+) -> Result<Vec<SelectedFetchTarget>, GatewayError>
 where
     S: ModelFetchRuntimeState + ?Sized,
 {
     if !state.has_provider_catalog_data_reader() || !state.has_provider_catalog_data_writer() {
-        return Ok(ModelFetchRunSummary {
+        return Ok(Vec::new());
-            attempted: 0,
-            succeeded: 0,
-            failed: 0,
-            skipped: 0,
-        });
     }
 
-    let providers = state.list_provider_catalog_providers(true).await?;
+    let providers = state
+        .list_provider_catalog_providers(true)
+        .await?
+        .into_iter()
+        .filter(|provider| provider_id_filter.is_none_or(|provider_id| provider.id == provider_id))
+        .collect::<Vec<_>>();
     if providers.is_empty() {
-        return Ok(ModelFetchRunSummary {
+        return Ok(Vec::new());
-            attempted: 0,
-            succeeded: 0,
-            failed: 0,
-            skipped: 0,
-        });
     }
 
     let provider_ids = providers
@@ -125,6 +152,9 @@ where
             .unwrap_or_default();
         let keys = keys_by_provider.remove(&provider.id).unwrap_or_default();
         for key in keys {
+            if key_id_filter.is_some_and(|key_id| key.id != key_id) {
+                continue;
+            }
             if !key.is_active || !key.auto_fetch_models {
                 continue;
             }
@@ -136,7 +166,16 @@ where
             });
         }
     }
+    Ok(targets)
+}
 
+async fn execute_fetch_targets<S>(
+    state: &S,
+    targets: Vec<SelectedFetchTarget>,
+) -> Result<ModelFetchRunSummary, GatewayError>
+where
+    S: ModelFetchRuntimeState + ?Sized,
+{
     let mut summary = ModelFetchRunSummary {
         attempted: targets.len(),
         succeeded: 0,

apps/aether-gateway/src/tests/control/admin/endpoints/keys.rs

@@ -1,5 +1,6 @@
 use std::sync::{Arc, Mutex};
 
+use aether_contracts::ExecutionPlan;
 use aether_crypto::{
     decrypt_python_fernet_ciphertext, encrypt_python_fernet_plaintext, DEVELOPMENT_ENCRYPTION_KEY,
 };
@@ -7,12 +8,13 @@ use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadReposi
 use aether_data_contracts::repository::provider_catalog::ProviderCatalogReadRepository;
 use axum::body::Body;
 use axum::routing::any;
-use axum::{extract::Request, Router};
+use axum::{extract::Request, Json, Router};
 use http::StatusCode;
 use serde_json::json;
 
 use super::super::super::{
-    build_router_with_state, sample_endpoint, sample_key, sample_provider, start_server, AppState,
+    build_router_with_state, build_state_with_execution_runtime_override, sample_endpoint,
+    sample_key, sample_provider, start_server, AppState,
 };
 use crate::constants::{
     GATEWAY_HEADER, TRUSTED_ADMIN_SESSION_ID_HEADER, TRUSTED_ADMIN_USER_ID_HEADER,
@@ -650,6 +652,301 @@ async fn gateway_updates_admin_provider_key_locally_with_trusted_admin_principal
     upstream_handle.abort();
 }
 
+#[tokio::test]
+async fn gateway_clears_allowed_models_when_disabling_auto_fetch_on_provider_key_update() {
+    let upstream_hits = Arc::new(Mutex::new(0usize));
+    let upstream_hits_clone = Arc::clone(&upstream_hits);
+    let upstream = Router::new().route(
+        "/api/admin/endpoints/keys/key-openai-a",
+        any(move |_request: Request| {
+            let upstream_hits_inner = Arc::clone(&upstream_hits_clone);
+            async move {
+                *upstream_hits_inner.lock().expect("mutex should lock") += 1;
+                (StatusCode::OK, Body::from("unexpected upstream hit"))
+            }
+        }),
+    );
+
+    let mut key = sample_key(
+        "key-openai-a",
+        "provider-openai",
+        "openai:chat",
+        "sk-test-a",
+    );
+    key.auto_fetch_models = true;
+    key.allowed_models = Some(json!(["gpt-5", "gpt-4.1-mini"]));
+
+    let provider_catalog_repository = Arc::new(InMemoryProviderCatalogReadRepository::seed(
+        vec![sample_provider("provider-openai", "openai", 10)],
+        vec![],
+        vec![key],
+    ));
+
+    let (_upstream_url, upstream_handle) = start_server(upstream).await;
+    let gateway = build_router_with_state(
+        AppState::new()
+            .expect("gateway should build")
+            .with_data_state_for_tests(
+                GatewayDataState::with_provider_catalog_repository_for_tests(
+                    provider_catalog_repository.clone(),
+                )
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = reqwest::Client::new()
+        .put(format!(
+            "{gateway_url}/api/admin/endpoints/keys/key-openai-a"
+        ))
+        .header(crate::constants::GATEWAY_HEADER, "rust-phase3b")
+        .header(TRUSTED_ADMIN_USER_ID_HEADER, "admin-user-123")
+        .header(TRUSTED_ADMIN_USER_ROLE_HEADER, "admin")
+        .header(TRUSTED_ADMIN_SESSION_ID_HEADER, "session-123")
+        .json(&json!({
+            "auto_fetch_models": false
+        }))
+        .send()
+        .await
+        .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload["auto_fetch_models"], false);
+    assert_eq!(payload["allowed_models"], json!([]));
+    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);
+
+    let reloaded = provider_catalog_repository
+        .list_keys_by_ids(&["key-openai-a".to_string()])
+        .await
+        .expect("keys should read");
+    assert_eq!(reloaded.len(), 1);
+    assert!(!reloaded[0].auto_fetch_models);
+    assert_eq!(reloaded[0].allowed_models, None);
+
+    gateway_handle.abort();
+    upstream_handle.abort();
+}
+
+#[tokio::test]
+async fn gateway_overwrites_allowed_models_immediately_when_enabling_auto_fetch() {
+    let execution_runtime_hits = Arc::new(Mutex::new(0usize));
+    let execution_runtime_hits_clone = Arc::clone(&execution_runtime_hits);
+    let execution_runtime = Router::new().route(
+        "/v1/execute/sync",
+        any(move |Json(plan): Json<ExecutionPlan>| {
+            let execution_runtime_hits_inner = Arc::clone(&execution_runtime_hits_clone);
+            async move {
+                *execution_runtime_hits_inner
+                    .lock()
+                    .expect("mutex should lock") += 1;
+                assert_eq!(plan.url, "https://api.openai.example/v1/models");
+                assert_eq!(
+                    plan.headers.get("authorization").map(String::as_str),
+                    Some("Bearer sk-test-a")
+                );
+                Json(json!({
+                    "request_id": "req-update-key-auto-fetch",
+                    "status_code": 200,
+                    "headers": {
+                        "content-type": "application/json"
+                    },
+                    "body": {
+                        "json_body": {
+                            "data": [
+                                {"id": "gpt-5"},
+                                {"id": "gpt-4.1"},
+                                {"id": "gpt-o1"}
+                            ]
+                        }
+                    }
+                }))
+            }
+        }),
+    );
+    let (execution_runtime_url, execution_runtime_handle) = start_server(execution_runtime).await;
+
+    let mut key = sample_key(
+        "key-openai-a",
+        "provider-openai",
+        "openai:chat",
+        "sk-test-a",
+    );
+    key.auto_fetch_models = false;
+    key.allowed_models = Some(json!(["manual-a", "manual-b"]));
+
+    let provider_catalog_repository = Arc::new(InMemoryProviderCatalogReadRepository::seed(
+        vec![sample_provider("provider-openai", "openai", 10)],
+        vec![sample_endpoint(
+            "endpoint-openai-chat",
+            "provider-openai",
+            "openai:chat",
+            "https://api.openai.example",
+        )],
+        vec![key],
+    ));
+
+    let gateway = build_router_with_state(
+        build_state_with_execution_runtime_override(execution_runtime_url)
+            .with_data_state_for_tests(
+                GatewayDataState::with_provider_catalog_repository_for_tests(
+                    provider_catalog_repository.clone(),
+                )
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = reqwest::Client::new()
+        .put(format!(
+            "{gateway_url}/api/admin/endpoints/keys/key-openai-a"
+        ))
+        .header(crate::constants::GATEWAY_HEADER, "rust-phase3b")
+        .header(TRUSTED_ADMIN_USER_ID_HEADER, "admin-user-123")
+        .header(TRUSTED_ADMIN_USER_ROLE_HEADER, "admin")
+        .header(TRUSTED_ADMIN_SESSION_ID_HEADER, "session-123")
+        .json(&json!({
+            "auto_fetch_models": true
+        }))
+        .send()
+        .await
+        .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload["auto_fetch_models"], true);
+    assert_eq!(
+        payload["allowed_models"],
+        json!(["gpt-4.1", "gpt-5", "gpt-o1"])
+    );
+    assert_eq!(payload["last_models_fetch_error"], serde_json::Value::Null);
+    assert_eq!(
+        *execution_runtime_hits.lock().expect("mutex should lock"),
+        1
+    );
+
+    let reloaded = provider_catalog_repository
+        .list_keys_by_ids(&["key-openai-a".to_string()])
+        .await
+        .expect("keys should read");
+    assert_eq!(reloaded.len(), 1);
+    assert!(reloaded[0].auto_fetch_models);
+    assert_eq!(
+        reloaded[0].allowed_models,
+        Some(json!(["gpt-4.1", "gpt-5", "gpt-o1"]))
+    );
+    assert_eq!(reloaded[0].locked_models, None);
+
+    gateway_handle.abort();
+    execution_runtime_handle.abort();
+}
+
+#[tokio::test]
+async fn gateway_fetches_allowed_models_immediately_when_enabling_auto_fetch_from_empty_state() {
+    let execution_runtime_hits = Arc::new(Mutex::new(0usize));
+    let execution_runtime_hits_clone = Arc::clone(&execution_runtime_hits);
+    let execution_runtime = Router::new().route(
+        "/v1/execute/sync",
+        any(move |Json(plan): Json<ExecutionPlan>| {
+            let execution_runtime_hits_inner = Arc::clone(&execution_runtime_hits_clone);
+            async move {
+                *execution_runtime_hits_inner
+                    .lock()
+                    .expect("mutex should lock") += 1;
+                assert_eq!(plan.url, "https://api.openai.example/v1/models");
+                Json(json!({
+                    "request_id": "req-update-key-auto-fetch-empty",
+                    "status_code": 200,
+                    "headers": {
+                        "content-type": "application/json"
+                    },
+                    "body": {
+                        "json_body": {
+                            "data": [
+                                {"id": "gpt-5-mini"},
+                                {"id": "gpt-4.1-nano"}
+                            ]
+                        }
+                    }
+                }))
+            }
+        }),
+    );
+    let (execution_runtime_url, execution_runtime_handle) = start_server(execution_runtime).await;
+
+    let mut key = sample_key(
+        "key-openai-a",
+        "provider-openai",
+        "openai:chat",
+        "sk-test-a",
+    );
+    key.auto_fetch_models = false;
+    key.allowed_models = None;
+
+    let provider_catalog_repository = Arc::new(InMemoryProviderCatalogReadRepository::seed(
+        vec![sample_provider("provider-openai", "openai", 10)],
+        vec![sample_endpoint(
+            "endpoint-openai-chat",
+            "provider-openai",
+            "openai:chat",
+            "https://api.openai.example",
+        )],
+        vec![key],
+    ));
+
+    let gateway = build_router_with_state(
+        build_state_with_execution_runtime_override(execution_runtime_url)
+            .with_data_state_for_tests(
+                GatewayDataState::with_provider_catalog_repository_for_tests(
+                    provider_catalog_repository.clone(),
+                )
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = reqwest::Client::new()
+        .put(format!(
+            "{gateway_url}/api/admin/endpoints/keys/key-openai-a"
+        ))
+        .header(crate::constants::GATEWAY_HEADER, "rust-phase3b")
+        .header(TRUSTED_ADMIN_USER_ID_HEADER, "admin-user-123")
+        .header(TRUSTED_ADMIN_USER_ROLE_HEADER, "admin")
+        .header(TRUSTED_ADMIN_SESSION_ID_HEADER, "session-123")
+        .json(&json!({
+            "auto_fetch_models": true
+        }))
+        .send()
+        .await
+        .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload["auto_fetch_models"], true);
+    assert_eq!(
+        payload["allowed_models"],
+        json!(["gpt-4.1-nano", "gpt-5-mini"])
+    );
+    assert_eq!(
+        *execution_runtime_hits.lock().expect("mutex should lock"),
+        1
+    );
+
+    let reloaded = provider_catalog_repository
+        .list_keys_by_ids(&["key-openai-a".to_string()])
+        .await
+        .expect("keys should read");
+    assert_eq!(reloaded.len(), 1);
+    assert!(reloaded[0].auto_fetch_models);
+    assert_eq!(
+        reloaded[0].allowed_models,
+        Some(json!(["gpt-4.1-nano", "gpt-5-mini"]))
+    );
+
+    gateway_handle.abort();
+    execution_runtime_handle.abort();
+}
+
 #[tokio::test]
 async fn gateway_rejects_admin_provider_key_update_when_api_key_duplicates_existing_key() {
     let upstream_hits = Arc::new(Mutex::new(0usize));

frontend/src/features/providers/components/KeyFormDialog.vue

@@ -276,7 +276,7 @@
               v-if="showAutoFetchWarning"
               class="text-xs text-amber-600 dark:text-amber-400"
             >
-              已配置的模型权限将在下次获取时被覆盖
+              {{ autoFetchWarningMessage }}
             </p>
           </div>
           <Switch v-model="form.auto_fetch_models" />
@@ -441,6 +441,15 @@ const showAutoFetchWarning = computed(() => {
   return true
 })
 
+const autoFetchWarningMessage = computed(() => {
+  if (!showAutoFetchWarning.value || !props.editingKey?.allowed_models) return ''
+  const models = Array.isArray(props.editingKey.allowed_models)
+    ? props.editingKey.allowed_models
+    : []
+  if (models.length === 0) return ''
+  return `当前 Key 模型权限存在以下模型：${models.map(model => `“${model}”`).join('、')}，开启自动获取后将被覆盖`
+})
+
 // 检查是否正在切换认证类型
 const switchingToVertexAI = computed(() =>
   !!props.editingKey &&
@@ -754,6 +763,7 @@ async function handleSave() {
     const authConfig = parseAuthConfig()
 
     if (props.editingKey) {
+      const shouldClearAllowedModels = !!props.editingKey.auto_fetch_models && !form.value.auto_fetch_models
       // 更新模式
       // 注意：rpm_limit 使用 null 表示自适应模式
       // undefined 表示"保持原值不变"（会在 JSON 序列化时被忽略）
@@ -769,6 +779,7 @@ async function handleSave() {
         note: form.value.note,
         is_active: form.value.is_active,
         capabilities: capabilitiesData,
+        allowed_models: shouldClearAllowedModels ? null : undefined,
         auto_fetch_models: form.value.auto_fetch_models,
         model_include_patterns: parsePatternText(form.value.model_include_patterns_text),
         model_exclude_patterns: parsePatternText(form.value.model_exclude_patterns_text)

frontend/src/features/providers/components/OAuthKeyEditDialog.vue

@@ -124,7 +124,7 @@
               v-if="showAutoFetchWarning"
               class="text-xs text-amber-600 dark:text-amber-400"
             >
-              已配置的模型权限将在下次获取时被覆盖
+              {{ autoFetchWarningMessage }}
             </p>
           </div>
           <Switch v-model="form.auto_fetch_models" />
@@ -220,6 +220,15 @@ const showAutoFetchWarning = computed(() => {
   return true
 })
 
+const autoFetchWarningMessage = computed(() => {
+  if (!showAutoFetchWarning.value || !props.editingKey?.allowed_models) return ''
+  const models = Array.isArray(props.editingKey.allowed_models)
+    ? props.editingKey.allowed_models
+    : []
+  if (models.length === 0) return ''
+  return `当前 Key 模型权限存在以下模型：${models.map(model => `“${model}”`).join('、')}，开启自动获取后将被覆盖`
+})
+
 // 表单是否可以保存
 const canSave = computed(() => {
   // 必须填写名称
@@ -345,6 +354,7 @@ async function handleSave() {
 
   saving.value = true
   try {
+    const shouldClearAllowedModels = !!props.editingKey.auto_fetch_models && !form.value.auto_fetch_models
     const updateData: EndpointAPIKeyUpdate = {
       name: form.value.name,
       internal_priority: form.value.internal_priority,
@@ -352,6 +362,7 @@ async function handleSave() {
       cache_ttl_minutes: form.value.cache_ttl_minutes,
       max_probe_interval_minutes: form.value.max_probe_interval_minutes,
       note: form.value.note,
+      allowed_models: shouldClearAllowedModels ? null : undefined,
       auto_fetch_models: form.value.auto_fetch_models,
       model_include_patterns: parsePatternText(form.value.model_include_patterns_text),
       model_exclude_patterns: parsePatternText(form.value.model_exclude_patterns_text)