refactor: 改进分布式任务锁的清理策略

实现两种锁清理模式：
- 单实例模式（默认）：启动时使用 Lua 脚本原子性清理旧锁，解决 worker 重启时���锁残留问题
- 多实例模式：使用 NX 选项竞争锁，依赖 TTL 处理异常退出

可通过 SINGLE_INSTANCE_MODE 环境变量控制模式选择。

Dockerfile.app

@@ -105,7 +105,7 @@ RUN printf '%s\n' \
 'stderr_logfile=/var/log/nginx/error.log' \
 '' \
 '[program:app]' \
-'command=gunicorn src.main:app -w %(ENV_GUNICORN_WORKERS)s -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:%(ENV_PORT)s --timeout 120 --access-logfile - --error-logfile - --log-level info' \
+'command=gunicorn src.main:app --preload -w %(ENV_GUNICORN_WORKERS)s -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:%(ENV_PORT)s --timeout 120 --access-logfile - --error-logfile - --log-level info' \
 'directory=/app' \
 'autostart=true' \
 'autorestart=true' \

Dockerfile.app.local

@@ -106,7 +106,7 @@ RUN printf '%s\n' \
 'stderr_logfile=/var/log/nginx/error.log' \
 '' \
 '[program:app]' \
-'command=gunicorn src.main:app -w %(ENV_GUNICORN_WORKERS)s -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:%(ENV_PORT)s --timeout 120 --access-logfile - --error-logfile - --log-level info' \
+'command=gunicorn src.main:app --preload -w %(ENV_GUNICORN_WORKERS)s -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:%(ENV_PORT)s --timeout 120 --access-logfile - --error-logfile - --log-level info' \
 'directory=/app' \
 'autostart=true' \
 'autorestart=true' \

alembic/versions/20251210_baseline.py

@@ -394,6 +394,10 @@ def upgrade() -> None:
             index=True,
         ),
     )
+    # usage 表复合索引（优化常见查询）
+    op.create_index("idx_usage_user_created", "usage", ["user_id", "created_at"])
+    op.create_index("idx_usage_apikey_created", "usage", ["api_key_id", "created_at"])
+    op.create_index("idx_usage_provider_model_created", "usage", ["provider", "model", "created_at"])
 
     # ==================== user_quotas ====================
     op.create_table(

alembic/versions/20251220_1500_add_usage_composite_indexes.py

@@ -18,33 +18,35 @@ depends_on = None
 def upgrade() -> None:
     """为 usage 表添加复合索引以优化常见查询
 
-    使用 CONCURRENTLY 创建索引以避免锁表，
-    但需要在 AUTOCOMMIT 模式下执行（不能在事务内）
+    注意：这些索引已经在 baseline 迁移中创建。
+    此迁移仅用于从旧版本升级的场景，新安装会跳过。
     """
     conn = op.get_bind()
-    engine = conn.engine
 
-    # 使用新连接并设置 AUTOCOMMIT 模式以支持 CREATE INDEX CONCURRENTLY
-    with engine.connect().execution_options(isolation_level="AUTOCOMMIT") as autocommit_conn:
-        # 使用 IF NOT EXISTS 避免重复创建，无需单独检查索引是否存在
-
-        # 1. user_id + created_at 复合索引 (用户用量查询)
-        autocommit_conn.execute(text(
-            "CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_usage_user_created "
-            "ON usage (user_id, created_at)"
+    # 检查 usage 表是否存在
+    result = conn.execute(text(
+        "SELECT EXISTS (SELECT FROM information_schema.tables WHERE table_name = 'usage')"
     ))
+    if not result.scalar():
+        # 表不存在，跳过
+        return
 
-        # 2. api_key_id + created_at 复合索引 (API Key 用量查询)
-        autocommit_conn.execute(text(
-            "CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_usage_apikey_created "
-            "ON usage (api_key_id, created_at)"
-        ))
+    # 定义需要创建的索引
+    indexes = [
+        ("idx_usage_user_created", "ON usage (user_id, created_at)"),
+        ("idx_usage_apikey_created", "ON usage (api_key_id, created_at)"),
+        ("idx_usage_provider_model_created", "ON usage (provider, model, created_at)"),
+    ]
 
-        # 3. provider + model + created_at 复合索引 (模型统计查询)
-        autocommit_conn.execute(text(
-            "CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_usage_provider_model_created "
-            "ON usage (provider, model, created_at)"
+    # 分别检查并创建每个索引
+    for index_name, index_def in indexes:
+        result = conn.execute(text(
+            f"SELECT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = '{index_name}')"
         ))
+        if result.scalar():
+            continue  # 索引已存在，跳过
+
+        conn.execute(text(f"CREATE INDEX {index_name} {index_def}"))
 
 
 def downgrade() -> None:

deploy.sh

@@ -26,10 +26,13 @@ calc_deps_hash() {
     cat pyproject.toml frontend/package.json frontend/package-lock.json Dockerfile.base.local 2>/dev/null | md5sum | cut -d' ' -f1
 }
 
-# 计算代码文件的哈希值
+# 计算代码文件的哈希值（包含 Dockerfile.app.local）
 calc_code_hash() {
-    find src -type f -name "*.py" 2>/dev/null | sort | xargs cat 2>/dev/null | md5sum | cut -d' ' -f1
-    find frontend/src -type f \( -name "*.vue" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) 2>/dev/null | sort | xargs cat 2>/dev/null | md5sum | cut -d' ' -f1
+    {
+        cat Dockerfile.app.local 2>/dev/null
+        find src -type f -name "*.py" 2>/dev/null | sort | xargs cat 2>/dev/null
+        find frontend/src -type f \( -name "*.vue" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) 2>/dev/null | sort | xargs cat 2>/dev/null
+    } | md5sum | cut -d' ' -f1
 }
 
 # 计算迁移文件的哈希值

frontend/src/api/endpoints/providers.ts

@@ -58,3 +58,38 @@ export async function deleteProvider(providerId: string): Promise<{ message: str
   return response.data
 }
 
+/**
+ * 测试模型连接性
+ */
+export interface TestModelRequest {
+  provider_id: string
+  model_name: string
+  api_key_id?: string
+  message?: string
+  api_format?: string
+}
+
+export interface TestModelResponse {
+  success: boolean
+  error?: string
+  data?: {
+    response?: {
+      status_code?: number
+      error?: string | { message?: string }
+      choices?: Array<{ message?: { content?: string } }>
+    }
+    content_preview?: string
+  }
+  provider?: {
+    id: string
+    name: string
+    display_name: string
+  }
+  model?: string
+}
+
+export async function testModel(data: TestModelRequest): Promise<TestModelResponse> {
+  const response = await client.post('/api/admin/provider-query/test-model', data)
+  return response.data
+}
+

frontend/src/components/ui/dialog/Dialog.vue

@@ -163,7 +163,9 @@ const contentZIndex = computed(() => (props.zIndex || 60) + 10)
 useEscapeKey(() => {
   if (isOpen.value) {
     handleClose()
+    return true  // 阻止其他监听器（如父级抽屉的 ESC 监听器）
   }
+  return false
 }, {
   disableOnInput: true,
   once: false

frontend/src/composables/useClipboard.ts

@@ -4,11 +4,11 @@ import { log } from '@/utils/logger'
 export function useClipboard() {
   const { success, error: showError } = useToast()
 
-  async function copyToClipboard(text: string): Promise<boolean> {
+  async function copyToClipboard(text: string, showToast = true): Promise<boolean> {
     try {
       if (navigator.clipboard && window.isSecureContext) {
         await navigator.clipboard.writeText(text)
-        success('已复制到剪贴板')
+        if (showToast) success('已复制到剪贴板')
         return true
       }
 
@@ -25,17 +25,17 @@ export function useClipboard() {
       try {
         const successful = document.execCommand('copy')
         if (successful) {
-          success('已复制到剪贴板')
+          if (showToast) success('已复制到剪贴板')
           return true
         }
-        showError('复制失败，请手动复制')
+        if (showToast) showError('复制失败，请手动复制')
         return false
       } finally {
         document.body.removeChild(textArea)
       }
     } catch (err) {
       log.error('复制失败:', err)
-      showError('复制失败，请手动选择文本进行复制')
+      if (showToast) showError('复制失败，请手动选择文本进行复制')
       return false
     }
   }

frontend/src/composables/useConfirm.ts

@@ -47,11 +47,11 @@ export function useConfirm() {
   /**
    * 便捷方法：危险操作确认（红色主题）
    */
-  const confirmDanger = (message: string, title?: string): Promise<boolean> => {
+  const confirmDanger = (message: string, title?: string, confirmText?: string): Promise<boolean> => {
     return confirm({
       message,
       title: title || '危险操作',
-      confirmText: '删除',
+      confirmText: confirmText || '删除',
       variant: 'danger'
     })
   }

frontend/src/composables/useEscapeKey.ts

@@ -4,11 +4,11 @@ import { onMounted, onUnmounted, ref } from 'vue'
  * ESC 键监听 Composable（简化版本，直接使用独立监听器）
  * 用于按 ESC 键关闭弹窗或其他可关闭的组件
  *
- * @param callback - 按 ESC 键时执行的回调函数
+ * @param callback - 按 ESC 键时执行的回调函数，返回 true 表示已处理事件，阻止其他监听器执行
  * @param options - 配置选项
  */
 export function useEscapeKey(
-  callback: () => void,
+  callback: () => void | boolean,
   options: {
     /** 是否在输入框获得焦点时禁用 ESC 键，默认 true */
     disableOnInput?: boolean
@@ -42,8 +42,11 @@ export function useEscapeKey(
       if (isInputElement) return
     }
 
-    // 执行回调
-    callback()
+    // 执行回调，如果返回 true 则阻止其他监听器
+    const handled = callback()
+    if (handled === true) {
+      event.stopImmediatePropagation()
+    }
 
     // 移除当前元素的焦点，避免残留样式
     if (document.activeElement instanceof HTMLElement) {

frontend/src/features/models/components/ModelDetailDrawer.vue

@@ -700,6 +700,7 @@ import {
 } from 'lucide-vue-next'
 import { useEscapeKey } from '@/composables/useEscapeKey'
 import { useToast } from '@/composables/useToast'
+import { useClipboard } from '@/composables/useClipboard'
 import Card from '@/components/ui/card.vue'
 import Badge from '@/components/ui/badge.vue'
 import Button from '@/components/ui/button.vue'
@@ -731,6 +732,7 @@ const emit = defineEmits<{
   'refreshProviders': []
 }>()
 const { success: showSuccess, error: showError } = useToast()
+const { copyToClipboard } = useClipboard()
 
 interface Props {
   model: GlobalModelResponse | null
@@ -763,16 +765,6 @@ function handleClose() {
   }
 }
 
-// 复制到剪贴板
-async function copyToClipboard(text: string) {
-  try {
-    await navigator.clipboard.writeText(text)
-    showSuccess('已复制')
-  } catch {
-    showError('复制失败')
-  }
-}
-
 // 格式化日期
 function formatDate(dateStr: string): string {
   if (!dateStr) return '-'

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

@@ -433,11 +433,17 @@ const availableGlobalModels = computed(() => {
   )
 })
 
-// 计算可添加的上游模型（排除已关联的）
+// 计算可添加的上游模型（排除已关联的，包括主模型名和映射名称）
 const availableUpstreamModelsBase = computed(() => {
-  const existingModelNames = new Set(
-    existingModels.value.map(m => m.provider_model_name)
-  )
+  const existingModelNames = new Set<string>()
+  for (const m of existingModels.value) {
+    // 主模型名
+    existingModelNames.add(m.provider_model_name)
+    // 映射名称
+    for (const mapping of m.provider_model_mappings ?? []) {
+      if (mapping.name) existingModelNames.add(mapping.name)
+    }
+  }
   return upstreamModels.value.filter(m => !existingModelNames.has(m.id))
 })
 

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

@@ -17,7 +17,7 @@
             v-model:open="modelSelectOpen"
             :model-value="formData.modelId"
             :disabled="!!editingGroup"
-            @update:model-value="formData.modelId = $event"
+            @update:model-value="handleModelChange"
           >
             <SelectTrigger class="h-9">
               <SelectValue placeholder="请选择模型" />
@@ -449,7 +449,17 @@ interface UpstreamModelGroup {
 }
 
 const groupedAvailableUpstreamModels = computed<UpstreamModelGroup[]>(() => {
+  // 收集当前表单已添加的名称
   const addedNames = new Set(formData.value.aliases.map(a => a.name.trim()))
+
+  // 收集所有已存在的映射名称（包括主模型名和映射名称）
+  for (const m of props.models) {
+    addedNames.add(m.provider_model_name)
+    for (const mapping of m.provider_model_mappings ?? []) {
+      if (mapping.name) addedNames.add(mapping.name)
+    }
+  }
+
   const availableModels = filteredUpstreamModels.value.filter(m => !addedNames.has(m.id))
 
   const groups = new Map<string, UpstreamModelGroup>()
@@ -519,6 +529,15 @@ function initForm() {
   }
 }
 
+// 处理模型选择变更
+function handleModelChange(value: string) {
+  formData.value.modelId = value
+  const selectedModel = props.models.find(m => m.id === value)
+  if (selectedModel) {
+    upstreamModelSearch.value = selectedModel.provider_model_name
+  }
+}
+
 // 切换 API 格式
 function toggleApiFormat(format: string) {
   const index = formData.value.apiFormats.indexOf(format)

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

@@ -531,6 +531,7 @@
               <!-- 模型名称映射 -->
               <ModelAliasesTab
                 v-if="provider"
+                ref="modelAliasesTabRef"
                 :key="`aliases-${provider.id}`"
                 :provider="provider"
                 @refresh="handleRelatedDataRefresh"
@@ -660,6 +661,7 @@ import Button from '@/components/ui/button.vue'
 import Badge from '@/components/ui/badge.vue'
 import Card from '@/components/ui/card.vue'
 import { useToast } from '@/composables/useToast'
+import { useClipboard } from '@/composables/useClipboard'
 import { getProvider, getProviderEndpoints } from '@/api/endpoints'
 import {
   KeyFormDialog,
@@ -705,6 +707,7 @@ const emit = defineEmits<{
 }>()
 
 const { error: showError, success: showSuccess } = useToast()
+const { copyToClipboard } = useClipboard()
 
 const loading = ref(false)
 const provider = ref<any>(null)
@@ -735,6 +738,9 @@ const deleteModelConfirmOpen = ref(false)
 const modelToDelete = ref<Model | null>(null)
 const batchAssignDialogOpen = ref(false)
 
+// ModelAliasesTab 组件引用
+const modelAliasesTabRef = ref<InstanceType<typeof ModelAliasesTab> | null>(null)
+
 // 拖动排序相关状态
 const dragState = ref({
   isDragging: false,
@@ -756,7 +762,9 @@ const hasBlockingDialogOpen = computed(() =>
   deleteKeyConfirmOpen.value ||
   modelFormDialogOpen.value ||
   deleteModelConfirmOpen.value ||
-  batchAssignDialogOpen.value
+  batchAssignDialogOpen.value ||
+  // 检测 ModelAliasesTab 子组件的 Dialog 是否打开
+  modelAliasesTabRef.value?.dialogOpen
 )
 
 // 监听 providerId 变化
@@ -1244,16 +1252,6 @@ function getHealthScoreBarColor(score: number): string {
   return 'bg-red-500 dark:bg-red-400'
 }
 
-// 复制到剪贴板
-async function copyToClipboard(text: string) {
-  try {
-    await navigator.clipboard.writeText(text)
-    showSuccess('已复制到剪贴板')
-  } catch {
-    showError('复制失败', '错误')
-  }
-}
-
 // 加载 Provider 信息
 async function loadProvider() {
   if (!props.providerId) return

frontend/src/features/providers/components/provider-tabs/ModelAliasesTab.vue

@@ -110,8 +110,9 @@
             <div
               v-for="mapping in group.aliases"
               :key="mapping.name"
-              class="flex items-center gap-2 py-1"
+              class="flex items-center justify-between gap-2 py-1"
             >
+              <div class="flex items-center gap-2 flex-1 min-w-0">
                 <!-- 优先级标签 -->
                 <span class="inline-flex items-center justify-center w-5 h-5 rounded bg-background border text-xs font-medium shrink-0">
                   {{ mapping.priority }}
@@ -121,6 +122,19 @@
                   {{ mapping.name }}
                 </span>
               </div>
+              <!-- 测试按钮 -->
+              <Button
+                variant="ghost"
+                size="icon"
+                class="h-7 w-7 shrink-0"
+                title="测试映射"
+                :disabled="testingMapping === `${group.model.id}-${group.apiFormatsKey}-${mapping.name}`"
+                @click="testMapping(group, mapping)"
+              >
+                <Loader2 v-if="testingMapping === `${group.model.id}-${group.apiFormatsKey}-${mapping.name}`" class="w-3 h-3 animate-spin" />
+                <Play v-else class="w-3 h-3" />
+              </Button>
+            </div>
           </div>
         </div>
       </div>
@@ -166,18 +180,20 @@
 
 <script setup lang="ts">
 import { ref, computed, onMounted, watch } from 'vue'
-import { Tag, Plus, Edit, Trash2, ChevronRight } from 'lucide-vue-next'
+import { Tag, Plus, Edit, Trash2, ChevronRight, Loader2, Play } from 'lucide-vue-next'
 import { Card, Button, Badge } from '@/components/ui'
 import AlertDialog from '@/components/common/AlertDialog.vue'
 import ModelMappingDialog, { type AliasGroup } from '../ModelMappingDialog.vue'
 import { useToast } from '@/composables/useToast'
 import {
   getProviderModels,
+  testModel,
   API_FORMAT_LABELS,
   type Model,
   type ProviderModelAlias
 } from '@/api/endpoints'
 import { updateModel } from '@/api/endpoints/models'
+import { parseTestModelError } from '@/utils/errorParser'
 
 const props = defineProps<{
   provider: any
@@ -196,6 +212,7 @@ const dialogOpen = ref(false)
 const deleteConfirmOpen = ref(false)
 const editingGroup = ref<AliasGroup | null>(null)
 const deletingGroup = ref<AliasGroup | null>(null)
+const testingMapping = ref<string | null>(null)
 
 // 列表展开状态
 const expandedAliasGroups = ref<Set<string>>(new Set())
@@ -337,6 +354,49 @@ async function onDialogSaved() {
   emit('refresh')
 }
 
+// 测试模型映射
+async function testMapping(group: any, mapping: any) {
+  const testingKey = `${group.model.id}-${group.apiFormatsKey}-${mapping.name}`
+  testingMapping.value = testingKey
+
+  try {
+    // 根据分组的 API 格式来确定应该使用的格式
+    let apiFormat = null
+    if (group.apiFormats.length === 1) {
+      apiFormat = group.apiFormats[0]
+    } else if (group.apiFormats.length === 0) {
+      // 如果没有指定格式，但分组显示为"全部"，则使用模型的默认格式
+      apiFormat = group.model.effective_api_format || group.model.api_format
+    }
+
+    const result = await testModel({
+      provider_id: props.provider.id,
+      model_name: mapping.name,  // 使用映射名称进行测试
+      message: "hello",
+      api_format: apiFormat
+    })
+
+    if (result.success) {
+      showSuccess(`映射 "${mapping.name}" 测试成功`)
+
+      // 如果有响应内容，可以显示更多信息
+      if (result.data?.response?.choices?.[0]?.message?.content) {
+        const content = result.data.response.choices[0].message.content
+        showSuccess(`测试成功，响应: ${content.substring(0, 100)}${content.length > 100 ? '...' : ''}`)
+      } else if (result.data?.content_preview) {
+        showSuccess(`流式测试成功，预览: ${result.data.content_preview}`)
+      }
+    } else {
+      showError(`映射测试失败: ${parseTestModelError(result)}`)
+    }
+  } catch (err: any) {
+    const errorMsg = err.response?.data?.detail || err.message || '测试请求失败'
+    showError(`映射测试失败: ${errorMsg}`)
+  } finally {
+    testingMapping.value = null
+  }
+}
+
 // 监听 provider 变化
 watch(() => props.provider?.id, (newId) => {
   if (newId) {
@@ -349,4 +409,9 @@ onMounted(() => {
     loadModels()
   }
 })
+
+// 暴露给父组件，用于检测是否有弹窗打开
+defineExpose({
+  dialogOpen: computed(() => dialogOpen.value || deleteConfirmOpen.value)
+})
 </script>

frontend/src/features/providers/components/provider-tabs/ModelsTab.vue

@@ -156,6 +156,17 @@
             </td>
             <td class="align-top px-4 py-3">
               <div class="flex justify-center gap-1.5">
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  class="h-8 w-8"
+                  title="测试模型"
+                  :disabled="testingModelId === model.id"
+                  @click="testModelConnection(model)"
+                >
+                  <Loader2 v-if="testingModelId === model.id" class="w-3.5 h-3.5 animate-spin" />
+                  <Play v-else class="w-3.5 h-3.5" />
+                </Button>
                 <Button
                   variant="ghost"
                   size="icon"
@@ -209,12 +220,14 @@
 
 <script setup lang="ts">
 import { ref, computed, onMounted } from 'vue'
-import { Box, Edit, Trash2, Layers, Eye, Wrench, Zap, Brain, Power, Copy, Image } from 'lucide-vue-next'
+import { Box, Edit, Trash2, Layers, Eye, Wrench, Zap, Brain, Power, Copy, Image, Loader2, Play } from 'lucide-vue-next'
 import Card from '@/components/ui/card.vue'
 import Button from '@/components/ui/button.vue'
 import { useToast } from '@/composables/useToast'
-import { getProviderModels, type Model } from '@/api/endpoints'
+import { useClipboard } from '@/composables/useClipboard'
+import { getProviderModels, testModel, type Model } from '@/api/endpoints'
 import { updateModel } from '@/api/endpoints/models'
+import { parseTestModelError } from '@/utils/errorParser'
 
 const props = defineProps<{
   provider: any
@@ -227,11 +240,13 @@ const emit = defineEmits<{
 }>()
 
 const { error: showError, success: showSuccess } = useToast()
+const { copyToClipboard } = useClipboard()
 
 // 状态
 const loading = ref(false)
 const models = ref<Model[]>([])
 const togglingModelId = ref<string | null>(null)
+const testingModelId = ref<string | null>(null)
 
 // 按名称排序的模型列表
 const sortedModels = computed(() => {
@@ -244,12 +259,7 @@ const sortedModels = computed(() => {
 
 // 复制模型 ID 到剪贴板
 async function copyModelId(modelId: string) {
-  try {
-    await navigator.clipboard.writeText(modelId)
-    showSuccess('已复制到剪贴板')
-  } catch {
-    showError('复制失败', '错误')
-  }
+  await copyToClipboard(modelId)
 }
 
 // 加载模型
@@ -380,6 +390,39 @@ async function toggleModelActive(model: Model) {
   }
 }
 
+// 测试模型连接性
+async function testModelConnection(model: Model) {
+  if (testingModelId.value) return
+
+  testingModelId.value = model.id
+  try {
+    const result = await testModel({
+      provider_id: props.provider.id,
+      model_name: model.provider_model_name,
+      message: "hello"
+    })
+
+    if (result.success) {
+      showSuccess(`模型 "${model.provider_model_name}" 测试成功`)
+
+      // 如果有响应内容，可以显示更多信息
+      if (result.data?.response?.choices?.[0]?.message?.content) {
+        const content = result.data.response.choices[0].message.content
+        showSuccess(`测试成功，响应: ${content.substring(0, 100)}${content.length > 100 ? '...' : ''}`)
+      } else if (result.data?.content_preview) {
+        showSuccess(`流式测试成功，预览: ${result.data.content_preview}`)
+      }
+    } else {
+      showError(`模型测试失败: ${parseTestModelError(result)}`)
+    }
+  } catch (err: any) {
+    const errorMsg = err.response?.data?.detail || err.message || '测试请求失败'
+    showError(`模型测试失败: ${errorMsg}`)
+  } finally {
+    testingModelId.value = null
+  }
+}
+
 onMounted(() => {
   loadModels()
 })

frontend/src/features/usage/components/RequestDetailDrawer.vue

@@ -473,6 +473,7 @@
 import { ref, watch, computed } from 'vue'
 import Button from '@/components/ui/button.vue'
 import { useEscapeKey } from '@/composables/useEscapeKey'
+import { useClipboard } from '@/composables/useClipboard'
 import Card from '@/components/ui/card.vue'
 import Badge from '@/components/ui/badge.vue'
 import Separator from '@/components/ui/separator.vue'
@@ -505,6 +506,7 @@ const copiedStates = ref<Record<string, boolean>>({})
 const viewMode = ref<'compare' | 'formatted' | 'raw'>('compare')
 const currentExpandDepth = ref(1)
 const dataSource = ref<'client' | 'provider'>('client')
+const { copyToClipboard } = useClipboard()
 const historicalPricing = ref<{
   input_price: string
   output_price: string
@@ -784,7 +786,7 @@ function copyJsonToClipboard(tabName: string) {
   }
 
   if (data) {
-    navigator.clipboard.writeText(JSON.stringify(data, null, 2))
+    copyToClipboard(JSON.stringify(data, null, 2), false)
     copiedStates.value[tabName] = true
     setTimeout(() => {
       copiedStates.value[tabName] = false

frontend/src/features/users/components/UserFormDialog.vue

@@ -86,6 +86,34 @@
             </p>
           </div>
 
+          <div
+            v-if="isEditMode && form.password.length > 0"
+            class="space-y-2"
+          >
+            <Label class="text-sm font-medium">
+              确认新密码 <span class="text-muted-foreground">*</span>
+            </Label>
+            <Input
+              :id="`pwd-confirm-${formNonce}`"
+              v-model="form.confirmPassword"
+              type="password"
+              autocomplete="new-password"
+              data-form-type="other"
+              data-lpignore="true"
+              :name="`confirm-${formNonce}`"
+              required
+              minlength="6"
+              placeholder="再次输入新密码"
+              class="h-10"
+            />
+            <p
+              v-if="form.confirmPassword.length > 0 && form.password !== form.confirmPassword"
+              class="text-xs text-destructive"
+            >
+              两次输入的密码不一致
+            </p>
+          </div>
+
           <div class="space-y-2">
             <Label
               for="form-email"
@@ -423,6 +451,7 @@ const apiFormats = ref<Array<{ value: string; label: string }>>([])
 const form = ref({
   username: '',
   password: '',
+  confirmPassword: '',
   email: '',
   quota: 10,
   role: 'user' as 'admin' | 'user',
@@ -443,6 +472,7 @@ function resetForm() {
   form.value = {
     username: '',
     password: '',
+    confirmPassword: '',
     email: '',
     quota: 10,
     role: 'user',
@@ -461,6 +491,7 @@ function loadUserData() {
   form.value = {
     username: props.user.username,
     password: '',
+    confirmPassword: '',
     email: props.user.email || '',
     quota: props.user.quota_usd == null ? 10 : props.user.quota_usd,
     role: props.user.role,
@@ -486,7 +517,9 @@ const isFormValid = computed(() => {
   const hasUsername = form.value.username.trim().length > 0
   const hasEmail = form.value.email.trim().length > 0
   const hasPassword = isEditMode.value || form.value.password.length >= 6
-  return hasUsername && hasEmail && hasPassword
+  // 编辑模式下如果填写了密码，必须确认密码一致
+  const passwordConfirmed = !isEditMode.value || form.value.password.length === 0 || form.value.password === form.value.confirmPassword
+  return hasUsername && hasEmail && hasPassword && passwordConfirmed
 })
 
 // 加载访问控制选项

frontend/src/stores/users.ts

@@ -14,7 +14,7 @@ export const useUsersStore = defineStore('users', () => {
     try {
       users.value = await usersApi.getAllUsers()
     } catch (err: any) {
-      error.value = err.response?.data?.detail || '获取用户列表失败'
+      error.value = err.response?.data?.error?.message || err.response?.data?.detail || '获取用户列表失败'
     } finally {
       loading.value = false
     }
@@ -29,7 +29,7 @@ export const useUsersStore = defineStore('users', () => {
       users.value.push(newUser)
       return newUser
     } catch (err: any) {
-      error.value = err.response?.data?.detail || '创建用户失败'
+      error.value = err.response?.data?.error?.message || err.response?.data?.detail || '创建用户失败'
       throw err
     } finally {
       loading.value = false
@@ -52,7 +52,7 @@ export const useUsersStore = defineStore('users', () => {
       }
       return updatedUser
     } catch (err: any) {
-      error.value = err.response?.data?.detail || '更新用户失败'
+      error.value = err.response?.data?.error?.message || err.response?.data?.detail || '更新用户失败'
       throw err
     } finally {
       loading.value = false
@@ -67,7 +67,7 @@ export const useUsersStore = defineStore('users', () => {
       await usersApi.deleteUser(userId)
       users.value = users.value.filter(u => u.id !== userId)
     } catch (err: any) {
-      error.value = err.response?.data?.detail || '删除用户失败'
+      error.value = err.response?.data?.error?.message || err.response?.data?.detail || '删除用户失败'
       throw err
     } finally {
       loading.value = false
@@ -78,7 +78,7 @@ export const useUsersStore = defineStore('users', () => {
     try {
       return await usersApi.getUserApiKeys(userId)
     } catch (err: any) {
-      error.value = err.response?.data?.detail || '获取 API Keys 失败'
+      error.value = err.response?.data?.error?.message || err.response?.data?.detail || '获取 API Keys 失败'
       throw err
     }
   }
@@ -87,7 +87,7 @@ export const useUsersStore = defineStore('users', () => {
     try {
       return await usersApi.createApiKey(userId, name)
     } catch (err: any) {
-      error.value = err.response?.data?.detail || '创建 API Key 失败'
+      error.value = err.response?.data?.error?.message || err.response?.data?.detail || '创建 API Key 失败'
       throw err
     }
   }
@@ -96,7 +96,7 @@ export const useUsersStore = defineStore('users', () => {
     try {
       await usersApi.deleteApiKey(userId, keyId)
     } catch (err: any) {
-      error.value = err.response?.data?.detail || '删除 API Key 失败'
+      error.value = err.response?.data?.error?.message || err.response?.data?.detail || '删除 API Key 失败'
       throw err
     }
   }
@@ -110,7 +110,7 @@ export const useUsersStore = defineStore('users', () => {
       // 刷新用户列表以获取最新数据
       await fetchUsers()
     } catch (err: any) {
-      error.value = err.response?.data?.detail || '重置配额失败'
+      error.value = err.response?.data?.error?.message || err.response?.data?.detail || '重置配额失败'
       throw err
     } finally {
       loading.value = false

frontend/src/utils/errorParser.ts

@@ -198,3 +198,49 @@ export function parseApiErrorShort(err: unknown, defaultMessage: string = '操
   const lines = fullError.split('\n')
   return lines[0] || defaultMessage
 }
+
+/**
+ * 解析模型测试响应的错误信息
+ * @param result 测试响应结果
+ * @returns 格式化的错误信息
+ */
+export function parseTestModelError(result: {
+  error?: string
+  data?: {
+    response?: {
+      status_code?: number
+      error?: string | { message?: string }
+    }
+  }
+}): string {
+  let errorMsg = result.error || '测试失败'
+
+  // 检查HTTP状态码错误
+  if (result.data?.response?.status_code) {
+    const status = result.data.response.status_code
+    if (status === 403) {
+      errorMsg = '认证失败: API密钥无效或客户端类型不被允许'
+    } else if (status === 401) {
+      errorMsg = '认证失败: API密钥无效或已过期'
+    } else if (status === 404) {
+      errorMsg = '模型不存在: 请检查模型名称是否正确'
+    } else if (status === 429) {
+      errorMsg = '请求频率过高: 请稍后重试'
+    } else if (status >= 500) {
+      errorMsg = `服务器错误: HTTP ${status}`
+    } else {
+      errorMsg = `请求失败: HTTP ${status}`
+    }
+  }
+
+  // 尝试从错误响应中提取更多信息
+  if (result.data?.response?.error) {
+    if (typeof result.data.response.error === 'string') {
+      errorMsg = result.data.response.error
+    } else if (result.data.response.error?.message) {
+      errorMsg = result.data.response.error.message
+    }
+  }
+
+  return errorMsg
+}

frontend/src/views/admin/ApiKeys.vue

@@ -650,6 +650,7 @@
 import { ref, computed, onMounted } from 'vue'
 import { useToast } from '@/composables/useToast'
 import { useConfirm } from '@/composables/useConfirm'
+import { useClipboard } from '@/composables/useClipboard'
 import { adminApi, type AdminApiKey, type CreateStandaloneApiKeyRequest } from '@/api/admin'
 
 import {
@@ -693,6 +694,7 @@ import { log } from '@/utils/logger'
 
 const { success, error } = useToast()
 const { confirmDanger } = useConfirm()
+const { copyToClipboard } = useClipboard()
 
 const apiKeys = ref<AdminApiKey[]>([])
 const loading = ref(false)
@@ -927,20 +929,14 @@ function selectKey() {
 }
 
 async function copyKey() {
-  try {
-    await navigator.clipboard.writeText(newKeyValue.value)
-    success('API Key 已复制到剪贴板')
-  } catch {
-    error('复制失败，请手动复制')
-  }
+  await copyToClipboard(newKeyValue.value)
 }
 
 async function copyKeyPrefix(apiKey: AdminApiKey) {
   try {
     // 调用后端 API 获取完整密钥
     const response = await adminApi.getFullApiKey(apiKey.id)
-    await navigator.clipboard.writeText(response.key)
-    success('完整密钥已复制到剪贴板')
+    await copyToClipboard(response.key)
   } catch (err) {
     log.error('复制密钥失败:', err)
     error('复制失败，请重试')
@@ -1046,9 +1042,10 @@ async function handleKeyFormSubmit(data: StandaloneKeyFormData) {
         rate_limit: data.rate_limit,
         expire_days: data.never_expire ? null : (data.expire_days || null),
         auto_delete_on_expiry: data.auto_delete_on_expiry,
-        allowed_providers: data.allowed_providers.length > 0 ? data.allowed_providers : undefined,
-        allowed_api_formats: data.allowed_api_formats.length > 0 ? data.allowed_api_formats : undefined,
-        allowed_models: data.allowed_models.length > 0 ? data.allowed_models : undefined
+        // 空数组表示清除限制（允许全部），后端会将空数组存为 NULL
+        allowed_providers: data.allowed_providers,
+        allowed_api_formats: data.allowed_api_formats,
+        allowed_models: data.allowed_models
       }
       await adminApi.updateApiKey(data.id, updateData)
       success('API Key 更新成功')
@@ -1064,9 +1061,10 @@ async function handleKeyFormSubmit(data: StandaloneKeyFormData) {
         rate_limit: data.rate_limit,
         expire_days: data.never_expire ? null : (data.expire_days || null),
         auto_delete_on_expiry: data.auto_delete_on_expiry,
-        allowed_providers: data.allowed_providers.length > 0 ? data.allowed_providers : undefined,
-        allowed_api_formats: data.allowed_api_formats.length > 0 ? data.allowed_api_formats : undefined,
-        allowed_models: data.allowed_models.length > 0 ? data.allowed_models : undefined
+        // 空数组表示不设置限制（允许全部），后端会将空数组存为 NULL
+        allowed_providers: data.allowed_providers,
+        allowed_api_formats: data.allowed_api_formats,
+        allowed_models: data.allowed_models
       }
       const response = await adminApi.createStandaloneApiKey(createData)
       newKeyValue.value = response.key

frontend/src/views/admin/CacheMonitoring.vue

@@ -46,6 +46,7 @@ const clearingRowAffinityKey = ref<string | null>(null)
 const currentPage = ref(1)
 const pageSize = ref(20)
 const currentTime = ref(Math.floor(Date.now() / 1000))
+const analysisHoursSelectOpen = ref(false)
 
 // ==================== 模型映射缓存 ====================
 
@@ -1056,7 +1057,7 @@ onBeforeUnmount(() => {
             <span class="text-xs text-muted-foreground hidden sm:inline">分析用户请求间隔，推荐合适的缓存 TTL</span>
           </div>
           <div class="flex flex-wrap items-center gap-2">
-            <Select v-model="analysisHours">
+            <Select v-model="analysisHours" v-model:open="analysisHoursSelectOpen">
               <SelectTrigger class="w-24 sm:w-28 h-8">
                 <SelectValue placeholder="时间段" />
               </SelectTrigger>

frontend/src/views/admin/ModelManagement.vue

@@ -713,6 +713,7 @@ import ProviderModelFormDialog from '@/features/providers/components/ProviderMod
 import type { Model } from '@/api/endpoints'
 import { useToast } from '@/composables/useToast'
 import { useConfirm } from '@/composables/useConfirm'
+import { useClipboard } from '@/composables/useClipboard'
 import { useRowClick } from '@/composables/useRowClick'
 import { parseApiError } from '@/utils/errorParser'
 import {
@@ -743,6 +744,7 @@ import { getProvidersSummary } from '@/api/endpoints/providers'
 import { getAllCapabilities, type CapabilityDefinition } from '@/api/endpoints'
 
 const { success, error: showError } = useToast()
+const { copyToClipboard } = useClipboard()
 
 // 状态
 const loading = ref(false)
@@ -1066,16 +1068,6 @@ function handleRowClick(event: MouseEvent, model: GlobalModelResponse) {
   selectModel(model)
 }
 
-// 复制到剪贴板
-async function copyToClipboard(text: string) {
-  try {
-    await navigator.clipboard.writeText(text)
-    success('已复制')
-  } catch {
-    showError('复制失败')
-  }
-}
-
 async function selectModel(model: GlobalModelResponse) {
   selectedModel.value = model
   detailTab.value = 'basic'

frontend/src/views/admin/ProviderManagement.vue

@@ -723,9 +723,19 @@ async function handleDeleteProvider(provider: ProviderWithEndpointsSummary) {
 // 切换提供商状态
 async function toggleProviderStatus(provider: ProviderWithEndpointsSummary) {
   try {
-    await updateProvider(provider.id, { is_active: !provider.is_active })
-    provider.is_active = !provider.is_active
-    showSuccess(provider.is_active ? '提供商已启用' : '提供商已停用')
+    const newStatus = !provider.is_active
+    await updateProvider(provider.id, { is_active: newStatus })
+
+    // 更新抽屉内部的 provider 对象
+    provider.is_active = newStatus
+
+    // 同时更新主页面 providers 数组中的对象，实现无感更新
+    const targetProvider = providers.value.find(p => p.id === provider.id)
+    if (targetProvider) {
+      targetProvider.is_active = newStatus
+    }
+
+    showSuccess(newStatus ? '提供商已启用' : '提供商已停用')
   } catch (err: any) {
     showError(err.response?.data?.detail || '操作失败', '错误')
   }

frontend/src/views/admin/Users.vue

@@ -701,6 +701,7 @@ import { ref, computed, onMounted, watch } from 'vue'
 import { useUsersStore } from '@/stores/users'
 import { useToast } from '@/composables/useToast'
 import { useConfirm } from '@/composables/useConfirm'
+import { useClipboard } from '@/composables/useClipboard'
 import { usageApi, type UsageByUser } from '@/api/usage'
 import { adminApi } from '@/api/admin'
 
@@ -748,6 +749,7 @@ import { log } from '@/utils/logger'
 
 const { success, error } = useToast()
 const { confirmDanger, confirmWarning } = useConfirm()
+const { copyToClipboard } = useClipboard()
 const usersStore = useUsersStore()
 
 // 用户表单对话框状态
@@ -875,7 +877,8 @@ async function toggleUserStatus(user: any) {
   const action = user.is_active ? '禁用' : '启用'
   const confirmed = await confirmDanger(
     `确定要${action}用户 ${user.username} 吗？`,
-    `${action}用户`
+    `${action}用户`,
+    action
   )
 
   if (!confirmed) return
@@ -884,7 +887,7 @@ async function toggleUserStatus(user: any) {
     await usersStore.updateUser(user.id, { is_active: !user.is_active })
     success(`用户已${action}`)
   } catch (err: any) {
-    error(err.response?.data?.detail || '未知错误', `${action}用户失败`)
+    error(err.response?.data?.error?.message || err.response?.data?.detail || '未知错误', `${action}用户失败`)
   }
 }
 
@@ -955,7 +958,7 @@ async function handleUserFormSubmit(data: UserFormData & { password?: string })
     closeUserFormDialog()
   } catch (err: any) {
     const title = data.id ? '更新用户失败' : '创建用户失败'
-    error(err.response?.data?.detail || '未知错误', title)
+    error(err.response?.data?.error?.message || err.response?.data?.detail || '未知错误', title)
   } finally {
     userFormDialogRef.value?.setSaving(false)
   }
@@ -989,7 +992,7 @@ async function createApiKey() {
     showNewApiKeyDialog.value = true
     await loadUserApiKeys(selectedUser.value.id)
   } catch (err: any) {
-    error(err.response?.data?.detail || '未知错误', '创建 API Key 失败')
+    error(err.response?.data?.error?.message || err.response?.data?.detail || '未知错误', '创建 API Key 失败')
   } finally {
     creatingApiKey.value = false
   }
@@ -1000,12 +1003,7 @@ function selectApiKey() {
 }
 
 async function copyApiKey() {
-  try {
-    await navigator.clipboard.writeText(newApiKey.value)
-    success('API Key已复制到剪贴板')
-  } catch {
-    error('复制失败，请手动复制')
-  }
+  await copyToClipboard(newApiKey.value)
 }
 
 async function closeNewApiKeyDialog() {
@@ -1026,7 +1024,7 @@ async function deleteApiKey(apiKey: any) {
     await loadUserApiKeys(selectedUser.value.id)
     success('API Key已删除')
   } catch (err: any) {
-    error(err.response?.data?.detail || '未知错误', '删除 API Key 失败')
+    error(err.response?.data?.error?.message || err.response?.data?.detail || '未知错误', '删除 API Key 失败')
   }
 }
 
@@ -1034,11 +1032,10 @@ async function copyFullKey(apiKey: any) {
   try {
     // 调用后端 API 获取完整密钥
     const response = await adminApi.getFullApiKey(apiKey.id)
-    await navigator.clipboard.writeText(response.key)
-    success('完整密钥已复制到剪贴板')
+    await copyToClipboard(response.key)
   } catch (err: any) {
     log.error('复制密钥失败:', err)
-    error(err.response?.data?.detail || '未知错误', '复制密钥失败')
+    error(err.response?.data?.error?.message || err.response?.data?.detail || '未知错误', '复制密钥失败')
   }
 }
 
@@ -1054,7 +1051,7 @@ async function resetQuota(user: any) {
     await usersStore.resetUserQuota(user.id)
     success('配额已重置')
   } catch (err: any) {
-    error(err.response?.data?.detail || '未知错误', '重置配额失败')
+    error(err.response?.data?.error?.message || err.response?.data?.detail || '未知错误', '重置配额失败')
   }
 }
 
@@ -1070,7 +1067,7 @@ async function deleteUser(user: any) {
     await usersStore.deleteUser(user.id)
     success('用户已删除')
   } catch (err: any) {
-    error(err.response?.data?.detail || '未知错误', '删除用户失败')
+    error(err.response?.data?.error?.message || err.response?.data?.detail || '未知错误', '删除用户失败')
   }
 }
 </script>

frontend/src/views/public/Home.vue

@@ -102,9 +102,9 @@
     <!-- Main Content -->
     <main class="relative z-10">
       <!-- Fixed Logo Container -->
-      <div class="fixed inset-0 z-20 pointer-events-none flex items-center justify-center overflow-hidden">
+      <div class="mt-4 fixed inset-0 z-20 pointer-events-none flex items-center justify-center overflow-hidden">
         <div
-          class="transform-gpu logo-container"
+          class="mt-16 transform-gpu logo-container"
           :class="[currentSection === SECTIONS.HOME ? 'home-section' : '', `logo-transition-${scrollDirection}`]"
           :style="fixedLogoStyle"
         >
@@ -151,7 +151,7 @@
         class="min-h-screen snap-start flex items-center justify-center px-16 lg:px-20 py-20"
       >
         <div class="max-w-4xl mx-auto text-center">
-          <div class="h-80 w-full mb-16" />
+          <div class="h-80 w-full mb-16 mt-8" />
           <h1
             class="mb-6 text-5xl md:text-7xl font-bold text-[#191919] dark:text-white leading-tight transition-all duration-700"
             :style="getTitleStyle(SECTIONS.HOME)"
@@ -166,7 +166,7 @@
             整合 Claude Code、Codex CLI、Gemini CLI 等多个 AI 编程助手
           </p>
           <button
-            class="mt-16 transition-all duration-700 cursor-pointer hover:scale-110"
+            class="mt-8 transition-all duration-700 cursor-pointer hover:scale-110"
             :style="getScrollIndicatorStyle(SECTIONS.HOME)"
             @click="scrollToSection(SECTIONS.CLAUDE)"
           >

frontend/src/views/shared/Usage.vue

@@ -301,6 +301,7 @@ function stopGlobalAutoRefresh() {
 function handleAutoRefreshChange(value: boolean) {
   globalAutoRefresh.value = value
   if (value) {
+    refreshData() // 立即刷新一次
     startGlobalAutoRefresh()
   } else {
     stopGlobalAutoRefresh()

frontend/src/views/user/ModelCatalog.vue

@@ -342,6 +342,7 @@ import {
   Plus,
 } from 'lucide-vue-next'
 import { useToast } from '@/composables/useToast'
+import { useClipboard } from '@/composables/useClipboard'
 import {
   Card,
   Table,
@@ -370,6 +371,7 @@ import { useRowClick } from '@/composables/useRowClick'
 import { log } from '@/utils/logger'
 
 const { success, error: showError } = useToast()
+const { copyToClipboard } = useClipboard()
 
 // 状态
 const loading = ref(false)
@@ -565,16 +567,6 @@ function hasTieredPricing(model: PublicGlobalModel): boolean {
   return (tiered?.tiers?.length || 0) > 1
 }
 
-async function copyToClipboard(text: string) {
-  try {
-    await navigator.clipboard.writeText(text)
-    success('已复制')
-  } catch (err) {
-    log.error('复制失败:', err)
-    showError('复制失败')
-  }
-}
-
 onMounted(() => {
   refreshData()
 })

frontend/src/views/user/components/UserModelDetailDrawer.vue

@@ -352,6 +352,7 @@ import {
 } from 'lucide-vue-next'
 import { useEscapeKey } from '@/composables/useEscapeKey'
 import { useToast } from '@/composables/useToast'
+import { useClipboard } from '@/composables/useClipboard'
 import Card from '@/components/ui/card.vue'
 import Badge from '@/components/ui/badge.vue'
 import Button from '@/components/ui/button.vue'
@@ -375,6 +376,7 @@ const emit = defineEmits<{
 }>()
 
 const { success: showSuccess, error: showError } = useToast()
+const { copyToClipboard } = useClipboard()
 
 interface Props {
   model: PublicGlobalModel | null
@@ -408,15 +410,6 @@ function handleClose() {
   emit('update:open', false)
 }
 
-async function copyToClipboard(text: string) {
-  try {
-    await navigator.clipboard.writeText(text)
-    showSuccess('已复制')
-  } catch {
-    showError('复制失败')
-  }
-}
-
 function getFirstTierPrice(
   tieredPricing: TieredPricingConfig | undefined | null,
   priceKey: 'input_price_per_1m' | 'output_price_per_1m' | 'cache_creation_price_per_1m' | 'cache_read_price_per_1m'

src/api/admin/provider_query.py

@@ -32,6 +32,17 @@ class ModelsQueryRequest(BaseModel):
     api_key_id: Optional[str] = None
 
 
+class TestModelRequest(BaseModel):
+    """模型测试请求"""
+
+    provider_id: str
+    model_name: str
+    api_key_id: Optional[str] = None
+    stream: bool = False
+    message: Optional[str] = "你好"
+    api_format: Optional[str] = None  # 指定使用的API格式，如果不指定则使用端点的默认格式
+
+
 # ============ API Endpoints ============
 
 
@@ -206,3 +217,228 @@ async def query_available_models(
             "display_name": provider.display_name,
         },
     }
+
+
+@router.post("/test-model")
+async def test_model(
+    request: TestModelRequest,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """
+    测试模型连接性
+
+    向指定提供商的指定模型发送测试请求，验证模型是否可用
+
+    Args:
+        request: 测试请求
+
+    Returns:
+        测试结果
+    """
+    # 获取提供商及其端点
+    provider = (
+        db.query(Provider)
+        .options(joinedload(Provider.endpoints).joinedload(ProviderEndpoint.api_keys))
+        .filter(Provider.id == request.provider_id)
+        .first()
+    )
+
+    if not provider:
+        raise HTTPException(status_code=404, detail="Provider not found")
+
+    # 找到合适的端点和API Key
+    endpoint_config = None
+    endpoint = None
+    api_key = None
+
+    if request.api_key_id:
+        # 使用指定的API Key
+        for ep in provider.endpoints:
+            for key in ep.api_keys:
+                if key.id == request.api_key_id and key.is_active and ep.is_active:
+                    endpoint = ep
+                    api_key = key
+                    break
+            if endpoint:
+                break
+    else:
+        # 使用第一个可用的端点和密钥
+        for ep in provider.endpoints:
+            if not ep.is_active or not ep.api_keys:
+                continue
+            for key in ep.api_keys:
+                if key.is_active:
+                    endpoint = ep
+                    api_key = key
+                    break
+            if endpoint:
+                break
+
+    if not endpoint or not api_key:
+        raise HTTPException(status_code=404, detail="No active endpoint or API key found")
+
+    try:
+        api_key_value = crypto_service.decrypt(api_key.api_key)
+    except Exception as e:
+        logger.error(f"[test-model] Failed to decrypt API key: {e}")
+        raise HTTPException(status_code=500, detail="Failed to decrypt API key")
+
+    # 构建请求配置
+    endpoint_config = {
+        "api_key": api_key_value,
+        "api_key_id": api_key.id,  # 添加API Key ID用于用量记录
+        "base_url": endpoint.base_url,
+        "api_format": endpoint.api_format,
+        "extra_headers": endpoint.headers,
+        "timeout": endpoint.timeout or 30.0,
+    }
+
+    try:
+        # 获取对应的 Adapter 类
+        adapter_class = _get_adapter_for_format(endpoint.api_format)
+        if not adapter_class:
+            return {
+                "success": False,
+                "error": f"Unknown API format: {endpoint.api_format}",
+                "provider": {
+                    "id": provider.id,
+                    "name": provider.name,
+                    "display_name": provider.display_name,
+                },
+                "model": request.model_name,
+            }
+
+        logger.debug(f"[test-model] 使用 Adapter: {adapter_class.__name__}")
+        logger.debug(f"[test-model] 端点 API Format: {endpoint.api_format}")
+
+        # 如果请求指定了 api_format，优先使用它
+        target_api_format = request.api_format or endpoint.api_format
+        if request.api_format and request.api_format != endpoint.api_format:
+            logger.debug(f"[test-model] 请求指定 API Format: {request.api_format}")
+            # 重新获取适配器
+            adapter_class = _get_adapter_for_format(request.api_format)
+            if not adapter_class:
+                return {
+                    "success": False,
+                    "error": f"Unknown API format: {request.api_format}",
+                    "provider": {
+                        "id": provider.id,
+                        "name": provider.name,
+                        "display_name": provider.display_name,
+                    },
+                    "model": request.model_name,
+                }
+            logger.debug(f"[test-model] 重新选择 Adapter: {adapter_class.__name__}")
+
+        # 准备测试请求数据
+        check_request = {
+            "model": request.model_name,
+            "messages": [
+                {"role": "user", "content": request.message or "Hello! This is a test message."}
+            ],
+            "max_tokens": 30,
+            "temperature": 0.7,
+        }
+
+        # 发送测试请求
+        async with httpx.AsyncClient(timeout=endpoint_config["timeout"]) as client:
+            # 非流式测试
+            logger.debug(f"[test-model] 开始非流式测试...")
+
+            response = await adapter_class.check_endpoint(
+                client,
+                endpoint_config["base_url"],
+                endpoint_config["api_key"],
+                check_request,
+                endpoint_config.get("extra_headers"),
+                # 用量计算参数（现在强制记录）
+                db=db,
+                user=current_user,
+                provider_name=provider.name,
+                provider_id=provider.id,
+                api_key_id=endpoint_config.get("api_key_id"),
+                model_name=request.model_name,
+            )
+
+            # 记录提供商返回信息
+            logger.debug(f"[test-model] 非流式测试结果:")
+            logger.debug(f"[test-model] Status Code: {response.get('status_code')}")
+            logger.debug(f"[test-model] Response Headers: {response.get('headers', {})}")
+            response_data = response.get('response', {})
+            response_body = response_data.get('response_body', {})
+            logger.debug(f"[test-model] Response Data: {response_data}")
+            logger.debug(f"[test-model] Response Body: {response_body}")
+            # 尝试解析 response_body (通常是 JSON 字符串)
+            parsed_body = response_body
+            import json
+            if isinstance(response_body, str):
+                try:
+                    parsed_body = json.loads(response_body)
+                except json.JSONDecodeError:
+                    pass
+
+            if isinstance(parsed_body, dict) and 'error' in parsed_body:
+                error_obj = parsed_body['error']
+                # 兼容 error 可能是字典或字符串的情况
+                if isinstance(error_obj, dict):
+                    logger.debug(f"[test-model] Error Message: {error_obj.get('message')}")
+                    raise HTTPException(status_code=500, detail=error_obj.get('message'))
+                else:
+                    logger.debug(f"[test-model] Error: {error_obj}")
+                    raise HTTPException(status_code=500, detail=error_obj)
+            elif 'error' in response:
+                logger.debug(f"[test-model] Error: {response['error']}")
+                raise HTTPException(status_code=500, detail=response['error'])
+            else:
+                # 如果有选择或消息，记录内容预览
+                if isinstance(response_data, dict):
+                    if 'choices' in response_data and response_data['choices']:
+                        choice = response_data['choices'][0]
+                        if 'message' in choice:
+                            content = choice['message'].get('content', '')
+                            logger.debug(f"[test-model] Content Preview: {content[:200]}...")
+                    elif 'content' in response_data and response_data['content']:
+                        content = str(response_data['content'])
+                        logger.debug(f"[test-model] Content Preview: {content[:200]}...")
+
+            # 检查测试是否成功（基于HTTP状态码）
+            status_code = response.get('status_code', 0)
+            is_success = status_code == 200 and 'error' not in response
+
+            return {
+                "success": is_success,
+                "data": {
+                    "stream": False,
+                    "response": response,
+                },
+                "provider": {
+                    "id": provider.id,
+                    "name": provider.name,
+                    "display_name": provider.display_name,
+                },
+                "model": request.model_name,
+                "endpoint": {
+                    "id": endpoint.id,
+                    "api_format": endpoint.api_format,
+                    "base_url": endpoint.base_url,
+                },
+            }
+
+    except Exception as e:
+        logger.error(f"[test-model] Error testing model {request.model_name}: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "provider": {
+                "id": provider.id,
+                "name": provider.name,
+                "display_name": provider.display_name,
+            },
+            "model": request.model_name,
+            "endpoint": {
+                "id": endpoint.id,
+                "api_format": endpoint.api_format,
+                "base_url": endpoint.base_url,
+            } if endpoint else None,
+        }

src/api/handlers/base/chat_adapter_base.py

@@ -63,6 +63,34 @@ class ChatAdapterBase(ApiAdapter):
     name: str = "chat.base"
     mode = ApiMode.STANDARD
 
+    # 子类可以配置的特殊方法（用于check_endpoint）
+    @classmethod
+    def build_endpoint_url(cls, base_url: str) -> str:
+        """构建端点URL，子类可以覆盖以自定义URL构建逻辑"""
+        # 默认实现：在base_url后添加特定路径
+        return base_url
+
+    @classmethod
+    def build_base_headers(cls, api_key: str) -> Dict[str, str]:
+        """构建基础请求头，子类可以覆盖以自定义认证头"""
+        # 默认实现：Bearer token认证
+        return {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        }
+
+    @classmethod
+    def get_protected_header_keys(cls) -> tuple:
+        """返回不应被extra_headers覆盖的头部key，子类可以覆盖"""
+        # 默认保护认证相关头部
+        return ("authorization", "content-type")
+
+    @classmethod
+    def build_request_body(cls, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """构建请求体，子类可以覆盖以自定义请求格式转换"""
+        # 默认实现：直接使用请求数据
+        return request_data.copy()
+
     def __init__(self, allowed_api_formats: Optional[list[str]] = None):
         self.allowed_api_formats = allowed_api_formats or [self.FORMAT_ID]
 
@@ -654,6 +682,65 @@ class ChatAdapterBase(ApiAdapter):
         # 默认实现返回空列表，子类应覆盖
         return [], f"{cls.FORMAT_ID} adapter does not implement fetch_models"
 
+    @classmethod
+    async def check_endpoint(
+        cls,
+        client: httpx.AsyncClient,
+        base_url: str,
+        api_key: str,
+        request_data: Dict[str, Any],
+        extra_headers: Optional[Dict[str, str]] = None,
+        # 用量计算参数（现在强制记录）
+        db: Optional[Any] = None,
+        user: Optional[Any] = None,
+        provider_name: Optional[str] = None,
+        provider_id: Optional[str] = None,
+        api_key_id: Optional[str] = None,
+        model_name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        测试模型连接性（非流式）
+
+        Args:
+            client: httpx 异步客户端
+            base_url: API 基础 URL
+            api_key: API 密钥（已解密）
+            request_data: 请求数据
+            extra_headers: 端点配置的额外请求头
+            db: 数据库会话
+            user: 用户对象
+            provider_name: 提供商名称
+            provider_id: 提供商ID
+            api_key_id: API Key ID
+            model_name: 模型名称
+
+        Returns:
+            测试响应数据
+        """
+        from src.api.handlers.base.endpoint_checker import build_safe_headers, run_endpoint_check
+
+        # 使用子类配置方法构建请求组件
+        url = cls.build_endpoint_url(base_url)
+        base_headers = cls.build_base_headers(api_key)
+        protected_keys = cls.get_protected_header_keys()
+        headers = build_safe_headers(base_headers, extra_headers, protected_keys)
+        body = cls.build_request_body(request_data)
+
+        # 使用通用的endpoint checker执行请求
+        return await run_endpoint_check(
+            client=client,
+            url=url,
+            headers=headers,
+            json_body=body,
+            api_format=cls.name,
+            # 用量计算参数（现在强制记录）
+            db=db,
+            user=user,
+            provider_name=provider_name,
+            provider_id=provider_id,
+            api_key_id=api_key_id,
+            model_name=model_name or request_data.get("model"),
+        )
 
 # =========================================================================
 # Adapter 注册表 - 用于根据 API format 获取 Adapter 实例

src/api/handlers/base/chat_handler_base.py

@@ -484,9 +484,8 @@ class ChatHandlerBase(BaseMessageHandler, ABC):
 
             stream_response.raise_for_status()
 
-            # 使用字节流迭代器（避免 aiter_lines 的性能问题）
-            # aiter_raw() 返回原始数据块，无缓冲，实现真正的流式传输
-            byte_iterator = stream_response.aiter_raw()
+            # 使用字节流迭代器（避免 aiter_lines 的性能问题, aiter_bytes 会自动解压 gzip/deflate）
+            byte_iterator = stream_response.aiter_bytes()
 
             # 预读检测嵌套错误
             prefetched_chunks = await stream_processor.prefetch_and_check_error(

src/api/handlers/base/cli_adapter_base.py

@@ -614,6 +614,146 @@ class CliAdapterBase(ApiAdapter):
         # 默认实现返回空列表，子类应覆盖
         return [], f"{cls.FORMAT_ID} adapter does not implement fetch_models"
 
+    @classmethod
+    async def check_endpoint(
+        cls,
+        client: httpx.AsyncClient,
+        base_url: str,
+        api_key: str,
+        request_data: Dict[str, Any],
+        extra_headers: Optional[Dict[str, str]] = None,
+        # 用量计算参数
+        db: Optional[Any] = None,
+        user: Optional[Any] = None,
+        provider_name: Optional[str] = None,
+        provider_id: Optional[str] = None,
+        api_key_id: Optional[str] = None,
+        model_name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        测试模型连接性（非流式）
+
+        通用的CLI endpoint测试方法，使用配置方法模式：
+        - build_endpoint_url(): 构建请求URL
+        - build_base_headers(): 构建基础认证头
+        - get_protected_header_keys(): 获取受保护的头部key
+        - build_request_body(): 构建请求体
+        - get_cli_user_agent(): 获取CLI User-Agent（子类可覆盖）
+
+        Args:
+            client: httpx 异步客户端
+            base_url: API 基础 URL
+            api_key: API 密钥（已解密）
+            request_data: 请求数据
+            extra_headers: 端点配置的额外请求头
+            db: 数据库会话
+            user: 用户对象
+            provider_name: 提供商名称
+            provider_id: 提供商ID
+            api_key_id: API密钥ID
+            model_name: 模型名称
+
+        Returns:
+            测试响应数据
+        """
+        from src.api.handlers.base.endpoint_checker import build_safe_headers, run_endpoint_check
+
+        # 构建请求组件
+        url = cls.build_endpoint_url(base_url, request_data, model_name)
+        base_headers = cls.build_base_headers(api_key)
+        protected_keys = cls.get_protected_header_keys()
+
+        # 添加CLI User-Agent
+        cli_user_agent = cls.get_cli_user_agent()
+        if cli_user_agent:
+            base_headers["User-Agent"] = cli_user_agent
+            protected_keys = tuple(list(protected_keys) + ["user-agent"])
+
+        headers = build_safe_headers(base_headers, extra_headers, protected_keys)
+        body = cls.build_request_body(request_data)
+
+        # 获取有效的模型名称
+        effective_model_name = model_name or request_data.get("model")
+
+        return await run_endpoint_check(
+            client=client,
+            url=url,
+            headers=headers,
+            json_body=body,
+            api_format=cls.name,
+            # 用量计算参数（现在强制记录）
+            db=db,
+            user=user,
+            provider_name=provider_name,
+            provider_id=provider_id,
+            api_key_id=api_key_id,
+            model_name=effective_model_name,
+        )
+
+    # =========================================================================
+    # CLI Adapter 配置方法 - 子类应覆盖这些方法而不是整个 check_endpoint
+    # =========================================================================
+
+    @classmethod
+    def build_endpoint_url(cls, base_url: str, request_data: Dict[str, Any], model_name: Optional[str] = None) -> str:
+        """
+        构建CLI API端点URL - 子类应覆盖
+
+        Args:
+            base_url: API基础URL
+            request_data: 请求数据
+            model_name: 模型名称（某些API需要，如Gemini）
+
+        Returns:
+            完整的端点URL
+        """
+        raise NotImplementedError(f"{cls.FORMAT_ID} adapter must implement build_endpoint_url")
+
+    @classmethod
+    def build_base_headers(cls, api_key: str) -> Dict[str, str]:
+        """
+        构建CLI API认证头 - 子类应覆盖
+
+        Args:
+            api_key: API密钥
+
+        Returns:
+            基础认证头部字典
+        """
+        raise NotImplementedError(f"{cls.FORMAT_ID} adapter must implement build_base_headers")
+
+    @classmethod
+    def get_protected_header_keys(cls) -> tuple:
+        """
+        返回CLI API的保护头部key - 子类应覆盖
+
+        Returns:
+            保护头部key的元组
+        """
+        raise NotImplementedError(f"{cls.FORMAT_ID} adapter must implement get_protected_header_keys")
+
+    @classmethod
+    def build_request_body(cls, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        构建CLI API请求体 - 子类应覆盖
+
+        Args:
+            request_data: 请求数据
+
+        Returns:
+            请求体字典
+        """
+        raise NotImplementedError(f"{cls.FORMAT_ID} adapter must implement build_request_body")
+
+    @classmethod
+    def get_cli_user_agent(cls) -> Optional[str]:
+        """
+        获取CLI User-Agent - 子类可覆盖
+
+        Returns:
+            CLI User-Agent字符串，如果不需要则为None
+        """
+        return None
 
 # =========================================================================
 # CLI Adapter 注册表 - 用于根据 API format 获取 CLI Adapter 实例

src/api/handlers/base/cli_handler_base.py

@@ -476,8 +476,8 @@ class CliMessageHandlerBase(BaseMessageHandler):
 
             stream_response.raise_for_status()
 
-            # 使用字节流迭代器（避免 aiter_lines 的性能问题）
-            byte_iterator = stream_response.aiter_raw()
+            # 使用字节流迭代器（避免 aiter_lines 的性能问题, aiter_bytes 会自动解压 gzip/deflate）
+            byte_iterator = stream_response.aiter_bytes()
 
             # 预读第一个数据块，检测嵌套错误（HTTP 200 但响应体包含错误）
             prefetched_chunks = await self._prefetch_and_check_embedded_error(
@@ -531,7 +531,7 @@ class CliMessageHandlerBase(BaseMessageHandler):
             # 检查是否需要格式转换
             needs_conversion = self._needs_format_conversion(ctx)
 
-            async for chunk in stream_response.aiter_raw():
+            async for chunk in stream_response.aiter_bytes():
                 # 在第一次输出数据前更新状态为 streaming
                 if not streaming_status_updated:
                     self._update_usage_to_streaming_with_ctx(ctx)

src/api/handlers/base/utils.py

@@ -4,17 +4,28 @@ Handler 基础工具函数
 
 from typing import Any, Dict, Optional
 
+from src.core.logger import logger
+
 
 def extract_cache_creation_tokens(usage: Dict[str, Any]) -> int:
     """
-    提取缓存创建 tokens（兼容新旧格式）
+    提取缓存创建 tokens（兼容三种格式）
 
-    Claude API 在不同版本中使用了不同的字段名来表示缓存创建 tokens：
-    - 新格式（2024年后）：使用 claude_cache_creation_5_m_tokens 和
-      claude_cache_creation_1_h_tokens 分别表示 5 分钟和 1 小时缓存
-    - 旧格式：使用 cache_creation_input_tokens 表示总的缓存创建 tokens
+    根据 Anthropic API 文档，支持三种格式（按优先级）：
 
-    此函数自动检测并适配两种格式，优先使用新格式。
+    1. **嵌套格式（优先级最高）**：
+       usage.cache_creation.ephemeral_5m_input_tokens
+       usage.cache_creation.ephemeral_1h_input_tokens
+
+    2. **扁平新格式（优先级第二）**：
+       usage.claude_cache_creation_5_m_tokens
+       usage.claude_cache_creation_1_h_tokens
+
+    3. **旧格式（优先级第三）**：
+       usage.cache_creation_input_tokens
+
+    优先使用嵌套格式，如果嵌套格式字段存在但值为 0，则智能 fallback 到旧格式。
+    扁平格式和嵌套格式互斥，按顺序检查。
 
     Args:
         usage: API 响应中的 usage 字典
@@ -22,20 +33,63 @@ def extract_cache_creation_tokens(usage: Dict[str, Any]) -> int:
     Returns:
         缓存创建 tokens 总数
     """
-    # 检查新格式字段是否存在（而非值是否为 0）
-    # 如果字段存在，即使值为 0 也是合法的，不应 fallback 到旧格式
-    has_new_format = (
+    # 1. 检查嵌套格式（最新格式）
+    cache_creation = usage.get("cache_creation")
+    if isinstance(cache_creation, dict):
+        cache_5m = int(cache_creation.get("ephemeral_5m_input_tokens", 0))
+        cache_1h = int(cache_creation.get("ephemeral_1h_input_tokens", 0))
+        total = cache_5m + cache_1h
+
+        if total > 0:
+            logger.debug(
+                f"Using nested cache_creation: 5m={cache_5m}, 1h={cache_1h}, total={total}"
+            )
+            return total
+
+        # 嵌套格式存在但为 0，fallback 到旧格式
+        old_format = int(usage.get("cache_creation_input_tokens", 0))
+        if old_format > 0:
+            logger.debug(
+                f"Nested cache_creation is 0, using old format: {old_format}"
+            )
+            return old_format
+
+        # 都是 0，返回 0
+        return 0
+
+    # 2. 检查扁平新格式
+    has_flat_format = (
         "claude_cache_creation_5_m_tokens" in usage
         or "claude_cache_creation_1_h_tokens" in usage
     )
 
-    if has_new_format:
-        cache_5m = usage.get("claude_cache_creation_5_m_tokens", 0)
-        cache_1h = usage.get("claude_cache_creation_1_h_tokens", 0)
-        return int(cache_5m) + int(cache_1h)
+    if has_flat_format:
+        cache_5m = int(usage.get("claude_cache_creation_5_m_tokens", 0))
+        cache_1h = int(usage.get("claude_cache_creation_1_h_tokens", 0))
+        total = cache_5m + cache_1h
 
-    # 回退到旧格式
-    return int(usage.get("cache_creation_input_tokens", 0))
+        if total > 0:
+            logger.debug(
+                f"Using flat new format: 5m={cache_5m}, 1h={cache_1h}, total={total}"
+            )
+            return total
+
+        # 扁平格式存在但为 0，fallback 到旧格式
+        old_format = int(usage.get("cache_creation_input_tokens", 0))
+        if old_format > 0:
+            logger.debug(
+                f"Flat cache_creation is 0, using old format: {old_format}"
+            )
+            return old_format
+
+        # 都是 0，返回 0
+        return 0
+
+    # 3. 回退到旧格式
+    old_format = int(usage.get("cache_creation_input_tokens", 0))
+    if old_format > 0:
+        logger.debug(f"Using old format: cache_creation_input_tokens={old_format}")
+    return old_format
 
 
 def build_sse_headers(extra_headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:

src/api/handlers/claude/adapter.py

@@ -209,6 +209,38 @@ class ClaudeChatAdapter(ChatAdapterBase):
             logger.warning(f"Failed to fetch Claude models from {models_url}: {e}")
             return [], error_msg
 
+    @classmethod
+    def build_endpoint_url(cls, base_url: str) -> str:
+        """构建Claude API端点URL"""
+        base_url = base_url.rstrip("/")
+        if base_url.endswith("/v1"):
+            return f"{base_url}/messages"
+        else:
+            return f"{base_url}/v1/messages"
+
+    @classmethod
+    def build_base_headers(cls, api_key: str) -> Dict[str, str]:
+        """构建Claude API认证头"""
+        return {
+            "x-api-key": api_key,
+            "Content-Type": "application/json",
+            "anthropic-version": "2023-06-01",
+        }
+
+    @classmethod
+    def get_protected_header_keys(cls) -> tuple:
+        """返回Claude API的保护头部key"""
+        return ("x-api-key", "content-type", "anthropic-version")
+
+    @classmethod
+    def build_request_body(cls, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """构建Claude API请求体"""
+        return {
+            "model": request_data.get("model"),
+            "max_tokens": request_data.get("max_tokens", 100),
+            "messages": request_data.get("messages", []),
+        }
+
 
 def build_claude_adapter(x_app_header: Optional[str]):
     """根据 x-app 头部构造 Chat 或 Claude Code 适配器。"""

src/api/handlers/claude_cli/adapter.py

@@ -4,7 +4,7 @@ Claude CLI Adapter - 基于通用 CLI Adapter 基类的简化实现
 继承 CliAdapterBase，只需配置 FORMAT_ID 和 HANDLER_CLASS。
 """
 
-from typing import Any, Dict, Optional, Tuple, Type
+from typing import Any, AsyncIterator, Dict, Optional, Tuple, Type, Union
 
 import httpx
 from fastapi import Request
@@ -126,5 +126,41 @@ class ClaudeCliAdapter(CliAdapterBase):
             m["api_format"] = cls.FORMAT_ID
         return models, error
 
+    @classmethod
+    def build_endpoint_url(cls, base_url: str, request_data: Dict[str, Any], model_name: Optional[str] = None) -> str:
+        """构建Claude CLI API端点URL"""
+        base_url = base_url.rstrip("/")
+        if base_url.endswith("/v1"):
+            return f"{base_url}/messages"
+        else:
+            return f"{base_url}/v1/messages"
+
+    @classmethod
+    def build_base_headers(cls, api_key: str) -> Dict[str, str]:
+        """构建Claude CLI API认证头"""
+        return {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        }
+
+    @classmethod
+    def get_protected_header_keys(cls) -> tuple:
+        """返回Claude CLI API的保护头部key"""
+        return ("authorization", "content-type")
+
+    @classmethod
+    def build_request_body(cls, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """构建Claude CLI API请求体"""
+        return {
+            "model": request_data.get("model"),
+            "max_tokens": request_data.get("max_tokens", 100),
+            "messages": request_data.get("messages", []),
+        }
+
+    @classmethod
+    def get_cli_user_agent(cls) -> Optional[str]:
+        """获取Claude CLI User-Agent"""
+        return config.internal_user_agent_claude_cli
+
 
 __all__ = ["ClaudeCliAdapter"]

src/api/handlers/gemini/adapter.py

@@ -4,7 +4,7 @@ Gemini Chat Adapter
 处理 Gemini API 格式的请求适配
 """
 
-from typing import Any, Dict, Optional, Tuple, Type
+from typing import Any, AsyncIterator, Dict, Optional, Tuple, Type, Union
 
 import httpx
 from fastapi import HTTPException, Request
@@ -12,6 +12,7 @@ from fastapi.responses import JSONResponse
 
 from src.api.handlers.base.chat_adapter_base import ChatAdapterBase, register_adapter
 from src.api.handlers.base.chat_handler_base import ChatHandlerBase
+from src.api.handlers.base.endpoint_checker import build_safe_headers, run_endpoint_check
 from src.core.logger import logger
 from src.models.gemini import GeminiRequest
 
@@ -199,6 +200,94 @@ class GeminiChatAdapter(ChatAdapterBase):
             logger.warning(f"Failed to fetch Gemini models from {models_url}: {e}")
             return [], error_msg
 
+    @classmethod
+    def build_endpoint_url(cls, base_url: str) -> str:
+        """构建Gemini API端点URL"""
+        base_url = base_url.rstrip("/")
+        if base_url.endswith("/v1beta"):
+            return base_url  # 子类需要处理model参数
+        else:
+            return f"{base_url}/v1beta"
+
+    @classmethod
+    def build_base_headers(cls, api_key: str) -> Dict[str, str]:
+        """构建Gemini API认证头"""
+        return {
+            "x-goog-api-key": api_key,
+            "Content-Type": "application/json",
+        }
+
+    @classmethod
+    def get_protected_header_keys(cls) -> tuple:
+        """返回Gemini API的保护头部key"""
+        return ("x-goog-api-key", "content-type")
+
+    @classmethod
+    def build_request_body(cls, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """构建Gemini API请求体"""
+        return {
+            "contents": request_data.get("messages", []),
+            "generationConfig": {
+                "maxOutputTokens": request_data.get("max_tokens", 100),
+                "temperature": request_data.get("temperature", 0.7),
+            },
+            "safetySettings": [
+                {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE"}
+            ],
+        }
+
+    @classmethod
+    async def check_endpoint(
+        cls,
+        client: httpx.AsyncClient,
+        base_url: str,
+        api_key: str,
+        request_data: Dict[str, Any],
+        extra_headers: Optional[Dict[str, str]] = None,
+        # 用量计算参数
+        db: Optional[Any] = None,
+        user: Optional[Any] = None,
+        provider_name: Optional[str] = None,
+        provider_id: Optional[str] = None,
+        api_key_id: Optional[str] = None,
+        model_name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """测试 Gemini API 模型连接性（非流式）"""
+        # Gemini需要从request_data或model_name参数获取model名称
+        effective_model_name = model_name or request_data.get("model", "")
+        if not effective_model_name:
+            return {
+                "error": "Model name is required for Gemini API",
+                "status_code": 400,
+            }
+
+        # 使用基类配置方法，但重写URL构建逻辑
+        base_url = cls.build_endpoint_url(base_url)
+        url = f"{base_url}/models/{effective_model_name}:generateContent"
+
+        # 构建请求组件
+        base_headers = cls.build_base_headers(api_key)
+        protected_keys = cls.get_protected_header_keys()
+        headers = build_safe_headers(base_headers, extra_headers, protected_keys)
+        body = cls.build_request_body(request_data)
+
+        # 使用基类的通用endpoint checker
+        from src.api.handlers.base.endpoint_checker import run_endpoint_check
+        return await run_endpoint_check(
+            client=client,
+            url=url,
+            headers=headers,
+            json_body=body,
+            api_format=cls.name,
+            # 用量计算参数（现在强制记录）
+            db=db,
+            user=user,
+            provider_name=provider_name,
+            provider_id=provider_id,
+            api_key_id=api_key_id,
+            model_name=effective_model_name,
+        )
+
 
 def build_gemini_adapter(x_app_header: str = "") -> GeminiChatAdapter:
     """

src/api/handlers/gemini_cli/adapter.py

@@ -4,7 +4,7 @@ Gemini CLI Adapter - 基于通用 CLI Adapter 基类的实现
 继承 CliAdapterBase，处理 Gemini CLI 格式的请求。
 """
 
-from typing import Any, Dict, Optional, Tuple, Type
+from typing import Any, AsyncIterator, Dict, Optional, Tuple, Type, Union
 
 import httpx
 from fastapi import Request
@@ -123,6 +123,52 @@ class GeminiCliAdapter(CliAdapterBase):
             m["api_format"] = cls.FORMAT_ID
         return models, error
 
+    @classmethod
+    def build_endpoint_url(cls, base_url: str, request_data: Dict[str, Any], model_name: Optional[str] = None) -> str:
+        """构建Gemini CLI API端点URL"""
+        effective_model_name = model_name or request_data.get("model", "")
+        if not effective_model_name:
+            raise ValueError("Model name is required for Gemini API")
+
+        base_url = base_url.rstrip("/")
+        if base_url.endswith("/v1beta"):
+            prefix = base_url
+        else:
+            prefix = f"{base_url}/v1beta"
+        return f"{prefix}/models/{effective_model_name}:generateContent"
+
+    @classmethod
+    def build_base_headers(cls, api_key: str) -> Dict[str, str]:
+        """构建Gemini CLI API认证头"""
+        return {
+            "x-goog-api-key": api_key,
+            "Content-Type": "application/json",
+        }
+
+    @classmethod
+    def get_protected_header_keys(cls) -> tuple:
+        """返回Gemini CLI API的保护头部key"""
+        return ("x-goog-api-key", "content-type")
+
+    @classmethod
+    def build_request_body(cls, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """构建Gemini CLI API请求体"""
+        return {
+            "contents": request_data.get("messages", []),
+            "generationConfig": {
+                "maxOutputTokens": request_data.get("max_tokens", 100),
+                "temperature": request_data.get("temperature", 0.7),
+            },
+            "safetySettings": [
+                {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE"}
+            ],
+        }
+
+    @classmethod
+    def get_cli_user_agent(cls) -> Optional[str]:
+        """获取Gemini CLI User-Agent"""
+        return config.internal_user_agent_gemini_cli
+
 
 def build_gemini_cli_adapter(x_app_header: str = "") -> GeminiCliAdapter:
     """

src/api/handlers/openai/adapter.py

@@ -4,13 +4,14 @@ OpenAI Chat Adapter - 基于 ChatAdapterBase 的 OpenAI Chat API 适配器
 处理 /v1/chat/completions 端点的 OpenAI Chat 格式请求。
 """
 
-from typing import Any, Dict, Optional, Tuple, Type
+from typing import Any, AsyncIterator, Dict, Optional, Tuple, Type, Union
 
 import httpx
 from fastapi import Request
 from fastapi.responses import JSONResponse
 
 from src.api.handlers.base.chat_adapter_base import ChatAdapterBase, register_adapter
+from src.api.handlers.base.endpoint_checker import build_safe_headers, run_endpoint_check
 from src.api.handlers.base.chat_handler_base import ChatHandlerBase
 from src.core.logger import logger
 from src.models.openai import OpenAIRequest
@@ -154,5 +155,32 @@ class OpenAIChatAdapter(ChatAdapterBase):
             logger.warning(f"Failed to fetch models from {models_url}: {e}")
             return [], error_msg
 
+    @classmethod
+    def build_endpoint_url(cls, base_url: str) -> str:
+        """构建OpenAI API端点URL"""
+        base_url = base_url.rstrip("/")
+        if base_url.endswith("/v1"):
+            return f"{base_url}/chat/completions"
+        else:
+            return f"{base_url}/v1/chat/completions"
+
+    @classmethod
+    def build_base_headers(cls, api_key: str) -> Dict[str, str]:
+        """构建OpenAI API认证头"""
+        return {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        }
+
+    @classmethod
+    def get_protected_header_keys(cls) -> tuple:
+        """返回OpenAI API的保护头部key"""
+        return ("authorization", "content-type")
+
+    @classmethod
+    def build_request_body(cls, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """构建OpenAI API请求体"""
+        return request_data.copy()
+
 
 __all__ = ["OpenAIChatAdapter"]

src/api/handlers/openai_cli/adapter.py

@@ -4,7 +4,7 @@ OpenAI CLI Adapter - 基于通用 CLI Adapter 基类的简化实现
 继承 CliAdapterBase，只需配置 FORMAT_ID 和 HANDLER_CLASS。
 """
 
-from typing import Dict, Optional, Tuple, Type
+from typing import Any, AsyncIterator, Dict, Optional, Tuple, Type, Union
 
 import httpx
 from fastapi import Request
@@ -68,5 +68,37 @@ class OpenAICliAdapter(CliAdapterBase):
             m["api_format"] = cls.FORMAT_ID
         return models, error
 
+    @classmethod
+    def build_endpoint_url(cls, base_url: str, request_data: Dict[str, Any], model_name: Optional[str] = None) -> str:
+        """构建OpenAI CLI API端点URL"""
+        base_url = base_url.rstrip("/")
+        if base_url.endswith("/v1"):
+            return f"{base_url}/chat/completions"
+        else:
+            return f"{base_url}/v1/chat/completions"
+
+    @classmethod
+    def build_base_headers(cls, api_key: str) -> Dict[str, str]:
+        """构建OpenAI CLI API认证头"""
+        return {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        }
+
+    @classmethod
+    def get_protected_header_keys(cls) -> tuple:
+        """返回OpenAI CLI API的保护头部key"""
+        return ("authorization", "content-type")
+
+    @classmethod
+    def build_request_body(cls, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """构建OpenAI CLI API请求体"""
+        return request_data.copy()
+
+    @classmethod
+    def get_cli_user_agent(cls) -> Optional[str]:
+        """获取OpenAI CLI User-Agent"""
+        return config.internal_user_agent_openai_cli
+
 
 __all__ = ["OpenAICliAdapter"]

src/models/admin_requests.py

@@ -317,6 +317,7 @@ class UpdateUserRequest(BaseModel):
 
     username: Optional[str] = Field(None, min_length=1, max_length=50)
     email: Optional[str] = Field(None, max_length=100)
+    password: Optional[str] = Field(None, min_length=6, max_length=128, description="新密码（留空保持不变）")
     quota_usd: Optional[float] = Field(None, ge=0)
     is_active: Optional[bool] = None
     role: Optional[str] = None

src/services/cache/aware_scheduler.py

@@ -30,6 +30,8 @@
 
 from __future__ import annotations
 
+import hashlib
+import random
 import time
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Union
@@ -956,7 +958,16 @@ class CacheAwareScheduler:
 
                 # 获取活跃的 Key 并按 internal_priority + 负载均衡排序
                 active_keys = [key for key in endpoint.api_keys if key.is_active]
-                keys = self._shuffle_keys_by_internal_priority(active_keys, affinity_key)
+                # 检查是否所有 Key 都是 TTL=0（轮换模式）
+                # 如果所有 Key 的 cache_ttl_minutes 都是 0 或 None，则使用随机排序
+                use_random = all(
+                    (key.cache_ttl_minutes or 0) == 0 for key in active_keys
+                ) if active_keys else False
+                if use_random and len(active_keys) > 1:
+                    logger.debug(
+                        f"  Endpoint {endpoint.id[:8]}... 启用 Key 轮换模式 (TTL=0, {len(active_keys)} keys)"
+                    )
+                keys = self._shuffle_keys_by_internal_priority(active_keys, affinity_key, use_random)
 
                 for key in keys:
                     # Key 级别的能力检查（模型级别的能力检查已在上面完成）
@@ -1170,6 +1181,7 @@ class CacheAwareScheduler:
         self,
         keys: List[ProviderAPIKey],
         affinity_key: Optional[str] = None,
+        use_random: bool = False,
     ) -> List[ProviderAPIKey]:
         """
         对 API Key 按 internal_priority 分组，同优先级内部基于 affinity_key 进行确定性打乱
@@ -1178,10 +1190,12 @@ class CacheAwareScheduler:
         - 数字越小越优先使用
         - 同优先级 Key 之间实现负载均衡
         - 使用 affinity_key 哈希确保同一请求 Key 的请求稳定（避免破坏缓存亲和性）
+        - 当 use_random=True 时，使用随机排序实现轮换（用于 TTL=0 的场景）
 
         Args:
             keys: API Key 列表
             affinity_key: 亲和性标识符（通常为 API Key ID，用于确定性打乱）
+            use_random: 是否使用随机排序（TTL=0 时为 True）
 
         Returns:
             排序后的 Key 列表
@@ -1198,15 +1212,19 @@ class CacheAwareScheduler:
             priority = key.internal_priority if key.internal_priority is not None else 999999
             priority_groups[priority].append(key)
 
-        # 对每个优先级组内的 Key 进行确定性打乱
+        # 对每个优先级组内的 Key 进行打乱
         result = []
         for priority in sorted(priority_groups.keys()):  # 数字小的优先级高，排前面
             group_keys = priority_groups[priority]
 
-            if len(group_keys) > 1 and affinity_key:
-                # 改进的哈希策略：为每个 key 计算独立的哈希值
-                import hashlib
-
+            if len(group_keys) > 1:
+                if use_random:
+                    # TTL=0 模式：使用随机排序实现 Key 轮换
+                    shuffled = list(group_keys)
+                    random.shuffle(shuffled)
+                    result.extend(shuffled)
+                elif affinity_key:
+                    # 正常模式：使用哈希确定性打乱（保持缓存亲和性）
                     key_scores = []
                     for key in group_keys:
                         # 使用 affinity_key + key.id 的组合哈希
@@ -1218,8 +1236,11 @@ class CacheAwareScheduler:
                     sorted_group = [key for _, key in sorted(key_scores)]
                     result.extend(sorted_group)
                 else:
-                # 单个 Key 或没有 affinity_key 时保持原顺序
+                    # 没有 affinity_key 时按 ID 排序保持稳定性
                     result.extend(sorted(group_keys, key=lambda k: k.id))
+            else:
+                # 单个 Key 直接添加
+                result.extend(group_keys)
 
         return result
 

src/services/health/endpoint.py

@@ -234,8 +234,15 @@ class EndpointHealthService:
                 for api_format in format_key_mapping.keys()
             }
 
+        # 参数校验（API 层已通过 Query(ge=1) 保证，这里做防御性检查）
+        if lookback_hours <= 0 or segments <= 0:
+            raise ValueError(
+                f"lookback_hours and segments must be positive, "
+                f"got lookback_hours={lookback_hours}, segments={segments}"
+            )
+
         # 计算时间范围
-        interval_minutes = (lookback_hours * 60) // segments
+        segment_seconds = (lookback_hours * 3600) / segments
         start_time = now - timedelta(hours=lookback_hours)
 
         # 使用 RequestCandidate 表查询所有尝试记录
@@ -243,7 +250,7 @@ class EndpointHealthService:
         final_statuses = ["success", "failed", "skipped"]
 
         segment_expr = func.floor(
-            func.extract('epoch', RequestCandidate.created_at - start_time) / (interval_minutes * 60)
+            func.extract('epoch', RequestCandidate.created_at - start_time) / segment_seconds
         ).label('segment_idx')
 
         candidate_stats = (

src/services/system/cleanup_scheduler.py

@@ -208,84 +208,118 @@ class CleanupScheduler:
                         return
 
                     # 非首次运行，检查最近是否有缺失的日期需要回填
-                    latest_stat = db.query(StatsDaily).order_by(StatsDaily.date.desc()).first()
+                    from src.models.database import StatsDailyModel
 
-                    if latest_stat:
-                        latest_date_utc = latest_stat.date
-                        if latest_date_utc.tzinfo is None:
-                            latest_date_utc = latest_date_utc.replace(tzinfo=timezone.utc)
-                        else:
-                            latest_date_utc = latest_date_utc.astimezone(timezone.utc)
-
-                        # 使用业务日期计算缺失区间（避免用 UTC 年月日导致日期偏移，且对 DST 更安全）
-                        latest_business_date = latest_date_utc.astimezone(app_tz).date()
                     yesterday_business_date = today_local.date() - timedelta(days=1)
-                        missing_start_date = latest_business_date + timedelta(days=1)
-
-                        if missing_start_date <= yesterday_business_date:
-                            missing_days = (
-                                yesterday_business_date - missing_start_date
-                            ).days + 1
-
-                            # 限制最大回填天数，防止停机很久后一次性回填太多
                     max_backfill_days: int = SystemConfigService.get_config(
                         db, "max_stats_backfill_days", 30
                     ) or 30
-                            if missing_days > max_backfill_days:
-                                logger.warning(
-                                    f"缺失 {missing_days} 天数据超过最大回填限制 "
-                                    f"{max_backfill_days} 天，只回填最近 {max_backfill_days} 天"
-                                )
-                                missing_start_date = yesterday_business_date - timedelta(
+
+                    # 计算回填检查的起始日期
+                    check_start_date = yesterday_business_date - timedelta(
                         days=max_backfill_days - 1
                     )
-                                missing_days = max_backfill_days
 
+                    # 获取 StatsDaily 和 StatsDailyModel 中已有数据的日期集合
+                    existing_daily_dates = set()
+                    existing_model_dates = set()
+
+                    daily_stats = (
+                        db.query(StatsDaily.date)
+                        .filter(StatsDaily.date >= check_start_date.isoformat())
+                        .all()
+                    )
+                    for (stat_date,) in daily_stats:
+                        if stat_date.tzinfo is None:
+                            stat_date = stat_date.replace(tzinfo=timezone.utc)
+                        existing_daily_dates.add(stat_date.astimezone(app_tz).date())
+
+                    model_stats = (
+                        db.query(StatsDailyModel.date)
+                        .filter(StatsDailyModel.date >= check_start_date.isoformat())
+                        .distinct()
+                        .all()
+                    )
+                    for (stat_date,) in model_stats:
+                        if stat_date.tzinfo is None:
+                            stat_date = stat_date.replace(tzinfo=timezone.utc)
+                        existing_model_dates.add(stat_date.astimezone(app_tz).date())
+
+                    # 找出需要回填的日期
+                    all_dates = set()
+                    current = check_start_date
+                    while current <= yesterday_business_date:
+                        all_dates.add(current)
+                        current += timedelta(days=1)
+
+                    # 需要回填 StatsDaily 的日期
+                    missing_daily_dates = all_dates - existing_daily_dates
+                    # 需要回填 StatsDailyModel 的日期
+                    missing_model_dates = all_dates - existing_model_dates
+                    # 合并所有需要处理的日期
+                    dates_to_process = missing_daily_dates | missing_model_dates
+
+                    if dates_to_process:
+                        sorted_dates = sorted(dates_to_process)
                         logger.info(
-                                f"检测到缺失 {missing_days} 天的统计数据 "
-                                f"({missing_start_date} ~ {yesterday_business_date})，开始回填..."
+                            f"检测到 {len(dates_to_process)} 天的统计数据需要回填 "
+                            f"(StatsDaily 缺失 {len(missing_daily_dates)} 天, "
+                            f"StatsDailyModel 缺失 {len(missing_model_dates)} 天)"
                         )
 
-                            current_date = missing_start_date
                         users = (
                             db.query(DBUser.id).filter(DBUser.is_active.is_(True)).all()
                         )
 
-                            while current_date <= yesterday_business_date:
+                        failed_dates = 0
+                        failed_users = 0
+
+                        for current_date in sorted_dates:
                             try:
                                 current_date_local = datetime.combine(
                                     current_date, datetime.min.time(), tzinfo=app_tz
                                 )
+                                # 只在缺失时才聚合对应的表
+                                if current_date in missing_daily_dates:
                                     StatsAggregatorService.aggregate_daily_stats(
                                         db, current_date_local
                                     )
+                                if current_date in missing_model_dates:
                                     StatsAggregatorService.aggregate_daily_model_stats(
                                         db, current_date_local
                                     )
+                                # 用户统计在任一缺失时都回填
                                 for (user_id,) in users:
                                     try:
                                         StatsAggregatorService.aggregate_user_daily_stats(
                                             db, user_id, current_date_local
                                         )
                                     except Exception as e:
+                                        failed_users += 1
                                         logger.warning(
                                             f"回填用户 {user_id} 日期 {current_date} 失败: {e}"
                                         )
                                         try:
                                             db.rollback()
-                                            except Exception:
-                                                pass
+                                        except Exception as rollback_err:
+                                            logger.error(f"回滚失败: {rollback_err}")
                             except Exception as e:
+                                failed_dates += 1
                                 logger.warning(f"回填日期 {current_date} 失败: {e}")
                                 try:
                                     db.rollback()
-                                    except Exception:
-                                        pass
-
-                                current_date += timedelta(days=1)
+                                except Exception as rollback_err:
+                                    logger.error(f"回滚失败: {rollback_err}")
 
                         StatsAggregatorService.update_summary(db)
-                            logger.info(f"缺失数据回填完成，共 {missing_days} 天")
+
+                        if failed_dates > 0 or failed_users > 0:
+                            logger.warning(
+                                f"回填完成，共处理 {len(dates_to_process)} 天，"
+                                f"失败: {failed_dates} 天, {failed_users} 个用户记录"
+                            )
+                        else:
+                            logger.info(f"缺失数据回填完成，共处理 {len(dates_to_process)} 天")
                     else:
                         logger.info("统计数据已是最新，无需回填")
                     return

src/services/user/apikey.py

@@ -59,14 +59,15 @@ class ApiKeyService:
         if expire_days:
             expires_at = datetime.now(timezone.utc) + timedelta(days=expire_days)
 
+        # 空数组转为 None（表示不限制）
         api_key = ApiKey(
             user_id=user_id,
             key_hash=key_hash,
             key_encrypted=key_encrypted,
             name=name or f"API Key {datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}",
-            allowed_providers=allowed_providers,
-            allowed_api_formats=allowed_api_formats,
-            allowed_models=allowed_models,
+            allowed_providers=allowed_providers or None,
+            allowed_api_formats=allowed_api_formats or None,
+            allowed_models=allowed_models or None,
             rate_limit=rate_limit,
             concurrent_limit=concurrent_limit,
             expires_at=expires_at,
@@ -141,8 +142,18 @@ class ApiKeyService:
             "auto_delete_on_expiry",
         ]
 
+        # 允许显式设置为空数组/None 的字段（空数组会转为 None，表示"全部"）
+        nullable_list_fields = {"allowed_providers", "allowed_api_formats", "allowed_models"}
+
         for field, value in kwargs.items():
-            if field in updatable_fields and value is not None:
+            if field not in updatable_fields:
+                continue
+            # 对于 nullable_list_fields，空数组应该转为 None（表示不限制）
+            if field in nullable_list_fields:
+                if value is not None:
+                    # 空数组转为 None（表示允许全部）
+                    setattr(api_key, field, value if value else None)
+            elif value is not None:
                 setattr(api_key, field, value)
 
         api_key.updated_at = datetime.now(timezone.utc)

src/utils/task_coordinator.py

@@ -1,8 +1,16 @@
-"""分布式任务协调器，确保仅有一个 worker 执行特定任务"""
+"""分布式任务协调器，确保仅有一个 worker 执行特定任务
+
+锁清理策略：
+- 单实例模式（默认）：启动时使用原子操作清理旧锁并获取新锁
+- 多实例模式：使用 NX 选项竞争锁，依赖 TTL 处理异常退出
+
+使用方式：
+- 默认行为：启动时清理旧锁（适用于单机部署）
+- 多实例部署：设置 SINGLE_INSTANCE_MODE=false 禁用启动清理
+"""
 
 from __future__ import annotations
 
-import asyncio
 import os
 import pathlib
 import uuid
@@ -19,6 +27,10 @@ except ImportError:  # pragma: no cover - Windows 环境
 class StartupTaskCoordinator:
     """利用 Redis 或文件锁，保证任务只在单个进程/实例中运行"""
 
+    # 类级别标记：在当前进程中是否已尝试过启动清理
+    # 注意：这在 fork 模式下每个 worker 都是独立的
+    _startup_cleanup_attempted = False
+
     def __init__(self, redis_client=None, lock_dir: Optional[str] = None):
         self.redis = redis_client
         self._tokens: Dict[str, str] = {}
@@ -26,6 +38,8 @@ class StartupTaskCoordinator:
         self._lock_dir = pathlib.Path(lock_dir or os.getenv("TASK_LOCK_DIR", "./.locks"))
         if not self._lock_dir.exists():
             self._lock_dir.mkdir(parents=True, exist_ok=True)
+        # 单实例模式：启动时清理旧锁（适用于单机部署，避免残留锁问题）
+        self._single_instance_mode = os.getenv("SINGLE_INSTANCE_MODE", "true").lower() == "true"
 
     def _redis_key(self, name: str) -> str:
         return f"task_lock:{name}"
@@ -36,7 +50,46 @@ class StartupTaskCoordinator:
         if self.redis:
             token = str(uuid.uuid4())
             try:
-                acquired = await self.redis.set(self._redis_key(name), token, nx=True, ex=ttl)
+                if self._single_instance_mode:
+                    # 单实例模式：使用 Lua 脚本原子性地"清理旧锁 + 竞争获取"
+                    # 只有当锁不存在或成功获取时才返回 1
+                    # 这样第一个执行的 worker 会清理旧锁并获取，后续 worker 会正常竞争
+                    script = """
+                    local key = KEYS[1]
+                    local token = ARGV[1]
+                    local ttl = tonumber(ARGV[2])
+                    local startup_key = KEYS[1] .. ':startup'
+
+                    -- 检查是否已有 worker 执行过启动清理
+                    local cleaned = redis.call('GET', startup_key)
+                    if not cleaned then
+                        -- 第一个 worker：删除旧锁，标记已清理
+                        redis.call('DEL', key)
+                        redis.call('SET', startup_key, '1', 'EX', 60)
+                    end
+
+                    -- 尝试获取锁（NX 模式）
+                    local result = redis.call('SET', key, token, 'NX', 'EX', ttl)
+                    if result then
+                        return 1
+                    end
+                    return 0
+                    """
+                    result = await self.redis.eval(
+                        script, 2,
+                        self._redis_key(name), self._redis_key(name),
+                        token, ttl
+                    )
+                    if result == 1:
+                        self._tokens[name] = token
+                        logger.info(f"任务 {name} 通过 Redis 锁独占执行")
+                        return True
+                    return False
+                else:
+                    # 多实例模式：直接使用 NX 选项竞争锁
+                    acquired = await self.redis.set(
+                        self._redis_key(name), token, nx=True, ex=ttl
+                    )
                     if acquired:
                         self._tokens[name] = token
                         logger.info(f"任务 {name} 通过 Redis 锁独占执行")